@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

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

You can use @MutableUnshared annotated classes from another project or library. The classes are assumed to have been purity-checked.