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:27:14 GMT
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


Mime
View raw message