Re: [lang] [LANG-1291] Provide annotations to document thread safety.

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: [lang] [LANG-1291] Provide annotations to document thread safety.

Benedikt Ritter-4
Hello Gary,

Can you please explain why you think it is better to use a single parameterized annotation over several individual annotations?

Thank you!
Benedikt

> Am 17.04.2017 um 20:54 schrieb [hidden email]:
>
> Repository: commons-lang
> Updated Branches:
>  refs/heads/master 5242157df -> a5e76ebc4
>
>
> [LANG-1291] Provide annotations to document thread safety.
>
> Project: http://git-wip-us.apache.org/repos/asf/commons-lang/repo
> Commit: http://git-wip-us.apache.org/repos/asf/commons-lang/commit/a5e76ebc
> Tree: http://git-wip-us.apache.org/repos/asf/commons-lang/tree/a5e76ebc
> Diff: http://git-wip-us.apache.org/repos/asf/commons-lang/diff/a5e76ebc
>
> Branch: refs/heads/master
> Commit: a5e76ebc404d419651c2a25b1a62199de64cccf5
> Parents: 5242157
> Author: Gary Gregory <[hidden email]>
> Authored: Mon Apr 17 11:54:04 2017 -0700
> Committer: Gary Gregory <[hidden email]>
> Committed: Mon Apr 17 11:54:04 2017 -0700
>
> ----------------------------------------------------------------------
> .../lang3/concurrent/annotation/Contract.java   | 50 +++++++++++++++
> .../annotation/ThreadingBehavior.java           | 66 ++++++++++++++++++++
> 2 files changed, 116 insertions(+)
> ----------------------------------------------------------------------
>
>
> http://git-wip-us.apache.org/repos/asf/commons-lang/blob/a5e76ebc/src/main/java/org/apache/commons/lang3/concurrent/annotation/Contract.java
> ----------------------------------------------------------------------
> diff --git a/src/main/java/org/apache/commons/lang3/concurrent/annotation/Contract.java b/src/main/java/org/apache/commons/lang3/concurrent/annotation/Contract.java
> new file mode 100644
> index 0000000..e34bb95
> --- /dev/null
> +++ b/src/main/java/org/apache/commons/lang3/concurrent/annotation/Contract.java
> @@ -0,0 +1,50 @@
> +/*
> + * ====================================================================
> + * Licensed to the Apache Software Foundation (ASF) under one
> + * or more contributor license agreements.  See the NOTICE file
> + * distributed with this work for additional information
> + * regarding copyright ownership.  The ASF licenses this file
> + * to you under the Apache License, Version 2.0 (the
> + * "License"); you may not use this file except in compliance
> + * with the License.  You may obtain a copy of the License at
> + *
> + *   http://www.apache.org/licenses/LICENSE-2.0
> + *
> + * Unless required by applicable law or agreed to in writing,
> + * software distributed under the License is distributed on an
> + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
> + * KIND, either express or implied.  See the License for the
> + * specific language governing permissions and limitations
> + * under the License.
> + * ====================================================================
> + *
> + * This software consists of voluntary contributions made by many
> + * individuals on behalf of the Apache Software Foundation.  For more
> + * information on the Apache Software Foundation, please see
> + * <http://www.apache.org/>.
> + *
> + */
> +package org.apache.commons.lang3.concurrent.annotation;
> +
> +import java.lang.annotation.Documented;
> +import java.lang.annotation.ElementType;
> +import java.lang.annotation.Retention;
> +import java.lang.annotation.RetentionPolicy;
> +import java.lang.annotation.Target;
> +
> +/**
> + * This annotation defines behavioral contract enforced at runtime by instances of annotated classes.
> + */
> +@Documented
> +@Target(ElementType.TYPE)
> +@Retention(RetentionPolicy.CLASS)
> +public @interface Contract {
> +
> +    /**
> +     * Defines behavioral contract enforced at runtime by instances of annotated classes.
> +     *
> +     * @return The behavioral contract enforced at runtime by instances of annotated classes.
> +     */
> +    ThreadingBehavior threading() default ThreadingBehavior.UNSAFE;
> +
> +}
>
> http://git-wip-us.apache.org/repos/asf/commons-lang/blob/a5e76ebc/src/main/java/org/apache/commons/lang3/concurrent/annotation/ThreadingBehavior.java
> ----------------------------------------------------------------------
> diff --git a/src/main/java/org/apache/commons/lang3/concurrent/annotation/ThreadingBehavior.java b/src/main/java/org/apache/commons/lang3/concurrent/annotation/ThreadingBehavior.java
> new file mode 100644
> index 0000000..e03b164
> --- /dev/null
> +++ b/src/main/java/org/apache/commons/lang3/concurrent/annotation/ThreadingBehavior.java
> @@ -0,0 +1,66 @@
> +/*
> + * ====================================================================
> + * Licensed to the Apache Software Foundation (ASF) under one
> + * or more contributor license agreements.  See the NOTICE file
> + * distributed with this work for additional information
> + * regarding copyright ownership.  The ASF licenses this file
> + * to you under the Apache License, Version 2.0 (the
> + * "License"); you may not use this file except in compliance
> + * with the License.  You may obtain a copy of the License at
> + *
> + *   http://www.apache.org/licenses/LICENSE-2.0
> + *
> + * Unless required by applicable law or agreed to in writing,
> + * software distributed under the License is distributed on an
> + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
> + * KIND, either express or implied.  See the License for the
> + * specific language governing permissions and limitations
> + * under the License.
> + * ====================================================================
> + *
> + * This software consists of voluntary contributions made by many
> + * individuals on behalf of the Apache Software Foundation.  For more
> + * information on the Apache Software Foundation, please see
> + * <http://www.apache.org/>.
> + *
> + */
> +package org.apache.commons.lang3.concurrent.annotation;
> +
> +/**
> + * Defines types of threading behavior enforced at runtime.
> + */
> +public enum ThreadingBehavior {
> +
> +    /**
> +     * Instances of classes with the given contract are expected to be fully immutable and thread-safe.
> +     */
> +    IMMUTABLE,
> +
> +    /**
> +     * Instances of classes with the given contract are expected to be immutable if their dependencies injected at
> +     * construction time are immutable and are expected to be thread-safe if their dependencies are thread-safe.
> +     */
> +    IMMUTABLE_CONDITIONAL,
> +
> +    /**
> +     * Instances of classes with the given contract are expected to maintain no state and to be thread-safe.
> +     */
> +    STATELESS,
> +
> +    /**
> +     * Instances of classes with the given contract are expected to be fully thread-safe.
> +     */
> +    SAFE,
> +
> +    /**
> +     * Instances of classes with the given contract are expected to be thread-safe if their dependencies injected at
> +     * construction time are thread-safe.
> +     */
> +    SAFE_CONDITIONAL,
> +
> +    /**
> +     * Instances of classes with the given contract are expected to be non thread-safe.
> +     */
> +    UNSAFE
> +
> +}
>


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [lang] [LANG-1291] Provide annotations to document thread safety.

