Annotation Type ThreadSafety


  • @Documented
    @Retention(RUNTIME)
    @Target({TYPE,METHOD})
    public @interface ThreadSafety
    This annotation type may be used to indicate the level of thread safety for a class or method. Any class or interface which does not include the ThreadSafety annotation should be assumed to be not threadsafe unless otherwise specified in the documentation for that class or interface.

    If the ThreadSafety annotation is applied to a method, then it will override the class-level annotation for the scope of that method. That is, if a class is declared to be ThreadSafetyLevel.MOSTLY_NOT_THREADSAFE but a method within that class is declared to be ThreadSafetyLevel.METHOD_THREADSAFE, then that method may be invoked concurrently by multiple threads against the same instance. If a class is declared to be ThreadSafetyLevel.MOSTLY_THREADSAFE but a method within that class is declared to be ThreadSafetyLevel.METHOD_NOT_THREADSAFE, then that method must not be invoked on an instance while any other thread is attempting to access the same instance. Methods within a class may only be annotated with either the ThreadSafetyLevel.METHOD_THREADSAFE or ThreadSafetyLevel.METHOD_NOT_THREADSAFE level, and only if the class is annotated with one of the ThreadSafetyLevel.MOSTLY_THREADSAFE, ThreadSafetyLevel.MOSTLY_NOT_THREADSAFE, or ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE level. Classes annotated with either the ThreadSafetyLevel.COMPLETELY_THREADSAFE or ThreadSafetyLevel.NOT_THREADSAFE levels must not provide alternate method-level ThreadSafety annotations.

    Note that there are some caveats regarding thread safety and immutability of elements in the LDAP SDK that are true regardless of the stated thread safety level:
    • If an array is provided as an argument to a constructor or a method, then that array must not be referenced or altered by the caller at any time after that point unless it is clearly noted that it is acceptable to do so.

    • If an array is returned by a method, then the contents of that array must not be altered unless it is clearly noted that it is acceptable to do so.

    • If a method is intended to alter the state of an argument (e.g., appending to a StringBuilder or ByteBuffer or ByteStringBuffer, reading from a Reader or an InputStream, or writing to a Writer or OutputStream), then that object provided as an argument must not be accessed by any other thread while that method is active unless it is clearly noted that it is acceptable to do so.

    • Unless otherwise noted, public static methods may be assumed to be threadsafe independent of the thread safety level for the class that contains them.

    • Required Element Summary

      Required Elements 
      Modifier and Type Required Element Description
      ThreadSafetyLevel level
      The thread safety level for the associated class, interface, enum, or method.
    • Element Detail

      • level

        @NotNull
        ThreadSafetyLevel level
        The thread safety level for the associated class, interface, enum, or method.
        Returns:
        The thread safety level for the associated class, interface, enum, or method.