com.surelogic
Annotation Type NotThreadSafe

@Documented
@Target(value=TYPE)
public @interface NotThreadSafe

The type to which this annotation is applied is not thread-safe. This annotation primarily exists for clarifying the non-thread-safety of a class that might otherwise be assumed to be thread-safe, despite the fact that it is a bad idea to assume a class is thread-safe without good reason.

This annotation is trusted, i.e., it is not verified. Its use is for documentation.

A type may not be annotated with both @ThreadSafe and @NotThreadSafe.

Relationship with @Immutable

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:

Documenting that a type is not thread-safe does not constrain the implementation of the program, it simply clarifies the programmer's intent.

Examples:

Most of the collection implementations provided in java.util are not thread-safe. This could be documented for java.util.ArrayList, for example, as shown below.

 package java.util;
 
 @NotThreadSafe
 public class ArrayList extends ... {
   ...
 }
 

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 NotThreadSafe
  */
 public class ArrayList extends ... {
   ...
 }
 

Implementation note: This annotation is derived from @NotThreadSafe proposed by Brian Goetz and Tim Peierls in the book Java Concurrency in Practice (Addison-Wesley 2006) we have simply adapted it to have semantics as a promise. Further, the annotation in net.jcip.annotations may be used instead of this one with the same tool behavior. One difference between the two annotations is that the the annotation in net.jcip.annotations has retention policy of RetentionPolicy.RUNTIME while the annotation in com.surelogic has a retention policy of RetentionPolicy.CLASS.

See Also:

ThreadSafe