garydgregory
Because if you use multiple annotations, you (or tools) can write silly
things like:

@ThreadSafe
@NotThreadSafe
public class Foo {
   ...
}

Gary

On Mon, Apr 17, 2017 at 11:27 PM, Benedikt Ritter <[hidden email]>
wrote:

> Hello Gary,
>
> Can you please explain why you think it is better to use a single
> parameterized annotation over several individual annotations?
>
> Thank you!
> Benedikt
>
> > Am 17.04.2017 um 20:54 schrieb [hidden email]:
> >
> > Repository: commons-lang
> > Updated Branches:
> >  refs/heads/master 5242157df -> a5e76ebc4
> >
> >
> > [LANG-1291] Provide annotations to document thread safety.
> >
> > Project: http://git-wip-us.apache.org/repos/asf/commons-lang/repo
> > Commit: http://git-wip-us.apache.org/repos/asf/commons-lang/commit/
> a5e76ebc
> > Tree: http://git-wip-us.apache.org/repos/asf/commons-lang/tree/a5e76ebc
> > Diff: http://git-wip-us.apache.org/repos/asf/commons-lang/diff/a5e76ebc
> >
> > Branch: refs/heads/master
> > Commit: a5e76ebc404d419651c2a25b1a62199de64cccf5
> > Parents: 5242157
> > Author: Gary Gregory <[hidden email]>
> > Authored: Mon Apr 17 11:54:04 2017 -0700
> > Committer: Gary Gregory <[hidden email]>
> > Committed: Mon Apr 17 11:54:04 2017 -0700
> >
> > ----------------------------------------------------------------------
> > .../lang3/concurrent/annotation/Contract.java   | 50 +++++++++++++++
> > .../annotation/ThreadingBehavior.java           | 66
> ++++++++++++++++++++
> > 2 files changed, 116 insertions(+)
> > ----------------------------------------------------------------------
> >
> >
> > http://git-wip-us.apache.org/repos/asf/commons-lang/blob/
> a5e76ebc/src/main/java/org/apache/commons/lang3/concurrent/annotation/
> Contract.java
> > ----------------------------------------------------------------------
> > diff --git a/src/main/java/org/apache/commons/lang3/concurrent/annotation/Contract.java
> b/src/main/java/org/apache/commons/lang3/concurrent/
> annotation/Contract.java
> > new file mode 100644
> > index 0000000..e34bb95
> > --- /dev/null
> > +++ b/src/main/java/org/apache/commons/lang3/concurrent/
> annotation/Contract.java
> > @@ -0,0 +1,50 @@
> > +/*
> > + * ====================================================================
> > + * Licensed to the Apache Software Foundation (ASF) under one
> > + * or more contributor license agreements.  See the NOTICE file
> > + * distributed with this work for additional information
> > + * regarding copyright ownership.  The ASF licenses this file
> > + * to you under the Apache License, Version 2.0 (the
> > + * "License"); you may not use this file except in compliance
> > + * with the License.  You may obtain a copy of the License at
> > + *
> > + *   http://www.apache.org/licenses/LICENSE-2.0
> > + *
> > + * Unless required by applicable law or agreed to in writing,
> > + * software distributed under the License is distributed on an
> > + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
> > + * KIND, either express or implied.  See the License for the
> > + * specific language governing permissions and limitations
> > + * under the License.
> > + * ====================================================================
> > + *
> > + * This software consists of voluntary contributions made by many
> > + * individuals on behalf of the Apache Software Foundation.  For more
> > + * information on the Apache Software Foundation, please see
> > + * <http://www.apache.org/>.
> > + *
> > + */
> > +package org.apache.commons.lang3.concurrent.annotation;
> > +
> > +import java.lang.annotation.Documented;
> > +import java.lang.annotation.ElementType;
> > +import java.lang.annotation.Retention;
> > +import java.lang.annotation.RetentionPolicy;
> > +import java.lang.annotation.Target;
> > +
> > +/**
> > + * This annotation defines behavioral contract enforced at runtime by
> instances of annotated classes.
> > + */
> > +@Documented
> > +@Target(ElementType.TYPE)
> > +@Retention(RetentionPolicy.CLASS)
> > +public @interface Contract {
> > +
> > +    /**
> > +     * Defines behavioral contract enforced at runtime by instances of
> annotated classes.
> > +     *
> > +     * @return The behavioral contract enforced at runtime by instances
> of annotated classes.
> > +     */
> > +    ThreadingBehavior threading() default ThreadingBehavior.UNSAFE;
> > +
> > +}
> >
> > http://git-wip-us.apache.org/repos/asf/commons-lang/blob/
> a5e76ebc/src/main/java/org/apache/commons/lang3/concurrent/annotation/
> ThreadingBehavior.java
> > ----------------------------------------------------------------------
> > diff --git a/src/main/java/org/apache/commons/lang3/concurrent/
> annotation/ThreadingBehavior.java b/src/main/java/org/apache/
> commons/lang3/concurrent/annotation/ThreadingBehavior.java
> > new file mode 100644
> > index 0000000..e03b164
> > --- /dev/null
> > +++ b/src/main/java/org/apache/commons/lang3/concurrent/
> annotation/ThreadingBehavior.java
> > @@ -0,0 +1,66 @@
> > +/*
> > + * ====================================================================
> > + * Licensed to the Apache Software Foundation (ASF) under one
> > + * or more contributor license agreements.  See the NOTICE file
> > + * distributed with this work for additional information
> > + * regarding copyright ownership.  The ASF licenses this file
> > + * to you under the Apache License, Version 2.0 (the
> > + * "License"); you may not use this file except in compliance
> > + * with the License.  You may obtain a copy of the License at
> > + *
> > + *   http://www.apache.org/licenses/LICENSE-2.0
> > + *
> > + * Unless required by applicable law or agreed to in writing,
> > + * software distributed under the License is distributed on an
> > + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
> > + * KIND, either express or implied.  See the License for the
> > + * specific language governing permissions and limitations
> > + * under the License.
> > + * ====================================================================
> > + *
> > + * This software consists of voluntary contributions made by many
> > + * individuals on behalf of the Apache Software Foundation.  For more
> > + * information on the Apache Software Foundation, please see
> > + * <http://www.apache.org/>.
> > + *
> > + */
> > +package org.apache.commons.lang3.concurrent.annotation;
> > +
> > +/**
> > + * Defines types of threading behavior enforced at runtime.
> > + */
> > +public enum ThreadingBehavior {
> > +
> > +    /**
> > +     * Instances of classes with the given contract are expected to be
> fully immutable and thread-safe.
> > +     */
> > +    IMMUTABLE,
> > +
> > +    /**
> > +     * Instances of classes with the given contract are expected to be
> immutable if their dependencies injected at
> > +     * construction time are immutable and are expected to be
> thread-safe if their dependencies are thread-safe.
> > +     */
> > +    IMMUTABLE_CONDITIONAL,
> > +
> > +    /**
> > +     * Instances of classes with the given contract are expected to
> maintain no state and to be thread-safe.
> > +     */
> > +    STATELESS,
> > +
> > +    /**
> > +     * Instances of classes with the given contract are expected to be
> fully thread-safe.
> > +     */
> > +    SAFE,
> > +
> > +    /**
> > +     * Instances of classes with the given contract are expected to be
> thread-safe if their dependencies injected at
> > +     * construction time are thread-safe.
> > +     */
> > +    SAFE_CONDITIONAL,
> > +
> > +    /**
> > +     * Instances of classes with the given contract are expected to be
> non thread-safe.
> > +     */
> > +    UNSAFE
> > +
> > +}
> >
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>


