Package ch.elca.el4j.util.concurrency

Class, field, and method level annotations for describing thread-safety policies.


Annotation Types Summary
GuardedBy The field or method to which this annotation is applied can only be accessed when holding a particular lock, which may be a built-in (synchronization) lock, or may be an explicit java.util.concurrent.Lock.
Immutable The class to which this annotation is applied is immutable.
NotThreadSafe The class to which this annotation is applied is not thread-safe.
ThreadSafe The class to which this annotation is applied is thread-safe.

Package ch.elca.el4j.util.concurrency Description

Class, field, and method level annotations for describing thread-safety policies.

These annotations are copied from this book: in order to place them in a proper package. Please refer also to the book Effective Java, 2nd edition, Item 70.

Three class-level annotations describe the intended thread-safety promises of a class: @Immutable, @ThreadSafe, and @NotThreadSafe. @Immutable means that the class is immutable, and implies @ThreadSafe. @NotThreadSafe is optional; if a class is not annotated as thread-safe, it should be presumed not to be thread-safe, but if you want to make it extra clear, use @NotThreadSafe.

These annotations are relatively unintrusive and are beneficial to both users and maintainers. Users can see immediately whether a class is thread-safe, and maintainers can see immediately whether thread-safety guarantees must be preserved. Annotations are also useful to a third constituency: tools. Static code-analysis tools may be able to verify that the code complies with the contract indicated by the annotation, such as verifying that a class annotated with @Immutable actually is immutable.

Field and method annotations

The class-level annotations above are part of the public documentation for the class. Other aspects of a class's thread-safety strategy are entirely for maintainers and are not part of its public documentation.

Classes that use locking should document which state variables are guarded with which locks, and which locks are used to guard those variables. A common source of inadvertent non-thread-safety is when a thread-safe class consistently uses locking to guard its state, but is later modified to add either new state variables that are not adequately guarded by locking, or new methods that do not use locking properly to guard the existing state variables. Documenting which variables are guarded by which locks can help prevent both types of omissions.

The @GuardedBy(lock) annotation documents that a field or method should be accessed only with a specific lock held.

Copyright and license

This software is copyright (c) 2005 Brian Goetz and Tim Peierls and is released under the Creative Commons Attribution License ( The official home for this software is Any republication or derived work distributed in source code form must include the copyright and license notice.

Links to wiki:

Copyright © 2005-2011 ELCA. All Rights Reserved.