commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gary Gregory <garydgreg...@gmail.com>
Subject Re: [lang] [LANG-1291] Provide annotations to document thread safety.
Date Tue, 18 Apr 2017 06:46:22 GMT
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 <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

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