--
E-Mail: [hidden email] | [hidden email]
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
Reply | Threaded
Open this post in threaded view
|

Re: [lang] [LANG-1291] Provide annotations to document thread safety.

Benedikt Ritter-4
Hi,

> Am 18.04.2017 um 08:46 schrieb Gary Gregory <[hidden email]>:
>
> Because if you use multiple annotations, you (or tools) can write silly
> things like:
>
> @ThreadSafe
> @NotThreadSafe
> public class Foo {
>   …
> }

Thank you for the clarification. It makes complete sense to me. Given this reason I’m fine with @Contract.

Benedikt

>
> Gary
>
> On Mon, Apr 17, 2017 at 11:27 PM, Benedikt Ritter <[hidden email]>
> wrote:
>
>> Hello Gary,
>>
>> Can you please explain why you think it is better to use a single
>> parameterized annotation over several individual annotations?
>>
>> Thank you!
>> Benedikt
>>
>>> Am 17.04.2017 um 20:54 schrieb [hidden email]:
>>>
>>> Repository: commons-lang
>>> Updated Branches:
>>> refs/heads/master 5242157df -> a5e76ebc4
>>>
>>>
>>> [LANG-1291] Provide annotations to document thread safety.
>>>
>>> Project: http://git-wip-us.apache.org/repos/asf/commons-lang/repo
>>> Commit: http://git-wip-us.apache.org/repos/asf/commons-lang/commit/
>> a5e76ebc
>>> Tree: http://git-wip-us.apache.org/repos/asf/commons-lang/tree/a5e76ebc
>>> Diff: http://git-wip-us.apache.org/repos/asf/commons-lang/diff/a5e76ebc
>>>
>>> Branch: refs/heads/master
>>> Commit: a5e76ebc404d419651c2a25b1a62199de64cccf5
>>> Parents: 5242157
>>> Author: Gary Gregory <[hidden email]>
>>> Authored: Mon Apr 17 11:54:04 2017 -0700
>>> Committer: Gary Gregory <[hidden email]>
>>> Committed: Mon Apr 17 11:54:04 2017 -0700
>>>
>>> ----------------------------------------------------------------------
>>> .../lang3/concurrent/annotation/Contract.java   | 50 +++++++++++++++
>>> .../annotation/ThreadingBehavior.java           | 66
>> ++++++++++++++++++++
>>> 2 files changed, 116 insertions(+)
>>> ----------------------------------------------------------------------
>>>
>>>
>>> http://git-wip-us.apache.org/repos/asf/commons-lang/blob/
>> a5e76ebc/src/main/java/org/apache/commons/lang3/concurrent/annotation/
>> Contract.java
>>> ----------------------------------------------------------------------
>>> diff --git a/src/main/java/org/apache/commons/lang3/concurrent/annotation/Contract.java
>> b/src/main/java/org/apache/commons/lang3/concurrent/
>> annotation/Contract.java
>>> new file mode 100644
>>> index 0000000..e34bb95
>>> --- /dev/null
>>> +++ b/src/main/java/org/apache/commons/lang3/concurrent/
>> annotation/Contract.java
>>> @@ -0,0 +1,50 @@
>>> +/*
>>> + * ====================================================================
>>> + * Licensed to the Apache Software Foundation (ASF) under one
>>> + * or more contributor license agreements.  See the NOTICE file
>>> + * distributed with this work for additional information
>>> + * regarding copyright ownership.  The ASF licenses this file
>>> + * to you under the Apache License, Version 2.0 (the
>>> + * "License"); you may not use this file except in compliance
>>> + * with the License.  You may obtain a copy of the License at
>>> + *
>>> + *   http://www.apache.org/licenses/LICENSE-2.0
>>> + *
>>> + * Unless required by applicable law or agreed to in writing,
>>> + * software distributed under the License is distributed on an
>>> + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
>>> + * KIND, either express or implied.  See the License for the
>>> + * specific language governing permissions and limitations
>>> + * under the License.
>>> + * ====================================================================
>>> + *
>>> + * This software consists of voluntary contributions made by many
>>> + * individuals on behalf of the Apache Software Foundation.  For more
>>> + * information on the Apache Software Foundation, please see
>>> + * <http://www.apache.org/>.
>>> + *
>>> + */
>>> +package org.apache.commons.lang3.concurrent.annotation;
>>> +
>>> +import java.lang.annotation.Documented;
>>> +import java.lang.annotation.ElementType;
>>> +import java.lang.annotation.Retention;
>>> +import java.lang.annotation.RetentionPolicy;
>>> +import java.lang.annotation.Target;
>>> +
>>> +/**
>>> + * This annotation defines behavioral contract enforced at runtime by
>> instances of annotated classes.
>>> + */
>>> +@Documented
>>> +@Target(ElementType.TYPE)
>>> +@Retention(RetentionPolicy.CLASS)
>>> +public @interface Contract {
>>> +
>>> +    /**
>>> +     * Defines behavioral contract enforced at runtime by instances of
>> annotated classes.
>>> +     *
>>> +     * @return The behavioral contract enforced at runtime by instances
>> of annotated classes.
>>> +     */
>>> +    ThreadingBehavior threading() default ThreadingBehavior.UNSAFE;
>>> +
>>> +}
>>>
>>> http://git-wip-us.apache.org/repos/asf/commons-lang/blob/
>> a5e76ebc/src/main/java/org/apache/commons/lang3/concurrent/annotation/
>> ThreadingBehavior.java
>>> ----------------------------------------------------------------------
>>> diff --git a/src/main/java/org/apache/commons/lang3/concurrent/
>> annotation/ThreadingBehavior.java b/src/main/java/org/apache/
>> commons/lang3/concurrent/annotation/ThreadingBehavior.java
>>> new file mode 100644
>>> index 0000000..e03b164
>>> --- /dev/null
>>> +++ b/src/main/java/org/apache/commons/lang3/concurrent/
>> annotation/ThreadingBehavior.java
>>> @@ -0,0 +1,66 @@
>>> +/*
>>> + * ====================================================================
>>> + * Licensed to the Apache Software Foundation (ASF) under one
>>> + * or more contributor license agreements.  See the NOTICE file
>>> + * distributed with this work for additional information
>>> + * regarding copyright ownership.  The ASF licenses this file
>>> + * to you under the Apache License, Version 2.0 (the
>>> + * "License"); you may not use this file except in compliance
>>> + * with the License.  You may obtain a copy of the License at
>>> + *
>>> + *   http://www.apache.org/licenses/LICENSE-2.0
>>> + *
>>> + * Unless required by applicable law or agreed to in writing,
>>> + * software distributed under the License is distributed on an
>>> + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
>>> + * KIND, either express or implied.  See the License for the
>>> + * specific language governing permissions and limitations
>>> + * under the License.
>>> + * ====================================================================
>>> + *
>>> + * This software consists of voluntary contributions made by many
>>> + * individuals on behalf of the Apache Software Foundation.  For more
>>> + * information on the Apache Software Foundation, please see
>>> + * <http://www.apache.org/>.
>>> + *
>>> + */
>>> +package org.apache.commons.lang3.concurrent.annotation;
>>> +
>>> +/**
>>> + * Defines types of threading behavior enforced at runtime.
>>> + */
>>> +public enum ThreadingBehavior {
>>> +
>>> +    /**
>>> +     * Instances of classes with the given contract are expected to be
>> fully immutable and thread-safe.
>>> +     */
>>> +    IMMUTABLE,
>>> +
>>> +    /**
>>> +     * Instances of classes with the given contract are expected to be
>> immutable if their dependencies injected at
>>> +     * construction time are immutable and are expected to be
>> thread-safe if their dependencies are thread-safe.
>>> +     */
>>> +    IMMUTABLE_CONDITIONAL,
>>> +
>>> +    /**
>>> +     * Instances of classes with the given contract are expected to
>> maintain no state and to be thread-safe.
>>> +     */
>>> +    STATELESS,
>>> +
>>> +    /**
>>> +     * Instances of classes with the given contract are expected to be
>> fully thread-safe.
>>> +     */
>>> +    SAFE,
>>> +
>>> +    /**
>>> +     * Instances of classes with the given contract are expected to be
>> thread-safe if their dependencies injected at
>>> +     * construction time are thread-safe.
>>> +     */
>>> +    SAFE_CONDITIONAL,
>>> +
>>> +    /**
>>> +     * Instances of classes with the given contract are expected to be
>> non thread-safe.
>>> +     */
>>> +    UNSAFE
>>> +
>>> +}
>>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [hidden email]
>> For additional commands, e-mail: [hidden email]
>>
>>
>
>
> --
> E-Mail: [hidden email] | [hidden email]
> 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


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [lang] [LANG-1291] Provide annotations to document thread safety.

