`@MutableUnshared` Specification

Declares that instances of this class contain mutable state, which, in order to preserve the no-side-effects clause of the purity contract, will not be shared with other classes during pure method calls.

The typical use case for objects marked with this annotation is likely to be collectors, iterators, enumerations and some types of inner class, where the scope of use is limited to within a single pure method.

Contract

Concrete classes inherit @UnsharedImmutable from any superclass or interface with the annotation.
Public / Package accessible fields of the class must be immutable (see: {@link ImmutableValue} for what qualifies).
Public / Package accessible methods must only receive immutable parameters. (interface purity).
Public / Package accessible methods must only return immutable values as results. (The one exception is returning this, which is allowed for convenience building fluent APIs).
Mutable Unshared objects are not thread-safe. If you use them in multiple threads, you are likely to end up with a non-deterministic state.

Inner Classes (non-static)

In Java, inner classes will be constructed with a reference to their parent class. Because of the rule on non-static arguments, any parent class must be immutable.

Covariant Return Types

Since there is a requirement that values leaving the @MutableUnshared instances must be immutable (to prevent sharing of state, and thus, side-effects) you can use covariant return types to narrow the result of a method. For example, if you are implementing an interface like:

		interface Result {
		
			Object get();
			
		}

You can elect to return a narrower result such as:

		public SomeImmutableValue get() {
			// blah
		}

Runtime Return Value Checking

If it is not possible to narrow the result in this way (perhaps you are using generics) you can check the result at runtime. This can be done in the following way:

		public Object someNonImmutableReturnMethod() {
			return Pure4J.returnImmutable(new ImmutableObjectOfSomeKind());
		}

Libraries