...
| Code Block | ||
|---|---|---|
| ||
@Immutable
public final class Point {
private final int f_x;
private final int f_y;
public Point(int x, int y) {
f_x = x;
f_y = y;
}
public int getX() {
return f_x;
}
public int getY() {
return f_y;
}
}
|
| Wiki Markup |
|---|
"It is not necessary to document the immutability of {{enum}} types. Unless it is obvious from the return type,static factories must document the thread safety of the returned object, as demonstrated by {{Collections.synchronizedMap}}." \[[Bloch 08|AA. Java References#Bloch 08]\]. |
@NotThreadSafe This annotation is applied to classes that are not thread-safe. Several classes do not document whether they are safe for multithreaded use or not. Consequently, a programmer has no easy way to determine whether the class is thread-safe. This annotation provides clear indication of the class's lack of thread-safety.
...
| Wiki Markup |
|---|
"A state-dependent class should either fully expose (and document) its waiting and notification protocols to subclasses, or prevent subclasses from participating in them at all. (This is an extension of "design and document for inheritance, or else prohibit it" \[EJ Item 15\].) At the very least, designing a state-dependent class for inheritance requires exposing the condition queues and locks and documenting the condition predicates and synchronization policy; it may also require exposing the underlying state variables. (The worst thing a state-dependent class can do is expose its state to subclasses but not document its protocols for waiting and notification; this is like a class exposing its state variables but not documenting its invariants.)". \[[Goetz 06, pg 395|AA. Java References#Goetz 06]\] |
Wait-notify protocols should be adequately documented. Currently, we are not aware of any annotations for this purpose.
Risk Assessment
Failing to document thread-safety and not annotating concurrent code can make detection and prevention of race conditions and data races relatively difficult.
Rule | Severity | Likelihood | Remediation Cost | Priority | Level |
|---|---|---|---|---|---|
CON33- J | low | probable | medium | P4 | L2 |
Related Vulnerabilities
Search for vulnerabilities resulting from the violation of this rule on the CERT website.
References
| Wiki Markup |
|---|
\[[Bloch 08|AA. Java References#Bloch 08]\] Item 70: "Document thread safety"
\[[Goetz 06|AA. Java References#Goetz 06]\] |
...
11. Concurrency (CON) 11. Concurrency (CON) CON02-J. Always synchronize on the appropriate object