Java Reference
In-Depth Information
Bibliography
[Bloch 2008]
Item 70, “Document Thread Safety”
[Goetz 2006]
Java Concurrency in Practice
[Long 2012]
TSM01-J. Do not let the
this
reference escape during object construction
[Sutherland 2010]
“Composable Thread Coloring”
26. Always provide feedback about the resulting value of a method
Methods should be designed to return a value that allows the developer to learn about the
current state of the object and/or the result of an operation. This advice is consistent with
The CERT
®
Oracle
®
Secure Coding Standard for Java
™
[Long2012],“EXP00-J.Donot
ignore values returned by methods.” The returned value should be representative of the
last known state and should be chosen keeping in mind the perceptions and mental model
of the developer.
Feedbackcanalsobeprovidedbythrowingeitherstandardorcustomexceptionobjects
derived from the
Exception
class. With this approach, the developer can still get precise
information about the outcome of the method and proceed to take the necessary actions.
Todoso,theexception shouldprovideadetailed accountoftheabnormalconditionatthe
appropriate abstraction level.
APIs should use a combination of these approaches, both to help clients distinguish
correct results from incorrect ones and to encourage careful handling of any incorrect res-
ults. In cases where there is a commonly accepted error value that cannot be misinter-
preted as a valid return value for the method, that error value should be returned; and in
othercasesanexceptionshouldbethrown.Amethodmustnotreturnavaluethatcanhold
both valid return data and an error code; see
Guideline 52
,
“
Avoid in-band error indicat-
Alternatively, an object can provide a state-testing method [Bloch 2008] that checks
whether the object is in a consistent state. This approach is useful only in cases where the
object'sstatecannotbemodifiedbyexternalthreads.Thispreventsatime-of-check,time-
of-use (TOCTOU) race condition between invocation of the object's state-testing method
