@ImmutableValue Specification

This annotation declares that instances of this class are immutable and are value objects.

That is, In object-oriented and functional programming:

• An immutable object is an object whose state cannot be modified after it is created.
• A Value object is one where the identity of the object is defined by the state (i.e. fields) of the object itself.

Immutability Contract

This class declares the immutability contract, which is then checked by the JPure compile-time checker.

• Concrete classes inherit @ImmutableValue from any superclass or interface with the annotation.
• The fields on the class must be declared final, and therefore unalterable once set by the constructor.
• The fields must only contain other immutable value objects/primitives (see below).
• Concrete classes inheriting or declaring this annotation must be final.
• Any generic type parameters supplied to an ImmutableValue annotated class must also be immutable value types.
• To ensure thread-safety, arguments to methods on the class must also be immutable.
• Returned values from @ImmutableValue objects can be of any type.
• Any instance (i.e. non-static) methods on the class must be implementation-pure. (see {@link Pure} for what this entails).
• Methods (inherited from a base-class) which are overridden need not be pure.
• The purity (or otherwise) of static methods in the class hierarchy are not affected by this annotation
• Public / Package accessible methods of the class must only take immutable parameters (interface pure).

What Qualifies As An Immutable Value?

Various classes from the Java platform are already immutable, and recognized as such by Pure4J.

• Strings.
• Java primitives and their wrapper classes. e.g. int and Integer
• Instances of other classes labeled @ImmutableValue.
• BigDecimal, BigInteger
• Currency
• Anything extending Throwable. e.g. checked and unchecked exceptions.

Notable Exceptions To Immutable Values

• Arrays.
• Java Collection Classes (use the provided PersistentCollections instead)

Implementing toString() and HashCode()

Clients are warned that toString and hashCode are not pure functions, as they are not deterministic (being dependent on the system hash code, which is based on object id).

• Implementations with the @ImmutableValue annotation will need to implement these.
• AbstractImmutableValue is provided as a convenience class, which can be used to reduce boiler-plate code in implementation classes.

Implementing equals()

equals() by default is pure.

Your code is expected to observe the contract of equals() and not modify the state of the parameter object being passed to it. Unfortunately, this case is not checked by the system.

Exceptions

Exceptions are regarded as being immutable for convenience only. You should not use exceptions for passing system state.

Extending / Using Other Code

Pure4J will check code in your code base, but assume that anything tagged @ImmutableValue in a library has been correctly verified by the build process of that library.