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}