001 /*
002 * Copyright 2009-2016 UnboundID Corp.
003 * All Rights Reserved.
004 */
005 /*
006 * Copyright (C) 2009-2016 UnboundID Corp.
007 *
008 * This program is free software; you can redistribute it and/or modify
009 * it under the terms of the GNU General Public License (GPLv2 only)
010 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011 * as published by the Free Software Foundation.
012 *
013 * This program is distributed in the hope that it will be useful,
014 * but WITHOUT ANY WARRANTY; without even the implied warranty of
015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
016 * GNU General Public License for more details.
017 *
018 * You should have received a copy of the GNU General Public License
019 * along with this program; if not, see <http://www.gnu.org/licenses>.
020 */
021 package com.unboundid.util;
022
023
024
025 import java.lang.annotation.Documented;
026 import java.lang.annotation.ElementType;
027 import java.lang.annotation.Retention;
028 import java.lang.annotation.RetentionPolicy;
029 import java.lang.annotation.Target;
030
031
032
033 /**
034 * This annotation type may be used to indicate the level of thread safety for a
035 * class or method. Any class or interface which does not include the
036 * {@code ThreadSafety} annotation should be assumed to be not threadsafe unless
037 * otherwise specified in the documentation for that class or interface.
038 * <BR><BR>
039 * If the {@code ThreadSafety} annotation is applied to a method, then it will
040 * override the class-level annotation for the scope of that method. That is,
041 * if a class is declared to be {@code ThreadSafetyLevel.MOSTLY_NOT_THREADSAFE}
042 * but a method within that class is declared to be
043 * {@code ThreadSafetyLevel.METHOD_THREADSAFE}, then that method may be invoked
044 * concurrently by multiple threads against the same instance. If a class is
045 * declared to be {@code ThreadSafetyLevel.MOSTLY_THREADSAFE} but a method
046 * within that class is declared to be
047 * {@code ThreadSafetyLevel.METHOD_NOT_THREADSAFE}, then that method must not be
048 * invoked on an instance while any other thread is attempting to access the
049 * same instance. Methods within a class may only be annotated with either the
050 * {@code ThreadSafetyLevel.METHOD_THREADSAFE} or
051 * {@code ThreadSafetyLevel.METHOD_NOT_THREADSAFE} level, and only if the class
052 * is annotated with one of the {@code ThreadSafetyLevel.MOSTLY_THREADSAFE},
053 * {@code ThreadSafetyLevel.MOSTLY_NOT_THREADSAFE}, or
054 * {@code ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE} level. Classes annotated
055 * with either the {@code ThreadSafetyLevel.COMPLETELY_THREADSAFE} or
056 * {@code ThreadSafetyLevel.NOT_THREADSAFE} levels must not provide alternate
057 * method-level {@code ThreadSafety} annotations.
058 * <BR><BR>
059 * Note that there are some caveats regarding thread safety and immutability of
060 * elements in the LDAP SDK that are true regardless of the stated thread safety
061 * level:
062 * <UL>
063 * <LI>
064 * If an array is provided as an argument to a constructor or a method, then
065 * that array must not be referenced or altered by the caller at any time
066 * after that point unless it is clearly noted that it is acceptable to do
067 * so.
068 * <BR><BR>
069 * </LI>
070 *
071 * <LI>
072 * If an array is returned by a method, then the contents of that array must
073 * not be altered unless it is clearly noted that it is acceptable to do so.
074 * <BR><BR>
075 * </LI>
076 *
077 * <LI>
078 * If a method is intended to alter the state of an argument (e.g.,
079 * appending to a {@code StringBuilder} or {@code ByteBuffer} or
080 * {@code ByteStringBuffer}, reading from a {@code Reader} or an
081 * {@code InputStream}, or writing to a {@code Writer} or
082 * {@code OutputStream}), then that object provided as an argument must not
083 * be accessed by any other thread while that method is active unless it is
084 * clearly noted that it is acceptable to do so.
085 * <BR><BR>
086 * </LI>
087 *
088 * <LI>
089 * Unless otherwise noted, public static methods may be assumed to be
090 * threadsafe independent of the thread safety level for the class that
091 * contains them.
092 * <BR><BR>
093 * </LI>
094 * </UL>
095 */
096 @Documented()
097 @Retention(RetentionPolicy.RUNTIME)
098 @Target({ ElementType.TYPE, ElementType.METHOD })
099 public @interface ThreadSafety
100 {
101 /**
102 * The thread safety level for the associated class, interface, enum, or
103 * method.
104 */
105 ThreadSafetyLevel level();
106 }