Documenting and Verifying Thread Safety: Javadoc, Annotations, Static Analysis, and ArchUnit

When an instance method carries the synchronized keyword, the instance itself becomes the lock. Even if several threads call synchronized methods on the same instance at the same time, only one thread can enter. The others wait until the first thread leaves the method. A static synchronized method uses the Class object of its class as the lock. So synchronized is a clue to thread safety, and it would seem useful to show it in Javadoc. Javadoc, however, does not print the synchronized keyword in method declarations. Synchronization is considered an implementation detail, not a contract to expose in the API documentation. Item 82 of Effective Java, Third Edition, defends this policy on the same grounds.

synchronized on a method declaration is equivalent to wrapping the whole method body in a synchronized(this) block. That is, the following code

does the same thing as this code:

As the implementation improves, the synchronized region may shrink to part of the method, or a separate lock object may replace this. Such implementation details change more often than the external interface. It is also hard to show every lock-protected region in the method declaration. Some classes synchronize internally with java.util.concurrent.locks.Lock or CAS (Compare And Swap) operations. The presence or absence of the synchronized keyword therefore cannot be the only criterion for thread safety.

In a multithreaded environment, each method call may be safe on its own while a combination of calls is not. For example, a HashMap that is safely published after construction (for instance, through a final field or a volatile variable) and never modified afterward can be read with get() from several threads without problems. But if one thread changes its structure with put() while another calls get(), the result is not guaranteed. The same applies to Hashtable, whose public methods are all synchronized or delegate to synchronized methods and views, and to a Map wrapped with Collections.synchronizedMap(). When two calls are combined, such as checking with containsKey() and then calling put(), a race condition occurs unless the caller holds a lock externally.

What needs documenting, then, is not whether methods are synchronized but under what conditions the class is safe. Since Javadoc has no convention for this, developers have to write it in the class description themselves. The Effective Java classification in the next section provides the criteria.

Item 82 of Effective Java, Third Edition, "Document thread safety" (Item 70 in the Second Edition), recommends documenting thread safety in five levels.

Here are three examples of where and how the Java standard library and Spring Batch describe thread safety.

Apache HttpClient 5 defines a single annotation for thread safety, org.apache.hc.core5.annotation.Contract. Its threading attribute takes a value of the ThreadingBehavior enum.

In the HttpClient 5.5 source, the main classes are declared as follows.

SAFE_CONDITIONAL has a name similar to "conditionally thread-safe" in Effective Java, but it means something different. The Effective Java classification is about which sequences of method calls need external synchronization, while the HttpClient value is about whether the dependencies received through the constructor are thread-safe.

@Contract carries the @Documented meta-annotation, so it appears in the class declaration in Javadoc. Below is the Javadoc for BasicHttpClientConnectionManager.

Because it always appears in the same place, thread safety is visible at a glance. The class description also says "this class is fully thread-safe", but the annotation in the declaration catches the eye first.

HttpClient did not start with its own annotation. Up to HttpClient 4.5.2, HttpGet and the classes from the 5.5 example above were declared with @NotThreadSafe and @ThreadSafe, as shown below.

These annotations lived in the org.apache.http.annotation package, and their Javadoc said they originated in the book "Java Concurrency in Practice". Because of a licensing issue with the original JCIP library, discussed below, HttpCore 4.4.5 removed these four annotations, and HttpClient has used @Contract since 4.5.3.

Each project can define its own annotations, as HttpClient did. Using annotations from widely adopted open source, however, spares users from learning something new. SpotBugs and IntelliJ IDEA, covered later, include the JCIP package in their default lists of recognized annotations. The JCIP annotations that HttpClient 4.x borrowed are the starting point for such shared annotations.

The JCIP annotations are the thread safety annotations proposed in Appendix A of "Java Concurrency in Practice". There are four:

The first three annotations tell users about the class’s contract, and @GuardedBy tells maintainers of the class which lock to respect.

Effective Java, Second Edition (2008) came out after JCIP (2006) and explains its five levels by comparing them with the JCIP annotations. Lining up the two classifications, the four levels other than thread-hostile map onto the three class-level JCIP annotations. Unconditionally thread-safe and conditionally thread-safe are both covered by @ThreadSafe.

In short, Effective Java divides classes into five levels by how much external synchronization users need. JCIP uses a safe-or-not dichotomy with immutability added as a special case, and separates information for maintainers into @GuardedBy. Section 4.5 of JCIP, "Documenting synchronization policies", recommends documenting thread safety guarantees for users and synchronization policies for maintainers.

The original library distributed with the JCIP book is net.jcip:jcip-annotations:1.0 on Maven Central. Its license, however, is Creative Commons Attribution, a license that the Creative Commons foundation itself does not recommend for software. That led to com.github.stephenc.jcip:jcip-annotations:1.0-1, a reimplementation of the same API under the Apache License 2.0. The two libraries share the package name (net.jcip.annotations) and the annotation names.

The JCIP annotations have also been copied into several other projects. The following libraries use the same annotation names in different packages.

The original JCIP library is hard to recommend for new projects because of its license, and JSR-305 because its standardization was abandoned. Instead, considering the coverage of the static analysis tools in the next section, I recommend one of the following two libraries.

SpotBugs, the successor to FindBugs, has one bug pattern for the JCIP annotations, and it is for @Immutable. @GuardedBy and @ThreadSafe have no dedicated checks. Instead, a detector that looks for inconsistently synchronized fields reads them as input to its judgment. SpotBugs recognizes three packages:

The JCIP_FIELD_ISNT_FINAL_IN_IMMUTABLE_CLASS bug pattern, which dates back to FindBugs 2.0, warns when a class annotated with @Immutable has a field that is not final. The SpotBugs 4.10.4 implementation, however, excludes transient and volatile fields from this check.

