Remove annotations for documenting concurrency behavior.

As discussed on the ML, we need more time to figure out the design of
this annotations. So I'm removing them in order to get the next release
out of the door.
This commit is contained in:
Benedikt Ritter 2017-05-17 10:21:41 -04:00
parent 5a87fa172e
commit 796b051f28
No known key found for this signature in database
GPG Key ID: 9DAADC1C9FCC82D0
18 changed files with 0 additions and 681 deletions

View File

@ -1,50 +0,0 @@
/*
* ====================================================================
* 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;
}

View File

@ -1,39 +0,0 @@
/*
* 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;
/**
* Describes the lock which guards a field or method.
*/
@Documented
@Target({ ElementType.FIELD, ElementType.METHOD })
@Retention(RetentionPolicy.CLASS)
public @interface GuardedBy {
/**
* Gets the lock which guards a field or method.
*
* @return the lock which guards a field or method.
*/
String value();
}

View File

@ -1,33 +0,0 @@
/*
* 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;
/**
* Describes a type as immutable.
*/
@Documented
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.CLASS)
public @interface Immutable {
// marker annotation, empty body
}

View File

@ -1,35 +0,0 @@
/*
* 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;
/**
* Describes this type as not thread-safe.
*
* @see ThreadSafe
*/
@Documented
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.CLASS)
public @interface NotThreadSafe {
// marker annotation, empty body
}

View File

@ -1,35 +0,0 @@
/*
* 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;
/**
* Describes this type as thread-safe.
*
* @see NotThreadSafe
*/
@Documented
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.CLASS)
public @interface ThreadSafe {
// marker annotation, empty body
}

View File

@ -1,66 +0,0 @@
/*
* ====================================================================
* 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
}

View File

@ -1,22 +0,0 @@
/*
* 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.
*/
/**
* <p>Provides annotations to document classes' thread safety</p>
*
* @since 3.6
*/
package org.apache.commons.lang3.concurrent.annotation;

View File

@ -1,50 +0,0 @@
/*
* 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;
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);
}
}

View File

@ -1,38 +0,0 @@
/*
* 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 Contract}.
*/
public class ContractTest {
@Test
public void testClassAnnotationInClassFile() throws Exception {
AnnotationTestUtils.testClassAnnotationInClassFile(
"org.apache.commons.lang3.concurrent.annotation.ContractTestFixture",
"Lorg/apache/commons/lang3/concurrent/annotation/Contract;");
}
@Test
public void testMethodAnnotationNotRetainedAtRuntime() {
AnnotationTestUtils.testMethodAnnotationNotRetainedAtRuntime(ContractTestFixture.class, Contract.class);
}
}

View File

@ -1,25 +0,0 @@
/*
* 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}.
*/
@Contract()
public class ContractTestFixture {
// empty
}

View File

@ -1,65 +0,0 @@
/*
* 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);
}
}

View File

@ -1,32 +0,0 @@
/*
* 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
}
}

View File

@ -1,38 +0,0 @@
/*
* 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);
}
}

View File

@ -1,25 +0,0 @@
/*
* 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
}

View File

@ -1,39 +0,0 @@
/*
* 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);
}
}

View File

@ -1,25 +0,0 @@
/*
* 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
}

View File

@ -1,39 +0,0 @@
/*
* 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);
}
}

View File

@ -1,25 +0,0 @@
/*
* 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
}