On Tue, Nov 29, 2016 at 8:04 PM, Matt Sicker <boa...@gmail.com> wrote:
> 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).
>
The problem with solo annotations is that you can say nonsensical things
like:
@ThreadSafe
@NotThreadSafe
public class Foo {
...
}
You can't do that with:
@Contract(threading = ThreadingBehavior.IMMUTABLE)
Gary
>
> If only the JDK had an annotation for this.
>
> On 29 November 2016 at 20:41, Gary Gregory <garydgreg...@gmail.com> 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 <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-unsubscribe@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=31ecd1f6b6d1eaf8886ac902a24de4
> 18%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=31ecd1f6b6d1eaf8886ac902a24de4
> 18%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=31ecd1f6b6d1eaf8886ac902a24de4
> 18%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
> >
>
>
>
> --
> Matt Sicker <boa...@gmail.com>
>
--
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
