[LANG-1291] Provide annotations to document thread safety.

NOTICE.txt

@@ -6,3 +6,8 @@ The Apache Software Foundation (http://www.apache.org/).
 
 This product includes software from the Spring Framework,
 under the Apache License 2.0 (see: StringUtils.containsWhitespace())
+
+This product includes software Copyright (c) 2005 Brian Goetz and Tim Peierls
+Released under the Creative Commons Attribution License (http://creativecommons.org/licenses/by/2.5)
+Official home: http://www.jcip.net
+Any republication or derived work distributed in source code form must include this copyright and license notice.

pom.xml

@@ -526,6 +526,13 @@
       <scope>test</scope>
     </dependency>
 
+    <dependency>
+      <groupId>org.apache.bcel</groupId>
+      <artifactId>bcel</artifactId>
+      <version>6.0</version>
+      <scope>test</scope>
+    </dependency>
+
     <dependency>
       <groupId>org.easymock</groupId>
       <artifactId>easymock</artifactId>

src/changes/changes.xml

@@ -63,6 +63,7 @@ The <action> type attribute can be add,update,fix,remove.
     <action issue="LANG-1258" type="add" dev="pschumacher" due-to="IG, Grzegorz Rożniecki">Add ArrayUtils#toStringArray method</action>
     <action issue="LANG-1160" type="add" dev="kinow">StringUtils#abbreviate should support 'custom ellipses' parameter</action>
     <action issue="LANG-1270" type="add" dev="pschumacher" due-to="Pierre Templier">Add StringUtils#isAnyNotEmpty and #isAnyNotBlank</action>
+    <action issue="LANG-1291" type="add" dev="ggregory">Provide annotations to document thread safety</action>
     <action issue="LANG-1290" type="update" dev="pschumacher" due-to="Andrii Abramov">Increase test coverage of org.apache.commons.lang3.ArrayUtils</action>
     <action issue="LANG-1274" type="update" dev="pschumacher">StrSubstitutor should state its thread safety</action>
     <action issue="LANG-1277" type="update" dev="pschumacher" due-to="yufcuy">StringUtils#getLevenshteinDistance reduce memory consumption</action>

src/main/java/org/apache/commons/lang3/concurrent/annotation/GuardedBy.java

@@ -0,0 +1,78 @@
+/*
+ * 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.
+ */
+package org.apache.commons.lang3.concurrent.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/*
+ * Copyright (c) 2005 Brian Goetz
+ * Released under the Creative Commons Attribution License
+ *   (http://creativecommons.org/licenses/by/2.5)
+ * Official home: http://www.jcip.net
+ *
+ * Any republication or derived work distributed in source code form
+ * must include this copyright and license notice.
+ */
+
+/**
+ * GuardedBy
+ * 
+ * The field or method to which this annotation is applied can only be accessed
+ * when holding a particular lock, which may be a built-in (synchronization)
+ * lock, or may be an explicit java.util.concurrent.Lock.
+ * 
+ * The argument determines which lock guards the annotated field or method: this
+ * : The string literal "this" means that this field is guarded by the class in
+ * which it is defined. class-name.this : For inner classes, it may be necessary
+ * to disambiguate 'this'; the class-name.this designation allows you to specify
+ * which 'this' reference is intended itself : For reference fields only; the
+ * object to which the field refers. field-name : The lock object is referenced
+ * by the (instance or static) field specified by field-name.
+ * class-name.field-name : The lock object is reference by the static field
+ * specified by class-name.field-name. method-name() : The lock object is
+ * returned by calling the named nil-ary method. class-name.class : The Class
+ * object for the specified class should be used as the lock object.
+ */
+@Target({ ElementType.FIELD, ElementType.METHOD })
+@Retention(RetentionPolicy.CLASS)
+public @interface GuardedBy {
+
+    /**
+     * The field or method to which this annotation is applied can only be
+     * accessed when holding a particular lock, which may be a built-in
+     * (synchronization) lock, or may be an explicit java.util.concurrent.Lock.
+     * 
+     * The argument determines which lock guards the annotated field or method:
+     * this : The string literal "this" means that this field is guarded by the
+     * class in which it is defined. class-name.this : For inner classes, it may
+     * be necessary to disambiguate 'this'; the class-name.this designation
+     * allows you to specify which 'this' reference is intended itself : For
+     * reference fields only; the object to which the field refers. field-name :
+     * The lock object is referenced by the (instance or static) field specified
+     * by field-name. class-name.field-name : The lock object is reference by
+     * the static field specified by class-name.field-name. method-name() : The
+     * lock object is returned by calling the named nil-ary method.
+     * class-name.class : The Class object for the specified class should be
+     * used as the lock object.
+     * 
+     * @return see description
+     */
+    String value();
+}

src/main/java/org/apache/commons/lang3/concurrent/annotation/Immutable.java

@@ -0,0 +1,56 @@
+/*
+ * 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.
+ */
+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;
+
+/*
+ * Copyright (c) 2005 Brian Goetz
+ * Released under the Creative Commons Attribution License
+ *   (http://creativecommons.org/licenses/by/2.5)
+ * Official home: http://www.jcip.net
+ *
+ * Any republication or derived work distributed in source code form
+ * must include this copyright and license notice.
+ */
+
+/**
+ * Immutable
+ * 
+ * The class to which this annotation is applied is immutable. This means that
+ * its state cannot be seen to change by callers. Of necessity this means that
+ * all public fields are final, and that all public final reference fields refer
+ * to other immutable objects, and that methods do not publish references to any
+ * internal state which is mutable by implementation even if not by design.
+ * Immutable objects may still have internal mutable state for purposes of
+ * performance optimization; some state variables may be lazily computed, so
+ * long as they are computed from immutable state and that callers cannot tell
+ * the difference.
+ * 
+ * Immutable objects are inherently thread-safe; they may be passed between
+ * threads or published without synchronization.
+ */
+@Documented
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.CLASS)
+public @interface Immutable {
+    // marker annotation, empty body
+}

src/main/java/org/apache/commons/lang3/concurrent/annotation/NotThreadSafe.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.
+ */
+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;
+
+/*
+ * Copyright (c) 2005 Brian Goetz
+ * Released under the Creative Commons Attribution License
+ *   (http://creativecommons.org/licenses/by/2.5)
+ * Official home: http://www.jcip.net
+ *
+ * Any republication or derived work distributed in source code form
+ * must include this copyright and license notice.
+ */
+
+/**
+ * NotThreadSafe
+ * 
+ * The class to which this annotation is applied is not thread-safe. This
+ * annotation primarily exists for clarifying the non-thread-safety of a class
+ * that might otherwise be assumed to be thread-safe, despite the fact that it
+ * is a bad idea to assume a class is thread-safe without good reason.
+ * 
+ * @see ThreadSafe
+ */
+@Documented
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.CLASS)
+public @interface NotThreadSafe {
+    // marker annotation, empty body
+}

