Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id BFCEC200BDC for ; Wed, 30 Nov 2016 05:04:33 +0100 (CET) Received: by cust-asf.ponee.io (Postfix) id BE68D160B23; Wed, 30 Nov 2016 04:04:33 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 91527160B15 for ; Wed, 30 Nov 2016 05:04:32 +0100 (CET) Received: (qmail 41947 invoked by uid 500); 30 Nov 2016 04:04:31 -0000 Mailing-List: contact dev-help@commons.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: "Commons Developers List" Delivered-To: mailing list dev@commons.apache.org Received: (qmail 41902 invoked by uid 99); 30 Nov 2016 04:04:31 -0000 Received: from pnap-us-west-generic-nat.apache.org (HELO spamd1-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 30 Nov 2016 04:04:31 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd1-us-west.apache.org (ASF Mail Server at spamd1-us-west.apache.org) with ESMTP id ACC5FC1A25 for ; Wed, 30 Nov 2016 04:04:30 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd1-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: 3.149 X-Spam-Level: *** X-Spam-Status: No, score=3.149 tagged_above=-999 required=6.31 tests=[DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, FREEMAIL_REPLY=1, HTML_MESSAGE=2, KAM_LOTSOFHASH=0.25, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=disabled Authentication-Results: spamd1-us-west.apache.org (amavisd-new); dkim=pass (2048-bit key) header.d=gmail.com Received: from mx1-lw-us.apache.org ([10.40.0.8]) by localhost (spamd1-us-west.apache.org [10.40.0.7]) (amavisd-new, port 10024) with ESMTP id x83NDC4jmJcZ for ; Wed, 30 Nov 2016 04:04:27 +0000 (UTC) Received: from mail-io0-f181.google.com (mail-io0-f181.google.com [209.85.223.181]) by mx1-lw-us.apache.org (ASF Mail Server at mx1-lw-us.apache.org) with ESMTPS id 9C1C65F5FC for ; Wed, 30 Nov 2016 04:04:27 +0000 (UTC) Received: by mail-io0-f181.google.com with SMTP id j65so328752156iof.0 for ; Tue, 29 Nov 2016 20:04:27 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:from:date:message-id:subject:to; bh=7Tm/RNZmaXhKIISS/1Mb/rsMYWcW0YcddH9jaspBCp4=; b=0uf25oJMnNFq2RAhWa8HZ7HEAgozvCz1qUrcC5fEOKnORFboNoMRhQJ4r3NUuj/FG6 x8LQFGJx5dOH7u4+6uiV02z1GxhUDkFyxEkzTqP37SR7U/fz6vv5rNRAqto+eBVojTFI 7+Gwd0YKoVgQ02/BPY3KOiSY38New6uI9Mqz2LM4CMFmZbvuvUF0JFnmdNayvZvu102f qBoWbzhnQfu/BtCQvRrZpBVkJS/mFs4C1pFqx2R/QucSNlh2EdTxjyvWwJL3Ne8dHPec BoDFyjGz0JyxW1Po+pZxUm0r+GQ5vNw1R5/w6ab+eP8grqf5VDKeAt943zzb0okqS0rP IQvA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:in-reply-to:references:from:date :message-id:subject:to; bh=7Tm/RNZmaXhKIISS/1Mb/rsMYWcW0YcddH9jaspBCp4=; b=XJ5oBbkWnJKhw/u+tWgJxFcWw4iTFg7AmwafRuMdw0RFCP3CjzoKlLxd/f2Zcwaeb7 m5IIqjbFdwe3ObrdNxQzB5y6JEGk5TseGFgawGdTSjMN+AO3TZ5ZeX5MQ7WYEKrVoXLa JHqtXV4UlloKw7nsN3mWs1BQgzvme43enka9IxdAZD4eN/8hD+iFVFdeFkLWgIqJ52lm 5XnuKP9lCjAM/UW37uL38Oz5JvKXT9iROKN81QIiHqomdrNBP0hhP/iMrtLIfQ4Q/nUK RYgdqilcrWC3xIunzp3IrE7NB7Xf9iCjMCMJ7cPBxrd1PfquIC5PXt25z88K6T+2k2Nu yBjQ== X-Gm-Message-State: AKaTC00p6rpi0BX7d3RRm/w+P77DyTgecXNEpVVevIVERpcUP5XKNXC9UHdYjNP3wLKpbK89JTuWKtddEUpATQ== X-Received: by 10.36.50.214 with SMTP id j205mr26890950ita.33.1480478650616; Tue, 29 Nov 2016 20:04:10 -0800 (PST) MIME-Version: 1.0 Received: by 10.79.142.157 with HTTP; Tue, 29 Nov 2016 20:04:09 -0800 (PST) In-Reply-To: References: <126afd86-1b8c-517f-9185-e4bf3289dc95@oliver-heger.de> From: Matt Sicker Date: Tue, 29 Nov 2016 22:04:09 -0600 Message-ID: Subject: Re: [lang] Thread safety annotations To: Commons Developers List Content-Type: multipart/alternative; boundary=001a114aab8c11512c05427ccc30 archived-at: Wed, 30 Nov 2016 04:04:33 -0000 --001a114aab8c11512c05427ccc30 Content-Type: text/plain; charset=UTF-8 That's pretty neat. So it looks like two competing styles of annotations here would be separate annotations for each concern, a single annotation with an enum, or even separate annotations with boolean values or enums (though that gets a little more complex come to think of it). If only the JDK had an annotation for this. On 29 November 2016 at 20:41, Gary Gregory wrote: > And an example: > > /** > * HTTP/2 compatible extension of {@link RequestConnControl}. > * > * @since 5.0 > */ > @Contract(threading = ThreadingBehavior.IMMUTABLE) > public class H2RequestConnControl extends RequestConnControl { > ... > > Gary > > On Tue, Nov 29, 2016 at 6:40 PM, Gary Gregory > wrote: > > > FYI, this is how we're going to do it in HttpComponents 5: > > https://svn.apache.org/repos/asf/httpcomponents/ > > httpcore/trunk/httpcore5/src/main/java/org/apache/hc/core5/ > > annotation/ThreadingBehavior.java > > > > Gary > > > > On Tue, Nov 29, 2016 at 2:20 PM, Gary Gregory > > wrote: > > > >> On Tue, Nov 29, 2016 at 1:59 PM, Benedikt Ritter > >> wrote: > >> > >>> I agree with Oliver. I don't think we have consensus about if and how > we > >>> want to implement this. Does it even make sense to try to document > this? > >>> What value does such a documentation have, when it is wrong 50% of the > >>> time? I just sumed up the feedback I got from one (!) user at the > >>> conference. I think this needs more thought. This is why I suggested to > >>> create a PR instead of committing this directly to master. > >>> > >> > >> This is a good discussion. Let's keep in mind the audience for these new > >> annotations: > >> > >> - Commons Lang > >> - All of Commons > >> - Any Java code. > >> > >> Just because we may not get to document thread safety properly in > Commons > >> Lang does not mean that any other developers will fail similarly. > >> > >> My goal is not to decorate all of Commons Lang with these new > annotations > >> and certainly not to take on the task of documenting all of Commons ;-) > >> > >> I look at these annotations as a tool, a Commons way of using > annotations > >> where some folks best see fit. > >> > >> Providing these annotations is one thing, using them another ;-) > >> > >> Gary > >> > >> > >>> > >>> Regards. > >>> Benedikt > >>> > >>> Gary Gregory schrieb am Di. 29. Nov. 2016 um > >>> 22:33: > >>> > >>> > On Tue, Nov 29, 2016 at 1:12 PM, Oliver Heger < > >>> > oliver.heger@oliver-heger.de> > >>> > wrote: > >>> > > >>> > > > >>> > > > >>> > > Am 28.11.2016 um 22:28 schrieb Gary Gregory: > >>> > > > WRT licensing, I re-implemented the annotations in git master. > >>> Notice > >>> > > that > >>> > > > all Javadocs are different and much simpler for now. Feel free to > >>> write > >>> > > > more. > >>> > > > >>> > > As the length of this thread shows, using annotations for the > >>> purpose of > >>> > > documenting thread-safety can be a controversial topic. > >>> > > > >>> > > >>> > How is the length of a thread a reflection of its controversy? > >>> > > >>> > > >>> > > I do not see the advantage over a plain text documentation in > >>> Javadoc. > >>> > > Written text can even be more comprehensive. > >>> > > > >>> > > >>> > One does not exclude the other. Annotations are easy to search. Text > in > >>> > Javadoc is subject to typos and formatting oddities that makes it > much > >>> > harder to search. > >>> > > >>> > Tools can work with annotations. > >>> > > >>> > > >>> > > > >>> > > The risk that the documentation goes out of sync with the > >>> implementation > >>> > > is given in both scenarios. But if a class announced as thread-safe > >>> is > >>> > > manipulated in a way that it is no longer thread-safe, I would > >>> consider > >>> > > this as a bug. This is also a kind of backwards-incompatible > change. > >>> > > > >>> > > >>> > That has nothing to do with annotations. If we change behavior in > some > >>> > incompatible way, that's the bug. > >>> > > >>> > I can interpret what you wrote as: If I remove an @Override > annotation, > >>> > then that is backwards-incompatible change. That sounds extreme. > >>> > > >>> > I do not think we have talked about annotations in the context of > >>> backwards > >>> > compatibility. Does this deserve a separate discussion? > >>> > > >>> > a third penny, > >>> > Gary > >>> > > >>> > > >>> > > > >>> > > My 2 cents > >>> > > Oliver > >>> > > > >>> > > > > >>> > > > Gary > >>> > > > > >>> > > > On Mon, Nov 28, 2016 at 12:55 PM, Gary Gregory < > >>> garydgregory@gmail.com > >>> > > > >>> > > > wrote: > >>> > > > > >>> > > >> On Mon, Nov 28, 2016 at 12:18 PM, Matt Benson < > >>> gudnabrsam@gmail.com> > >>> > > >> wrote: > >>> > > >> > >>> > > >>> I hoped to stay out of this. :) Points: > >>> > > >>> > >>> > > >>> * "provided" scope is another Maven mechanism that compiles > >>> against a > >>> > > >>> given dependency but does not pull the dependency in as a > runtime > >>> > > >>> dependency. I personally prefer it to marking a dependency > >>> optional. > >>> > > >>> * For annotations with only classfile retention, a future > package > >>> > > >>> rename e.g. lang4 would not require a consumer to upgrade just > >>> for > >>> > the > >>> > > >>> renamed annotation, though nothing would stop them from doing > >>> so. A > >>> > > >>> given project could depend on either or both of lang3 and lang4 > >>> in > >>> > any > >>> > > >>> combination of compile-only or runtime-inclusive scope with no > >>> > > >>> problems. > >>> > > >>> * A standalone annotations component might be interesting, but > >>> I'm > >>> > not > >>> > > >>> sure if the proposed annotations constitute a critical mass > >>> adequate > >>> > > >>> to justify it. > >>> > > >>> > >>> > > >> > >>> > > >> I would have a hard time justifying a commons-lang3-annotations > >>> module > >>> > > >> with only these 4 annotations. > >>> > > >> > >>> > > >> I could see having a Commons Annotations component though which > >>> for > >>> > good > >>> > > >> or bad would hold all annotations one could imagine having the > >>> Commons > >>> > > >> world. Hm... it smells a bit though... > >>> > > >> > >>> > > >> Gary > >>> > > >> > >>> > > >> > >>> > > >>> > >>> > > >>> Matt > >>> > > >>> > >>> > > >>> On Mon, Nov 28, 2016 at 1:21 PM, Pascal Schumacher > >>> > > >>> wrote: > >>> > > >>>> Groovy had to change the license of its documentation from > CC-A > >>> 3.0 > >>> > to > >>> > > >>> the > >>> > > >>>> Apache License during incubation: > >>> > > >>>> > >>> > > >>>> https://issues.apache.org/jira/browse/LEGAL-167 > >>> > > >>>> http://markmail.org/message/2e7tehlwtpx625q4 > >>> > > >>>> https://issues.apache.org/jira/browse/GROOVY-7470 > >>> > > >>>> > >>> > > >>>> So I guess Commons is probably not allowed to use these files. > >>> > > >>>> > >>> > > >>>> > >>> > > >>>> Am 28.11.2016 um 18:58 schrieb Gary Gregory: > >>> > > >>>>> > >>> > > >>>>> On Mon, Nov 28, 2016 at 7:15 AM, Jochen Wiedmann > >>> > > >>>>> > >>> > > >>>>> wrote: > >>> > > >>>>> > >>> > > >>>>>> On Mon, Nov 28, 2016 at 4:06 PM, sebb > >>> wrote: > >>> > > >>>>>> > >>> > > >>>>>>> The code would not run without the JCIP jar. > >>> > > >>>>>> > >>> > > >>>>>> Are there licensing issues regarding that jar? > >>> > > >>>>>> > >>> > > >>>>> Hm, according to https://www.apache.org/legal/resolved.html, > >>> the > >>> > > >>> license > >>> > > >>>>> "Creative Commons Attribution (CC-A) 2.5" is discussed in the > >>> > section > >>> > > >>> "HOW > >>> > > >>>>> SHOULD "WEAK COPYLEFT" LICENSES BE HANDLED?" > >>> > > >>>>> > >>> > > >>>>> It looks like we might have an issue but this is not clear to > >>> me as > >>> > > >>> IANAL. > >>> > > >>>>> I you look at the license summary > >>> > > >>>>> https://creativecommons.org/licenses/by/2.5/ it sure seems > >>> OK, but > >>> > > our > >>> > > >>>>> resolved.html has this license on a list of licenses to watch > >>> out > >>> > > for. > >>> > > >>>>> > >>> > > >>>>> So to be on the safe side, how do we best re-implement these? > >>> The > >>> > > >>>>> annotation names we can keep as is but I would imagine that > >>> we'd > >>> > want > >>> > > >>> to > >>> > > >>>>> re-write the Javadoc from scratch. > >>> > > >>>>> > >>> > > >>>>> Thoughts? > >>> > > >>>>> > >>> > > >>>>> Gary > >>> > > >>>>> > >>> > > >>>>> > >>> > > >>>>>> Jochen > >>> > > >>>>>> > >>> > > >>>>>> > >>> > > >>>>>> -- > >>> > > >>>>>> The next time you hear: "Don't reinvent the wheel!" > >>> > > >>>>>> > >>> > > >>>>>> http://www.keystonedevelopment.co.uk/wp- > content/uploads/2014 > >>> /10/ > >>> > > >>>>>> evolution-of-the-wheel-300x85.jpg > >>> > > >>>>>> > >>> > > >>>>>> ------------------------------ > ------------------------------ > >>> > > --------- > >>> > > >>>>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org > >>> > > >>>>>> For additional commands, e-mail: > dev-help@commons.apache.org > >>> > > >>>>>> > >>> > > >>>>>> > >>> > > >>>>> > >>> > > >>>> > >>> > > >>>> > >>> > > >>>> > >>> > ------------------------------------------------------------ > --------- > >>> > > >>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org > >>> > > >>>> For additional commands, e-mail: dev-help@commons.apache.org > >>> > > >>>> > >>> > > >>> > >>> > > >>> ------------------------------------------------------------ > >>> --------- > >>> > > >>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org > >>> > > >>> For additional commands, e-mail: dev-help@commons.apache.org > >>> > > >>> > >>> > > >>> > >>> > > >> > >>> > > >> > >>> > > >> -- > >>> > > >> E-Mail: garydgregory@gmail.com | ggregory@apache.org > >>> > > >> Java Persistence with Hibernate, Second Edition > >>> > > >> >>> > > tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1617290459& > >>> > > linkCode=as2&tag=garygregory-20&linkId=cadb800f39946ec62ea2b > >>> 1af9fe6a2b8> > >>> > > >> > >>> > > >> >>> > ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a= > >>> > > 1617290459> > >>> > > >> JUnit in Action, Second Edition > >>> > > >> >>> > > tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182021& > >>> > > > >>> > linkCode=as2&tag=garygregory-20&linkId=31ecd1f6b6d1eaf8886ac > >>> 902a24de418%22 > >>> > > > > >>> > > >> > >>> > > >> >>> > ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a= > >>> > > 1935182021> > >>> > > >> Spring Batch in Action > >>> > > >> >>> > > 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> > >>> > > >> >>> > 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 > >>> > > >> > >>> > > > > >>> > > > > >>> > > > > >>> > > > >>> > > ------------------------------------------------------------ > >>> --------- > >>> > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org > >>> > > For additional commands, e-mail: dev-help@commons.apache.org > >>> > > > >>> > > > >>> > > >>> > > >>> > -- > >>> > E-Mail: garydgregory@gmail.com | ggregory@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&linkCo > >>> de=as2&tag=garygregory-20&linkId=cadb800f39946ec62ea2b1af9fe6a2b8 > >>> > > > >>> > > >>> > >>> > 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&linkCo > >>> de=as2&tag=garygregory-20&linkId=31ecd1f6b6d1eaf8886ac902a24de418%22 > >>> > > > >>> > > >>> > >>> > 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&linkCo > >>> de=%7B%7BlinkCode%7D%7D&tag=garygregory-20&linkId=%7B%7Blink > >>> _id%7D%7D%22%3ESpring+Batch+in+Action > >>> > > > >>> > >>> > 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 > >>> > > >>> > >> > >> > >> > >> -- > >> E-Mail: garydgregory@gmail.com | ggregory@apache.org > >> Java Persistence with Hibernate, Second Edition > >> tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1617290459& > linkCode=as2&tag=garygregory-20&linkId=cadb800f39946ec62ea2b1af9fe6a2b8> > >> > >> 1617290459> > >> JUnit in Action, Second Edition > >> tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182021& > linkCode=as2&tag=garygregory-20&linkId=31ecd1f6b6d1eaf8886ac902a24de418%22 > > > >> > >> 1935182021> > >> Spring Batch in Action > >> 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> > >> 1935182951> > >> Blog: http://garygregory.wordpress.com > >> Home: http://garygregory.com/ > >> Tweet! http://twitter.com/GaryGregory > >> > > > > > > > > -- > > E-Mail: garydgregory@gmail.com | ggregory@apache.org > > Java Persistence with Hibernate, Second Edition > > tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1617290459& > linkCode=as2&tag=garygregory-20&linkId=cadb800f39946ec62ea2b1af9fe6a2b8> > > > > 1617290459> > > JUnit in Action, Second Edition > > tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182021& > linkCode=as2&tag=garygregory-20&linkId=31ecd1f6b6d1eaf8886ac902a24de418%22 > > > > > > 1935182021> > > Spring Batch in Action > > 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> > > 1935182951> > > Blog: http://garygregory.wordpress.com > > Home: http://garygregory.com/ > > Tweet! http://twitter.com/GaryGregory > > > > > > -- > E-Mail: garydgregory@gmail.com | ggregory@apache.org > Java Persistence with Hibernate, Second Edition > tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1617290459& > linkCode=as2&tag=garygregory-20&linkId=cadb800f39946ec62ea2b1af9fe6a2b8> > > 1617290459> > JUnit in Action, Second Edition > tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182021& > linkCode=as2&tag=garygregory-20&linkId=31ecd1f6b6d1eaf8886ac902a24de418%22 > > > > 1935182021> > Spring Batch in Action > 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> > 1935182951> > Blog: http://garygregory.wordpress.com > Home: http://garygregory.com/ > Tweet! http://twitter.com/GaryGregory > -- Matt Sicker --001a114aab8c11512c05427ccc30--