sebb-2-2
I think ThreadingBehavior is very confusing as an enum.

I expect enum values to be mutually exclusive, but STATELESS is also IMMUTABLE.
And of course IMMUTABLE is SAFE.

How do I know which enum to use?

I don't think this is a good solution to the potential problem of
someone using both @ThreadSafe and @NotThreadsafe.



On 18 April 2017 at 07:49, Benedikt Ritter <[hidden email]> wrote:

> Hi,
>
>> Am 18.04.2017 um 08:46 schrieb Gary Gregory <[hidden email]>:
>>
>> Because if you use multiple annotations, you (or tools) can write silly
>> things like:
>>
>> @ThreadSafe
>> @NotThreadSafe
>> public class Foo {
>>   …
>> }
>
> Thank you for the clarification. It makes complete sense to me. Given this reason I’m fine with @Contract.
>
> Benedikt
>
>>
>> Gary
>>
>> On Mon, Apr 17, 2017 at 11:27 PM, Benedikt Ritter <[hidden email]>
>> wrote:
>>
>>> Hello Gary,
>>>
>>> Can you please explain why you think it is better to use a single
>>> parameterized annotation over several individual annotations?
>>>
>>> Thank you!
>>> Benedikt
>>>
>>>> Am 17.04.2017 um 20:54 schrieb [hidden email]:
>>>>
>>>> Repository: commons-lang
>>>> Updated Branches:
>>>> refs/heads/master 5242157df -> a5e76ebc4
>>>>
>>>>
>>>> [LANG-1291] Provide annotations to document thread safety.
>>>>
>>>> Project: http://git-wip-us.apache.org/repos/asf/commons-lang/repo
>>>> Commit: http://git-wip-us.apache.org/repos/asf/commons-lang/commit/
>>> a5e76ebc
>>>> Tree: http://git-wip-us.apache.org/repos/asf/commons-lang/tree/a5e76ebc
>>>> Diff: http://git-wip-us.apache.org/repos/asf/commons-lang/diff/a5e76ebc
>>>>
>>>> Branch: refs/heads/master
>>>> Commit: a5e76ebc404d419651c2a25b1a62199de64cccf5
>>>> Parents: 5242157
>>>> Author: Gary Gregory <[hidden email]>
>>>> Authored: Mon Apr 17 11:54:04 2017 -0700
>>>> Committer: Gary Gregory <[hidden email]>
>>>> Committed: Mon Apr 17 11:54:04 2017 -0700
>>>>
>>>> ----------------------------------------------------------------------
>>>> .../lang3/concurrent/annotation/Contract.java   | 50 +++++++++++++++
>>>> .../annotation/ThreadingBehavior.java           | 66
>>> ++++++++++++++++++++
>>>> 2 files changed, 116 insertions(+)
>>>> ----------------------------------------------------------------------
>>>>
>>>>
>>>> http://git-wip-us.apache.org/repos/asf/commons-lang/blob/
>>> a5e76ebc/src/main/java/org/apache/commons/lang3/concurrent/annotation/
>>> Contract.java
>>>> ----------------------------------------------------------------------
>>>> diff --git a/src/main/java/org/apache/commons/lang3/concurrent/annotation/Contract.java
>>> b/src/main/java/org/apache/commons/lang3/concurrent/
>>> annotation/Contract.java
>>>> new file mode 100644
>>>> index 0000000..e34bb95
>>>> --- /dev/null
>>>> +++ b/src/main/java/org/apache/commons/lang3/concurrent/
>>> annotation/Contract.java
>>>> @@ -0,0 +1,50 @@
>>>> +/*
>>>> + * ====================================================================
>>>> + * Licensed to the Apache Software Foundation (ASF) under one
>>>> + * or more contributor license agreements.  See the NOTICE file
>>>> + * distributed with this work for additional information
>>>> + * regarding copyright ownership.  The ASF licenses this file
>>>> + * to you under the Apache License, Version 2.0 (the
>>>> + * "License"); you may not use this file except in compliance
>>>> + * with the License.  You may obtain a copy of the License at
>>>> + *
>>>> + *   http://www.apache.org/licenses/LICENSE-2.0
>>>> + *
>>>> + * Unless required by applicable law or agreed to in writing,
>>>> + * software distributed under the License is distributed on an
>>>> + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
>>>> + * KIND, either express or implied.  See the License for the
>>>> + * specific language governing permissions and limitations
>>>> + * under the License.
>>>> + * ====================================================================
>>>> + *
>>>> + * This software consists of voluntary contributions made by many
>>>> + * individuals on behalf of the Apache Software Foundation.  For more
>>>> + * information on the Apache Software Foundation, please see
>>>> + * <http://www.apache.org/>.
>>>> + *
>>>> + */
>>>> +package org.apache.commons.lang3.concurrent.annotation;
>>>> +
>>>> +import java.lang.annotation.Documented;
>>>> +import java.lang.annotation.ElementType;
>>>> +import java.lang.annotation.Retention;
>>>> +import java.lang.annotation.RetentionPolicy;
>>>> +import java.lang.annotation.Target;
>>>> +
>>>> +/**
>>>> + * This annotation defines behavioral contract enforced at runtime by
>>> instances of annotated classes.
>>>> + */
>>>> +@Documented
>>>> +@Target(ElementType.TYPE)
>>>> +@Retention(RetentionPolicy.CLASS)
>>>> +public @interface Contract {
>>>> +
>>>> +    /**
>>>> +     * Defines behavioral contract enforced at runtime by instances of
>>> annotated classes.
>>>> +     *
>>>> +     * @return The behavioral contract enforced at runtime by instances
>>> of annotated classes.
>>>> +     */
>>>> +    ThreadingBehavior threading() default ThreadingBehavior.UNSAFE;
>>>> +
>>>> +}
>>>>
>>>> http://git-wip-us.apache.org/repos/asf/commons-lang/blob/
>>> a5e76ebc/src/main/java/org/apache/commons/lang3/concurrent/annotation/
>>> ThreadingBehavior.java
>>>> ----------------------------------------------------------------------
>>>> diff --git a/src/main/java/org/apache/commons/lang3/concurrent/
>>> annotation/ThreadingBehavior.java b/src/main/java/org/apache/
>>> commons/lang3/concurrent/annotation/ThreadingBehavior.java
>>>> new file mode 100644
>>>> index 0000000..e03b164
>>>> --- /dev/null
>>>> +++ b/src/main/java/org/apache/commons/lang3/concurrent/
>>> annotation/ThreadingBehavior.java
>>>> @@ -0,0 +1,66 @@
>>>> +/*
>>>> + * ====================================================================
>>>> + * Licensed to the Apache Software Foundation (ASF) under one
>>>> + * or more contributor license agreements.  See the NOTICE file
>>>> + * distributed with this work for additional information
>>>> + * regarding copyright ownership.  The ASF licenses this file
>>>> + * to you under the Apache License, Version 2.0 (the
>>>> + * "License"); you may not use this file except in compliance
>>>> + * with the License.  You may obtain a copy of the License at
>>>> + *
>>>> + *   http://www.apache.org/licenses/LICENSE-2.0
>>>> + *
>>>> + * Unless required by applicable law or agreed to in writing,
>>>> + * software distributed under the License is distributed on an
>>>> + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
>>>> + * KIND, either express or implied.  See the License for the
>>>> + * specific language governing permissions and limitations
>>>> + * under the License.
>>>> + * ====================================================================
>>>> + *
>>>> + * This software consists of voluntary contributions made by many
>>>> + * individuals on behalf of the Apache Software Foundation.  For more
>>>> + * information on the Apache Software Foundation, please see
>>>> + * <http://www.apache.org/>.
>>>> + *
>>>> + */
>>>> +package org.apache.commons.lang3.concurrent.annotation;
>>>> +
>>>> +/**
>>>> + * Defines types of threading behavior enforced at runtime.
>>>> + */
>>>> +public enum ThreadingBehavior {
>>>> +
>>>> +    /**
>>>> +     * Instances of classes with the given contract are expected to be
>>> fully immutable and thread-safe.
>>>> +     */
>>>> +    IMMUTABLE,
>>>> +
>>>> +    /**
>>>> +     * Instances of classes with the given contract are expected to be
>>> immutable if their dependencies injected at
>>>> +     * construction time are immutable and are expected to be
>>> thread-safe if their dependencies are thread-safe.
>>>> +     */
>>>> +    IMMUTABLE_CONDITIONAL,
>>>> +
>>>> +    /**
>>>> +     * Instances of classes with the given contract are expected to
>>> maintain no state and to be thread-safe.
>>>> +     */
>>>> +    STATELESS,
>>>> +
>>>> +    /**
>>>> +     * Instances of classes with the given contract are expected to be
>>> fully thread-safe.
>>>> +     */
>>>> +    SAFE,
>>>> +
>>>> +    /**
>>>> +     * Instances of classes with the given contract are expected to be
>>> thread-safe if their dependencies injected at
>>>> +     * construction time are thread-safe.
>>>> +     */
>>>> +    SAFE_CONDITIONAL,
>>>> +
>>>> +    /**
>>>> +     * Instances of classes with the given contract are expected to be
>>> non thread-safe.
>>>> +     */
>>>> +    UNSAFE
>>>> +
>>>> +}
>>>>
>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: [hidden email]
>>> For additional commands, e-mail: [hidden email]
>>>
>>>
>>
>>
>> --
>> E-Mail: [hidden email] | [hidden email]
>> 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
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [lang] [LANG-1291] Provide annotations to document thread safety.

