commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Benedikt Ritter <brit...@apache.org>
Subject Re: [lang] [LANG-1291] Provide annotations to document thread safety.
Date Tue, 18 Apr 2017 06:49:35 GMT
Hi,

> Am 18.04.2017 um 08:46 schrieb Gary Gregory <garydgregory@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 <britter@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 ggregory@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 <garydgregory@gmail.com>
>>> Authored: Mon Apr 17 11:54:04 2017 -0700
>>> Committer: Gary Gregory <garydgregory@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-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=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-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message