commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gary Gregory <garydgreg...@gmail.com>
Subject Re: [lang] Thread safety annotations
Date Wed, 30 Nov 2016 02:40:18 GMT
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 <garydgregory@gmail.com>
wrote:

> On Tue, Nov 29, 2016 at 1:59 PM, Benedikt Ritter <britter@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 <garydgregory@gmail.com> 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
>> > > >>> <pascalschumacher@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.wiedmann@gmail.com>
>> > > >>>>> wrote:
>> > > >>>>>
>> > > >>>>>> On Mon, Nov 28, 2016 at 4:06 PM, sebb <sebbaz@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-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
>> > > >> <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-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&link
>> Code=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&link
>> Code=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&link
>> Code=%7B%7BlinkCode%7D%7D&tag=garygregory-20&linkId=%7B%7Bli
>> nk_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: 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&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: 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&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

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message