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 <brit...@apache.org> wrote:
> Hi,
>
>> Am 18.04.2017 um 08:46 schrieb Gary Gregory <garydgreg...@gmail.com>:
>>
>> 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 <brit...@apache.org>
>> 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 ggreg...@apache.org:
>>>>
>>>> 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 <garydgreg...@gmail.com>
>>>> Authored: Mon Apr 17 11:54:04 2017 -0700
>>>> Committer: Gary Gregory <garydgreg...@gmail.com>
>>>> 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: 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=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: 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