src/main/java/org/apache/commons/lang3/concurrent/annotation/ThreadSafe.java

@@ -0,0 +1,47 @@
+/*
+ * 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.
+ */
+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;
+
+/*
+ * Copyright (c) 2005 Brian Goetz and Tim Peierls
+ * Released under the Creative Commons Attribution License
+ *   (http://creativecommons.org/licenses/by/2.5)
+ * Official home: http://www.jcip.net
+ *
+ * Any republication or derived work distributed in source code form
+ * must include this copyright and license notice.
+ */
+
+/**
+ * The class to which this annotation is applied is thread-safe.  This means that
+ * no sequences of accesses (reads and writes to public fields, calls to public methods)
+ * may put the object into an invalid state, regardless of the interleaving of those actions
+ * by the runtime, and without requiring any additional synchronization or coordination on the
+ * part of the caller.
+ */
+@Documented
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.CLASS)
+public @interface ThreadSafe {
+    // marker annotation, empty body
+}

src/test/java/org/apache/commons/lang3/concurrent/annotation/AnnotationTestUtils.java

@@ -0,0 +1,52 @@
+/*
+ * 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.
+ */
+package org.apache.commons.lang3.concurrent.annotation;
+
+import java.lang.annotation.Annotation;
+import java.lang.reflect.Method;
+
+import org.apache.bcel.Repository;
+import org.apache.bcel.classfile.AnnotationEntry;
+import org.apache.bcel.classfile.ElementValuePair;
+import org.apache.bcel.classfile.JavaClass;
+import org.apache.commons.lang3.reflect.MethodUtils;
+import org.junit.Assert;
+import org.junit.Test;
+
+class AnnotationTestUtils {
+
+    public static void testClassAnnotationInClassFile(final String className, final String annotationType) throws Exception {
+        final JavaClass clazz = Repository.lookupClass(className);
+        final AnnotationEntry[] annotationEntries = clazz.getAnnotationEntries();
+        Assert.assertNotNull(annotationEntries);
+        Assert.assertEquals(1, annotationEntries.length);
+        final AnnotationEntry annotationEntry = annotationEntries[0];
+        Assert.assertEquals(annotationType, annotationEntry .getAnnotationType());
+        final ElementValuePair[] elementValuePairs = annotationEntry.getElementValuePairs();
+        Assert.assertNotNull(elementValuePairs);
+        Assert.assertEquals(0, elementValuePairs.length);
+    }
+    
+    public static void testMethodAnnotationNotRetainedAtRuntime(final Class<?> cls,
+            final Class<? extends Annotation> annotationCls) {
+        final Method[] methods = MethodUtils.getMethodsWithAnnotation(cls, annotationCls);
+        Assert.assertNotNull(methods);
+        Assert.assertEquals(0, methods.length);
+    }
+
+
+}