Matt Sicker
You can work around annotation permissiveness by implementing an annotation
processor to fail compilations with improper combinations of annotations,
but I feel that the annotation+enum approach is a lot simpler to enforce.

On 18 April 2017 at 04:40, sebb <[hidden email]> wrote:

> I think ThreadingBehavior is very confusing as an enum.
>
> I expect enum values to be mutually exclusive, but STATELESS is also
> IMMUTABLE.
> And of course IMMUTABLE is SAFE.
>
> How do I know which enum to use?
>
> I don't think this is a good solution to the potential problem of
> someone using both @ThreadSafe and @NotThreadsafe.
>
>
>
> On 18 April 2017 at 07:49, Benedikt Ritter <[hidden email]> wrote:
> > Hi,
> >
> >> Am 18.04.2017 um 08:46 schrieb Gary Gregory <[hidden email]>:
> >>
> >> Because if you use multiple annotations, you (or tools) can write silly
> >> things like:
> >>
> >> @ThreadSafe
> >> @NotThreadSafe
> >> public class Foo {
> >>   …
> >> }
> >
> > Thank you for the clarification. It makes complete sense to me. Given
> this reason I’m fine with @Contract.
> >
> > Benedikt
> >
> >>
> >> Gary
> >>
> >> On Mon, Apr 17, 2017 at 11:27 PM, Benedikt Ritter <[hidden email]>
> >> wrote:
> >>
> >>> Hello Gary,
> >>>
> >>> Can you please explain why you think it is better to use a single
> >>> parameterized annotation over several individual annotations?
> >>>
> >>> Thank you!
> >>> Benedikt
> >>>
> >>>> Am 17.04.2017 um 20:54 schrieb [hidden email]:
> >>>>
> >>>> Repository: commons-lang
> >>>> Updated Branches:
> >>>> refs/heads/master 5242157df -> a5e76ebc4
> >>>>
> >>>>
> >>>> [LANG-1291] Provide annotations to document thread safety.
> >>>>
> >>>> Project: http://git-wip-us.apache.org/repos/asf/commons-lang/repo
> >>>> Commit: http://git-wip-us.apache.org/repos/asf/commons-lang/commit/
> >>> a5e76ebc
> >>>> Tree: http://git-wip-us.apache.org/repos/asf/commons-lang/tree/
> a5e76ebc
> >>>> Diff: http://git-wip-us.apache.org/repos/asf/commons-lang/diff/
> a5e76ebc
> >>>>
> >>>> Branch: refs/heads/master
> >>>> Commit: a5e76ebc404d419651c2a25b1a62199de64cccf5
> >>>> Parents: 5242157
> >>>> Author: Gary Gregory <[hidden email]>
> >>>> Authored: Mon Apr 17 11:54:04 2017 -0700
> >>>> Committer: Gary Gregory <[hidden email]>
> >>>> Committed: Mon Apr 17 11:54:04 2017 -0700
> >>>>
> >>>> ------------------------------------------------------------
> ----------
> >>>> .../lang3/concurrent/annotation/Contract.java   | 50 +++++++++++++++
> >>>> .../annotation/ThreadingBehavior.java           | 66
> >>> ++++++++++++++++++++
> >>>> 2 files changed, 116 insertions(+)
> >>>> ------------------------------------------------------------
> ----------
> >>>>
> >>>>
> >>>> http://git-wip-us.apache.org/repos/asf/commons-lang/blob/
> >>> a5e76ebc/src/main/java/org/apache/commons/lang3/concurrent/annotation/
> >>> Contract.java
> >>>> ------------------------------------------------------------
> ----------
> >>>> diff --git a/src/main/java/org/apache/commons/lang3/concurrent/
> annotation/Contract.java
> >>> b/src/main/java/org/apache/commons/lang3/concurrent/
> >>> annotation/Contract.java
> >>>> new file mode 100644
> >>>> index 0000000..e34bb95
> >>>> --- /dev/null
> >>>> +++ b/src/main/java/org/apache/commons/lang3/concurrent/
> >>> annotation/Contract.java
> >>>> @@ -0,0 +1,50 @@
> >>>> +/*
> >>>> + * ============================================================
> ========
> >>>> + * Licensed to the Apache Software Foundation (ASF) under one
> >>>> + * or more contributor license agreements.  See the NOTICE file
> >>>> + * distributed with this work for additional information
> >>>> + * regarding copyright ownership.  The ASF licenses this file
> >>>> + * to you under the Apache License, Version 2.0 (the
> >>>> + * "License"); you may not use this file except in compliance
> >>>> + * with the License.  You may obtain a copy of the License at
> >>>> + *
> >>>> + *   http://www.apache.org/licenses/LICENSE-2.0
> >>>> + *
> >>>> + * Unless required by applicable law or agreed to in writing,
> >>>> + * software distributed under the License is distributed on an
> >>>> + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
> >>>> + * KIND, either express or implied.  See the License for the
> >>>> + * specific language governing permissions and limitations
> >>>> + * under the License.
> >>>> + * ============================================================
> ========
> >>>> + *
> >>>> + * This software consists of voluntary contributions made by many
> >>>> + * individuals on behalf of the Apache Software Foundation.  For more
> >>>> + * information on the Apache Software Foundation, please see
> >>>> + * <http://www.apache.org/>.
> >>>> + *
> >>>> + */
> >>>> +package org.apache.commons.lang3.concurrent.annotation;
> >>>> +
> >>>> +import java.lang.annotation.Documented;
> >>>> +import java.lang.annotation.ElementType;
> >>>> +import java.lang.annotation.Retention;
> >>>> +import java.lang.annotation.RetentionPolicy;
> >>>> +import java.lang.annotation.Target;
> >>>> +
> >>>> +/**
> >>>> + * This annotation defines behavioral contract enforced at runtime by
> >>> instances of annotated classes.
> >>>> + */
> >>>> +@Documented
> >>>> +@Target(ElementType.TYPE)
> >>>> +@Retention(RetentionPolicy.CLASS)
> >>>> +public @interface Contract {
> >>>> +
> >>>> +    /**
> >>>> +     * Defines behavioral contract enforced at runtime by instances
> of
> >>> annotated classes.
> >>>> +     *
> >>>> +     * @return The behavioral contract enforced at runtime by
> instances
> >>> of annotated classes.
> >>>> +     */
> >>>> +    ThreadingBehavior threading() default ThreadingBehavior.UNSAFE;
> >>>> +
> >>>> +}
> >>>>
> >>>> http://git-wip-us.apache.org/repos/asf/commons-lang/blob/
> >>> a5e76ebc/src/main/java/org/apache/commons/lang3/concurrent/annotation/
> >>> ThreadingBehavior.java
> >>>> ------------------------------------------------------------
> ----------
> >>>> diff --git a/src/main/java/org/apache/commons/lang3/concurrent/
> >>> annotation/ThreadingBehavior.java b/src/main/java/org/apache/
> >>> commons/lang3/concurrent/annotation/ThreadingBehavior.java
> >>>> new file mode 100644
> >>>> index 0000000..e03b164
> >>>> --- /dev/null
> >>>> +++ b/src/main/java/org/apache/commons/lang3/concurrent/
> >>> annotation/ThreadingBehavior.java
> >>>> @@ -0,0 +1,66 @@
> >>>> +/*
> >>>> + * ============================================================
> ========
> >>>> + * Licensed to the Apache Software Foundation (ASF) under one
> >>>> + * or more contributor license agreements.  See the NOTICE file
> >>>> + * distributed with this work for additional information
> >>>> + * regarding copyright ownership.  The ASF licenses this file
> >>>> + * to you under the Apache License, Version 2.0 (the
> >>>> + * "License"); you may not use this file except in compliance
> >>>> + * with the License.  You may obtain a copy of the License at
> >>>> + *
> >>>> + *   http://www.apache.org/licenses/LICENSE-2.0
> >>>> + *
> >>>> + * Unless required by applicable law or agreed to in writing,
> >>>> + * software distributed under the License is distributed on an
> >>>> + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
> >>>> + * KIND, either express or implied.  See the License for the
> >>>> + * specific language governing permissions and limitations
> >>>> + * under the License.
> >>>> + * ============================================================
> ========
> >>>> + *
> >>>> + * This software consists of voluntary contributions made by many
> >>>> + * individuals on behalf of the Apache Software Foundation.  For more
> >>>> + * information on the Apache Software Foundation, please see
> >>>> + * <http://www.apache.org/>.
> >>>> + *
> >>>> + */
> >>>> +package org.apache.commons.lang3.concurrent.annotation;
> >>>> +
> >>>> +/**
> >>>> + * Defines types of threading behavior enforced at runtime.
> >>>> + */
> >>>> +public enum ThreadingBehavior {
> >>>> +
> >>>> +    /**
> >>>> +     * Instances of classes with the given contract are expected to
> be
> >>> fully immutable and thread-safe.
> >>>> +     */
> >>>> +    IMMUTABLE,
> >>>> +
> >>>> +    /**
> >>>> +     * Instances of classes with the given contract are expected to
> be
> >>> immutable if their dependencies injected at
> >>>> +     * construction time are immutable and are expected to be
> >>> thread-safe if their dependencies are thread-safe.
> >>>> +     */
> >>>> +    IMMUTABLE_CONDITIONAL,
> >>>> +
> >>>> +    /**
> >>>> +     * Instances of classes with the given contract are expected to
> >>> maintain no state and to be thread-safe.
> >>>> +     */
> >>>> +    STATELESS,
> >>>> +
> >>>> +    /**
> >>>> +     * Instances of classes with the given contract are expected to
> be
> >>> fully thread-safe.
> >>>> +     */
> >>>> +    SAFE,
> >>>> +
> >>>> +    /**
> >>>> +     * Instances of classes with the given contract are expected to
> be
> >>> thread-safe if their dependencies injected at
> >>>> +     * construction time are thread-safe.
> >>>> +     */
> >>>> +    SAFE_CONDITIONAL,
> >>>> +
> >>>> +    /**
> >>>> +     * Instances of classes with the given contract are expected to
> be
> >>> non thread-safe.
> >>>> +     */
> >>>> +    UNSAFE
> >>>> +
> >>>> +}
> >>>>
> >>>
> >>>
> >>> ---------------------------------------------------------------------
> >>> To unsubscribe, e-mail: [hidden email]
> >>> For additional commands, e-mail: [hidden email]
> >>>
> >>>
> >>
> >>
> >> --
> >> E-Mail: [hidden email] | [hidden email]
> >> 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
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: [hidden email]
> > For additional commands, e-mail: [hidden email]
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>


