Related to this, is HttpCore which switch from JCIP style annotations (4.x)
to @Contract (5.x). I'll ask that ML for the reason/experience.
Gary
On Wed, Apr 19, 2017 at 12:14 PM, Oliver Heger <oliver.he...@oliver-heger.de
> wrote:
>
>
> Am 19.04.2017 um 14:06 schrieb Gilles:
> > On Wed, 19 Apr 2017 09:17:32 +0200, Emmanuel Bourg wrote:
> >> Le 19/04/2017 à 00:23, Gary Gregory a écrit :
> >>
> >>> I'd like to see a real example before we talk about abstract
> >>> arguments and
> >>> counter-arguments, which will never end ;-)
> >>
> >> Ok,
> >
> > Good. [If only...] ;-)
> >
> >> here is a slightly more substantial example. The following class is
> >> immutable but not thread-safe:
> >>
> >> public class FileAppender {
> >> private final File file;
> >>
> >> public FileAppender(File file) {
> >> this.file = file;
> >> }
> >>
> >> public void append(String message) throws IOException {
> >> try (OutputStream out = new FileOutputStream(file)) {
> >> out.write(message.getBytes());
> >> }
> >> }
> >> }
> >>
> >> The point is, if the class operates on resources outside the JVM, the
> >> immutability doesn't ensure the thread safety. Immutability is only a
> >> thread safety guarantee for data structures, and not for classes with
> >> operations causing side effects (like writing to files, drawing on the
> >> screen, playing sounds, calling remote services, accessing off-heap
> >> memory, etc).
> >
> > The consequence should thus be that such classes should not be
> > documented as thread-safe _because_ such a qualifier would not
> > bring any actual benefit to the user.
> >
> > Documenting/annotating a class as "immutable" or "thread-safe"
> > must be a _promise_ to the user, and it requires more analysis
> > than recognizing that all the fields are final.
> >
> > To return to the question of which annotation, I'm unfazed by
> > the possibility of
> > @ThreadSafe
> > @NotThreadSafe
> > because it is an obvious documentation bug, with no more dire
> > consequences than saying
> > @ThreadSafe
> > when, in fact, it is not.
> >
> I agree. Let's not forget that the annotations are intended as a tool
> for documentation. The main responsibility is on the author who is using
> them.
>
> We should not try to be too clever here, especially as we have no way to
> prevent real documentation errors: classes being marked as @ThreadSafe
> although they are not, or originally thread-safe classes which are later
> modified in a way that breaks their thread-safety.
>
> Oliver
>
> >
> > Gilles
> >
> >>
> >> Emmanuel Bourg
> >>
> >>
> >
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> > For additional commands, e-mail: dev-h...@commons.apache.org
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> For additional commands, e-mail: dev-h...@commons.apache.org
>
>
--
E-Mail: garydgreg...@gmail.com | ggreg...@apache.org
Java Persistence with Hibernate, Second Edition
<https://www.amazon.com/gp/product/1617290459/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1617290459&linkCode=as2&tag=garygregory-20&linkId=cadb800f39946ec62ea2b1af9fe6a2b8>
<http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1617290459>
JUnit in Action, Second Edition
<https://www.amazon.com/gp/product/1935182021/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182021&linkCode=as2&tag=garygregory-20&linkId=31ecd1f6b6d1eaf8886ac902a24de418%22>
<http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1935182021>
Spring Batch in Action
<https://www.amazon.com/gp/product/1935182951/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182951&linkCode=%7B%7BlinkCode%7D%7D&tag=garygregory-20&linkId=%7B%7Blink_id%7D%7D%22%3ESpring+Batch+in+Action>
<http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1935182951>
Blog: http://garygregory.wordpress.com
Home: http://garygregory.com/
Tweet! http://twitter.com/GaryGregory