src/test/java/org/apache/commons/lang3/concurrent/annotation/GuardedByTest.java

@@ -0,0 +1,65 @@
+/*
+ * 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.
+ */
+package org.apache.commons.lang3.concurrent.annotation;
+
+import org.apache.bcel.Repository;
+import org.apache.bcel.classfile.AnnotationEntry;
+import org.apache.bcel.classfile.ElementValue;
+import org.apache.bcel.classfile.ElementValuePair;
+import org.apache.bcel.classfile.JavaClass;
+import org.junit.Assert;
+import org.junit.Test;
+
+/**
+ * Tests {@link GuardedBy}.
+ */
+public class GuardedByTest {
+
+    private org.apache.bcel.classfile.Method getBcelMethod(final JavaClass clazz, final String name) {
+        for (final org.apache.bcel.classfile.Method method : clazz.getMethods()) {
+            if (method.getName().equals(name)) {
+                return method;
+            }
+        }
+        return null;
+    }
+
+    @Test
+    public void testMethodAnnotationInClassFile() throws Exception {
+        final JavaClass clazz = Repository.lookupClass("org.apache.commons.lang3.concurrent.annotation.GuardedByTestFixture");
+        final org.apache.bcel.classfile.Method method = getBcelMethod(clazz, "foo");
+        Assert.assertNotNull(method);
+        final AnnotationEntry[] annotationEntries = method.getAnnotationEntries();
+        Assert.assertNotNull(annotationEntries);
+        Assert.assertEquals(1, annotationEntries.length);
+        final AnnotationEntry annotationEntry = annotationEntries[0];
+        Assert.assertEquals("Lorg/apache/commons/lang3/concurrent/annotation/GuardedBy;", annotationEntry .getAnnotationType());
+        final ElementValuePair[] elementValuePairs = annotationEntry.getElementValuePairs();
+        Assert.assertNotNull(elementValuePairs);
+        Assert.assertEquals(1, elementValuePairs.length);
+        final ElementValuePair elementValuePair = elementValuePairs[0];
+        final ElementValue value = elementValuePair.getValue();
+        Assert.assertNotNull(value);
+        Assert.assertEquals("bar", value.toString());
+    }
+
+    @Test
+    public void testMethodAnnotationNotRetainedAtRuntime() {
+        AnnotationTestUtils.testMethodAnnotationNotRetainedAtRuntime(GuardedByTestFixture.class, GuardedBy.class);
+    }
+
+}

src/test/java/org/apache/commons/lang3/concurrent/annotation/GuardedByTestFixture.java

@@ -0,0 +1,32 @@
+/*
+ * 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.
+ */
+package org.apache.commons.lang3.concurrent.annotation;
+
+/**
+ * Tests {@link GuardedBy}.
+ */
+public class GuardedByTestFixture {
+
+    @GuardedBy("ping")
+    private Object pong;
+    
+    @GuardedBy("bar")
+    public void foo() {
+        // empty
+    }
+
+}

