001/* 002 * Copyright 2009-2014 UnboundID Corp. 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright (C) 2009-2014 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 */ 021package com.unboundid.util; 022 023 024 025import java.lang.annotation.Documented; 026import java.lang.annotation.ElementType; 027import java.lang.annotation.Retention; 028import java.lang.annotation.RetentionPolicy; 029import 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 }) 099public @interface ThreadSafety 100{ 101 /** 102 * The thread safety level for the associated class, interface, enum, or 103 * method. 104 */ 105 ThreadSafetyLevel level(); 106}