com.surelogic

Annotation Type Mutable

@Documented
@Retention(value=RUNTIME)
@Target(value=TYPE)
public @interface Mutable

The class to which this annotation is applied is mutable, that is, has state that is changeable. This annotation primarily exists for clarifying the mutability of a class that might otherwise be assumed to be immutable, despite the fact that it is a bad idea to assume a class is immutable without good reason.

This annotation is not verified, it is intended for documentation of programmer intent only.

A type may not be annotated with both @Immutable and @Mutable.

Relationship with @ThreadSafe

Thread safety and immutability are two points along the same axis. This set of annotations can actually describe three points along the axis:

@Mutable and @NotThreadSafe

This is the same as being unannotated, or just @Mutable , or just @NotThreadSafe. The type contains mutable state that is not safe to access concurrently from multiple threads.

@Mutable and @ThreadSafe

This is the same as @ThreadSafe. The type contains mutable state that is safe to access concurrently from multiple threads.

@Immutable and @ThreadSafe

This is the same as @Immutable. The type contains no mutable state, and is thus safe to access concurrently from multiple threads.

The combination @Immutable and @NotThreadSafe is a modeling error because an immutable type is obviously thread safe.

Semantics:

Instances of the type to which this annotation is applied have state that can be seen to change by callers.

Examples:

The Aircraft class below is declared to be mutable because its position can be changed. Its implementation is also thread-safe, however, not all mutable classes are also thread-safe.

 @Mutable
 public class Aircraft {
   private final Lock stateLock = new ReentrantLock();
   ...
   @GuardedBy("stateLock")
   private long x, y;
   ...
   public void setPosition(long x, long y) {
     stateLock.lock();
     try {
       this.x = x;
       this.y = y;
     } finally {
       stateLock.unlock();
     }
   }
   ...
 }
 

Javadoc usage notes:

This annotation may placed in Javadoc, which can be useful for Java 1.4 code which does not include language support for annotations, via the @annotate tag.

 /**
  * @annotate Mutable
  */
 public class Aircraft {
   ...
 }
 

See Also:

Immutable