--
Matt Sicker <[hidden email]>
Reply | Threaded
Open this post in threaded view
|

Re: [lang] [LANG-1291] Provide annotations to document thread safety.

Benedikt Ritter-4
Hm, should we leave out the annotations from 3.6 to have more time for
building consensus? Otherwise this will delay the 3.6 release...

Benedikt

Matt Sicker <[hidden email]> schrieb am Mi. 19. Apr. 2017 um 01:33:

> You can work around annotation permissiveness by implementing an annotation
> processor to fail compilations with improper combinations of annotations,
> but I feel that the annotation+enum approach is a lot simpler to enforce.
>
> On 18 April 2017 at 04:40, sebb <[hidden email]> wrote:
>
> > I think ThreadingBehavior is very confusing as an enum.
> >
> > I expect enum values to be mutually exclusive, but STATELESS is also
> > IMMUTABLE.
> > And of course IMMUTABLE is SAFE.
> >
> > How do I know which enum to use?
> >
> > I don't think this is a good solution to the potential problem of
> > someone using both @ThreadSafe and @NotThreadsafe.
> >
> >
> >
> > On 18 April 2017 at 07:49, Benedikt Ritter <[hidden email]> wrote:
> > > Hi,
> > >
> > >> Am 18.04.2017 um 08:46 schrieb Gary Gregory <[hidden email]>:
> > >>
> > >> Because if you use multiple annotations, you (or tools) can write
> silly
> > >> things like:
> > >>
> > >> @ThreadSafe
> > >> @NotThreadSafe
> > >> public class Foo {
> > >>   …
> > >> }
> > >
> > > Thank you for the clarification. It makes complete sense to me. Given
> > this reason I’m fine with @Contract.
> > >
> > > Benedikt
> > >
> > >>
> > >> Gary
> > >>
> > >> On Mon, Apr 17, 2017 at 11:27 PM, Benedikt Ritter <[hidden email]
> >
> > >> wrote:
> > >>
> > >>> Hello Gary,
> > >>>
> > >>> Can you please explain why you think it is better to use a single
> > >>> parameterized annotation over several individual annotations?
> > >>>
> > >>> Thank you!
> > >>> Benedikt
> > >>>
> > >>>> Am 17.04.2017 um 20:54 schrieb [hidden email]:
> > >>>>
> > >>>> Repository: commons-lang
> > >>>> Updated Branches:
> > >>>> refs/heads/master 5242157df -> a5e76ebc4
> > >>>>
> > >>>>
> > >>>> [LANG-1291] Provide annotations to document thread safety.
> > >>>>
> > >>>> Project: http://git-wip-us.apache.org/repos/asf/commons-lang/repo
> > >>>> Commit: http://git-wip-us.apache.org/repos/asf/commons-lang/commit/
> > >>> a5e76ebc
> > >>>> Tree: http://git-wip-us.apache.org/repos/asf/commons-lang/tree/
> > a5e76ebc
> > >>>> Diff: http://git-wip-us.apache.org/repos/asf/commons-lang/diff/
> > a5e76ebc
> > >>>>
> > >>>> Branch: refs/heads/master
> > >>>> Commit: a5e76ebc404d419651c2a25b1a62199de64cccf5
> > >>>> Parents: 5242157
> > >>>> Author: Gary Gregory <[hidden email]>
> > >>>> Authored: Mon Apr 17 11:54:04 2017 -0700
> > >>>> Committer: Gary Gregory <[hidden email]>
> > >>>> Committed: Mon Apr 17 11:54:04 2017 -0700
> > >>>>
> > >>>> ------------------------------------------------------------
> > ----------
> > >>>> .../lang3/concurrent/annotation/Contract.java   | 50 +++++++++++++++
> > >>>> .../annotation/ThreadingBehavior.java           | 66
> > >>> ++++++++++++++++++++
> > >>>> 2 files changed, 116 insertions(+)
> > >>>> ------------------------------------------------------------
> > ----------
> > >>>>
> > >>>>
> > >>>> http://git-wip-us.apache.org/repos/asf/commons-lang/blob/
> > >>>
> a5e76ebc/src/main/java/org/apache/commons/lang3/concurrent/annotation/
> > >>> Contract.java
> > >>>> ------------------------------------------------------------
> > ----------
> > >>>> diff --git a/src/main/java/org/apache/commons/lang3/concurrent/
> > annotation/Contract.java
> > >>> b/src/main/java/org/apache/commons/lang3/concurrent/
> > >>> annotation/Contract.java
> > >>>> new file mode 100644
> > >>>> index 0000000..e34bb95
> > >>>> --- /dev/null
> > >>>> +++ b/src/main/java/org/apache/commons/lang3/concurrent/
> > >>> annotation/Contract.java
> > >>>> @@ -0,0 +1,50 @@
> > >>>> +/*
> > >>>> + * ============================================================
> > ========
> > >>>> + * Licensed to the Apache Software Foundation (ASF) under one
> > >>>> + * or more contributor license agreements.  See the NOTICE file
> > >>>> + * distributed with this work for additional information
> > >>>> + * regarding copyright ownership.  The ASF licenses this file
> > >>>> + * to you under the Apache License, Version 2.0 (the
> > >>>> + * "License"); you may not use this file except in compliance
> > >>>> + * with the License.  You may obtain a copy of the License at
> > >>>> + *
> > >>>> + *   http://www.apache.org/licenses/LICENSE-2.0
> > >>>> + *
> > >>>> + * Unless required by applicable law or agreed to in writing,
> > >>>> + * software distributed under the License is distributed on an
> > >>>> + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
> > >>>> + * KIND, either express or implied.  See the License for the
> > >>>> + * specific language governing permissions and limitations
> > >>>> + * under the License.
> > >>>> + * ============================================================
> > ========
> > >>>> + *
> > >>>> + * This software consists of voluntary contributions made by many
> > >>>> + * individuals on behalf of the Apache Software Foundation.  For
> more
> > >>>> + * information on the Apache Software Foundation, please see
> > >>>> + * <http://www.apache.org/>.
> > >>>> + *
> > >>>> + */
> > >>>> +package org.apache.commons.lang3.concurrent.annotation;
> > >>>> +
> > >>>> +import java.lang.annotation.Documented;
> > >>>> +import java.lang.annotation.ElementType;
> > >>>> +import java.lang.annotation.Retention;
> > >>>> +import java.lang.annotation.RetentionPolicy;
> > >>>> +import java.lang.annotation.Target;
> > >>>> +
> > >>>> +/**
> > >>>> + * This annotation defines behavioral contract enforced at runtime
> by
> > >>> instances of annotated classes.
> > >>>> + */
> > >>>> +@Documented
> > >>>> +@Target(ElementType.TYPE)
> > >>>> +@Retention(RetentionPolicy.CLASS)
> > >>>> +public @interface Contract {
> > >>>> +
> > >>>> +    /**
> > >>>> +     * Defines behavioral contract enforced at runtime by instances
> > of
> > >>> annotated classes.
> > >>>> +     *
> > >>>> +     * @return The behavioral contract enforced at runtime by
> > instances
> > >>> of annotated classes.
> > >>>> +     */
> > >>>> +    ThreadingBehavior threading() default ThreadingBehavior.UNSAFE;
> > >>>> +
> > >>>> +}
> > >>>>
> > >>>> http://git-wip-us.apache.org/repos/asf/commons-lang/blob/
> > >>>
> a5e76ebc/src/main/java/org/apache/commons/lang3/concurrent/annotation/
> > >>> ThreadingBehavior.java
> > >>>> ------------------------------------------------------------
> > ----------
> > >>>> diff --git a/src/main/java/org/apache/commons/lang3/concurrent/
> > >>> annotation/ThreadingBehavior.java b/src/main/java/org/apache/
> > >>> commons/lang3/concurrent/annotation/ThreadingBehavior.java
> > >>>> new file mode 100644
> > >>>> index 0000000..e03b164
> > >>>> --- /dev/null
> > >>>> +++ b/src/main/java/org/apache/commons/lang3/concurrent/
> > >>> annotation/ThreadingBehavior.java
> > >>>> @@ -0,0 +1,66 @@
> > >>>> +/*
> > >>>> + * ============================================================
> > ========
> > >>>> + * Licensed to the Apache Software Foundation (ASF) under one
> > >>>> + * or more contributor license agreements.  See the NOTICE file
> > >>>> + * distributed with this work for additional information
> > >>>> + * regarding copyright ownership.  The ASF licenses this file
> > >>>> + * to you under the Apache License, Version 2.0 (the
> > >>>> + * "License"); you may not use this file except in compliance
> > >>>> + * with the License.  You may obtain a copy of the License at
> > >>>> + *
> > >>>> + *   http://www.apache.org/licenses/LICENSE-2.0
> > >>>> + *
> > >>>> + * Unless required by applicable law or agreed to in writing,
> > >>>> + * software distributed under the License is distributed on an
> > >>>> + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
> > >>>> + * KIND, either express or implied.  See the License for the
> > >>>> + * specific language governing permissions and limitations
> > >>>> + * under the License.
> > >>>> + * ============================================================
> > ========
> > >>>> + *
> > >>>> + * This software consists of voluntary contributions made by many
> > >>>> + * individuals on behalf of the Apache Software Foundation.  For
> more
> > >>>> + * information on the Apache Software Foundation, please see
> > >>>> + * <http://www.apache.org/>.
> > >>>> + *
> > >>>> + */
> > >>>> +package org.apache.commons.lang3.concurrent.annotation;
> > >>>> +
> > >>>> +/**
> > >>>> + * Defines types of threading behavior enforced at runtime.
> > >>>> + */
> > >>>> +public enum ThreadingBehavior {
> > >>>> +
> > >>>> +    /**
> > >>>> +     * Instances of classes with the given contract are expected to
> > be
> > >>> fully immutable and thread-safe.
> > >>>> +     */
> > >>>> +    IMMUTABLE,
> > >>>> +
> > >>>> +    /**
> > >>>> +     * Instances of classes with the given contract are expected to
> > be
> > >>> immutable if their dependencies injected at
> > >>>> +     * construction time are immutable and are expected to be
> > >>> thread-safe if their dependencies are thread-safe.
> > >>>> +     */
> > >>>> +    IMMUTABLE_CONDITIONAL,
> > >>>> +
> > >>>> +    /**
> > >>>> +     * Instances of classes with the given contract are expected to
> > >>> maintain no state and to be thread-safe.
> > >>>> +     */
> > >>>> +    STATELESS,
> > >>>> +
> > >>>> +    /**
> > >>>> +     * Instances of classes with the given contract are expected to
> > be
> > >>> fully thread-safe.
> > >>>> +     */
> > >>>> +    SAFE,
> > >>>> +
> > >>>> +    /**
> > >>>> +     * Instances of classes with the given contract are expected to
> > be
> > >>> thread-safe if their dependencies injected at
> > >>>> +     * construction time are thread-safe.
> > >>>> +     */
> > >>>> +    SAFE_CONDITIONAL,
> > >>>> +
> > >>>> +    /**
> > >>>> +     * Instances of classes with the given contract are expected to
> > be
> > >>> non thread-safe.
> > >>>> +     */
> > >>>> +    UNSAFE
> > >>>> +
> > >>>> +}
> > >>>>
> > >>>
> > >>>
> > >>> ---------------------------------------------------------------------
> > >>> To unsubscribe, e-mail: [hidden email]
> > >>> For additional commands, e-mail: [hidden email]
> > >>>
> > >>>
> > >>
> > >>
> > >> --
> > >> E-Mail: [hidden email] | [hidden email]
> > >> 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
> > >
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: [hidden email]
> > > For additional commands, e-mail: [hidden email]
> > >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: [hidden email]
> > For additional commands, e-mail: [hidden email]
> >
> >
>
>
> --
> Matt Sicker <[hidden email]>
>