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 <garydgreg...@gmail.com>
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 <garydgreg...@gmail.com>
> wrote:
>
>> On Tue, Nov 29, 2016 at 1:59 PM, Benedikt Ritter <brit...@apache.org>
>> 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 <garydgreg...@gmail.com> schrieb am Di. 29. Nov. 2016 um
>>> 22:33:
>>>
>>> > On Tue, Nov 29, 2016 at 1:12 PM, Oliver Heger <
>>> > oliver.he...@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 <
>>> garydgreg...@gmail.com
>>> > >
>>> > > > wrote:
>>> > > >
>>> > > >> On Mon, Nov 28, 2016 at 12:18 PM, Matt Benson <
>>> gudnabr...@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
>>> > > >>> <pascalschumac...@gmx.net> 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
>>> > > >>>>> <jochen.wiedm...@gmail.com>
>>> > > >>>>> wrote:
>>> > > >>>>>
>>> > > >>>>>> On Mon, Nov 28, 2016 at 4:06 PM, sebb <seb...@gmail.com>
>>> 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-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
>>> > > >>>>
>>> > > >>>
>>> > > >>> ------------------------------------------------------------
>>> ---------
>>> > > >>> 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=cadb800f39946ec62ea2b
>>> 1af9fe6a2b8>
>>> > > >>
>>> > > >> <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=31ecd1f6b6d1eaf8886ac
>>> 902a24de418%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
>>> > > >>
>>> > > >
>>> > > >
>>> > > >
>>> > >
>>> > > ------------------------------------------------------------
>>> ---------
>>> > > 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&linkCo
>>> de=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&linkCo
>>> de=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&linkCo
>>> de=%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
>>> >
>>>
>>
>>
>>
>> --
>> 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
>>
>
>
>
> --
> 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
>
--
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