src/test/java/org/apache/commons/lang3/concurrent/annotation/ImmutableTest.java

@@ -0,0 +1,38 @@
+/*
+ * 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.
+ */
+package org.apache.commons.lang3.concurrent.annotation;
+
+import org.junit.Test;
+
+/**
+ * Tests {@link GuardedBy}.
+ */
+public class ImmutableTest {
+
+    @Test
+    public void testClassAnnotationInClassFile() throws Exception {
+        AnnotationTestUtils.testClassAnnotationInClassFile(
+                "org.apache.commons.lang3.concurrent.annotation.ImmutableTestFixture",
+                "Lorg/apache/commons/lang3/concurrent/annotation/Immutable;");
+    }
+
+    @Test
+    public void testMethodAnnotationNotRetainedAtRuntime() {
+        AnnotationTestUtils.testMethodAnnotationNotRetainedAtRuntime(ImmutableTestFixture.class, Immutable.class);
+    }
+
+}

src/test/java/org/apache/commons/lang3/concurrent/annotation/ImmutableTestFixture.java

@@ -0,0 +1,25 @@
+/*
+ * 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.
+ */
+package org.apache.commons.lang3.concurrent.annotation;
+
+/**
+ * Tests {@link Immutable}.
+ */
+@Immutable
+public class ImmutableTestFixture {
+    // empty
+}

src/test/java/org/apache/commons/lang3/concurrent/annotation/NotThreadSafeTest.java

@@ -0,0 +1,39 @@
+/*
+ * 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.
+ */
+package org.apache.commons.lang3.concurrent.annotation;
+
+import org.junit.Test;
+
+/**
+ * Tests {@link NotThreadSafe}.
+ */
+public class NotThreadSafeTest {
+
+    @Test
+    public void testClassAnnotationInClassFile() throws Exception {
+        AnnotationTestUtils.testClassAnnotationInClassFile(
+                "org.apache.commons.lang3.concurrent.annotation.NotThreadSafeTestFixture",
+                "Lorg/apache/commons/lang3/concurrent/annotation/NotThreadSafe;");
+    }
+
+    @Test
+    public void testMethodAnnotationNotRetainedAtRuntime() {
+        AnnotationTestUtils.testMethodAnnotationNotRetainedAtRuntime(NotThreadSafeTestFixture.class,
+                NotThreadSafe.class);
+    }
+
+}

src/test/java/org/apache/commons/lang3/concurrent/annotation/NotThreadSafeTestFixture.java

@@ -0,0 +1,25 @@
+/*
+ * 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.
+ */
+package org.apache.commons.lang3.concurrent.annotation;
+
+/**
+ * Tests {@link NotThreadSafe}.
+ */
+@NotThreadSafe
+public class NotThreadSafeTestFixture {
+    // empty
+}

src/test/java/org/apache/commons/lang3/concurrent/annotation/ThreadSafeTest.java

@@ -0,0 +1,39 @@
+/*
+ * 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.
+ */
+package org.apache.commons.lang3.concurrent.annotation;
+
+import org.junit.Test;
+
+/**
+ * Tests {@link ThreadSafe}.
+ */
+public class ThreadSafeTest {
+
+    @Test
+    public void testClassAnnotationInClassFile() throws Exception {
+        AnnotationTestUtils.testClassAnnotationInClassFile(
+                "org.apache.commons.lang3.concurrent.annotation.ThreadSafeTestFixture",
+                "Lorg/apache/commons/lang3/concurrent/annotation/ThreadSafe;");
+    }
+
+    @Test
+    public void testMethodAnnotationNotRetainedAtRuntime() {
+        AnnotationTestUtils.testMethodAnnotationNotRetainedAtRuntime(ThreadSafeTestFixture.class,
+                ThreadSafe.class);
+    }
+
+}

src/test/java/org/apache/commons/lang3/concurrent/annotation/ThreadSafeTestFixture.java

@@ -0,0 +1,25 @@
+/*
+ * 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.
+ */
+package org.apache.commons.lang3.concurrent.annotation;
+
+/**
+ * Tests {@link ThreadSafe}.
+ */
+@ThreadSafe
+public class ThreadSafeTestFixture {
+    // empty
+}