Create a class declared @Immutable that nevertheless has a setter,

configure the SpotBugs plugin in Gradle,

and run ./gradlew :spotbugs:spotbugsMain. The report contains this line:

The example sets ignoreFailures to true so that the report is printed in full even when there are warnings. To fail the build on violations in real CI, change this setting to false or omit it.

@GuardedBy is handled by the IS_FIELD_NOT_GUARDED bug pattern. This pattern, however, does not find violations by looking at the annotation. The IS2_INCONSISTENT_SYNC detector estimates missing synchronization from the proportion of field accesses made while holding a lock. When a field carries @GuardedBy("this"), the detector treats it differently in three ways:

The only value it recognizes is "this". The detector treats fields where less than half of the accesses hold the lock as likely false positives and lowers their priority.

That is why Counter in the same project is not reported with the default settings, even though it modifies a @GuardedBy("this") field without a lock. The read and write in increment() happen without a lock, and only the read in the synchronized method get() holds it. One of three accesses, or 33%, holds the lock. Only when you make the example report low-priority warnings too with ./gradlew :spotbugs:spotbugsMain -PreportLow does it appear.

The class below has the same violation plus two more synchronized methods, which brings the locked accesses to 60%.

This class is reported with high priority even with the default settings. The first letter of the output is the priority and the second is the category.

The same detector also reads @ThreadSafe and @NotThreadSafe. It excludes fields of @NotThreadSafe classes from the check and uses @ThreadSafe on a class as grounds for raising the warning priority of its fields. It does not verify that the contract declared by the annotation is kept. A class declared @ThreadSafe can hold a field of a @NotThreadSafe type without a warning.

In short, the only thing SpotBugs checks deterministically from annotations alone is the final rule for @Immutable classes. @GuardedBy violations are also reported as estimates based on the proportion of locked accesses; the annotation only changes the candidates and priority of that estimate.

Google’s Error Prone plugs into javac and checks rules that prevent errors at compile time.

IntelliJ IDEA 2026.2 has six inspections in the Concurrency annotation issues group. Five are for @GuardedBy and one is for @Immutable. No inspection verifies contracts declared with @ThreadSafe.

The Unguarded field access or method call inspection recognizes @GuardedBy from all of these packages:

SpotBugs also reads the original JCIP package, but it handles only @GuardedBy("this") and stops at warnings guessed from access proportions. IntelliJ, by comparison, directly checks the guard expressions of the original JCIP annotation.

The Non-final field in @Immutable class inspection warns when an @Immutable class has a field that is not final. It does not check whether field types are mutable, so its depth is closer to SpotBugs than to Error Prone. Unlike SpotBugs, though, it also warns about transient and volatile fields. The markers this inspection recognizes are:

@ThreadSafe is read only as a hint by the Access to static field locked on instance inspection in the "Threading issues" group. This inspection warns when code holding an instance lock accesses a non-constant static field. If the accessed field is final, it checks the annotations on the field’s declared type and skips the warning if a registered thread safety annotation is present. It therefore does not verify the contract of the annotated class itself. The default list contains these annotations:

Error Prone’s @ThreadSafe is not in the default list.

However, the inspection registrations in IntelliJ IDEA 2026.2 declare every inspection in the "Concurrency annotation issues" group with enabledByDefault="false" and level="WARNING". You have to turn them on yourself under Settings | Editor | Inspections | Java | Concurrency annotation issues. Even when enabled, they are editor warnings and cannot block javac compilation the way Error Prone does. Enforcing them in CI requires a separate runner such as Qodana. Qodana is a code quality platform from JetBrains that runs the same inspections as IntelliJ IDEA in CI, as a Docker image or a command-line tool. You enable the checks in a Qodana profile and set a failure condition.

Across the three tools, the range checked deterministically from annotations alone is narrow.

This is why I recommended either error_prone_annotations or jcip-annotations earlier. If you need checks that block compilation, use annotations that Error Prone recognizes. If you want to mark all four annotations and still get checks from your IDE and SpotBugs, use the net.jcip.annotations package (the Apache-licensed reimplementation).

The example has a class annotated with @NotThreadSafe and a controller that holds it as a field. The controller also has a SimpleDateFormat field. The full project is in examples/thread-safety-archunit.

The ArchUnit test consists of two rules.

The first rule fails if the type of any field in a class annotated with @RestController carries @NotThreadSafe, without separately analyzing external synchronization or bean scope. ArchUnit reads annotations from bytecode. It can therefore check annotations with RUNTIME retention, such as the original JCIP annotations, as well as those with CLASS retention, such as the JSR-305 annotations and HttpClient’s @Contract. The example rule looks only at net.jcip.annotations.NotThreadSafe, though, so checking annotations from other packages or the threading value of @Contract requires additional conditions. Library classes outside the analyzed packages are also read from the classpath under the default settings, so the same rule can check @NotThreadSafe that a library has applied.

The second rule is for JDK classes that carry no thread safety annotation, such as SimpleDateFormat. It lists Format, Calendar, and StringBuilder explicitly.

Running ./gradlew test with ArchUnit 1.5.0, Spring Web 7.0.9, JUnit 6.1.3, and JDK 25 fails both rules and reports which field broke each rule.

HealthController in the same project, which holds only Clock and DateTimeFormatter as fields, passed both rules.

ReportController, caught by the rules, can be fixed by holding the immutable DateTimeFormatter as a field instead of SimpleDateFormat, and by confining ReportFormatter to a local variable of the request-handling method.

After changing ReportController this way and running the test again, both rules pass. ReportFormatter is created anew on each call and is not shared with other request threads. Passing the rules, however, does not prove the thread safety of the whole controller. Other shared state and race conditions in sequences of method calls need separate review.

This approach also has limits.