[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/release 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 + +}
