Initial commit

resources/javax/annotation/CheckForNull.java

@@ -0,0 +1,16 @@
+package javax.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+import javax.annotation.meta.TypeQualifierNickname;
+import javax.annotation.meta.When;
+
+@Documented
+@TypeQualifierNickname
+@Nonnull(when = When.MAYBE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface CheckForNull {
+
+}

resources/javax/annotation/CheckForSigned.java

@@ -0,0 +1,24 @@
+package javax.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+import javax.annotation.meta.TypeQualifierNickname;
+import javax.annotation.meta.When;
+
+/**
+ * Used to annotate a value that may be either negative or nonnegative, and
+ * indicates that uses of it should check for
+ * negative values before using it in a way that requires the value to be
+ * nonnegative, and check for it being nonnegative before using it in a way that
+ * requires it to be negative.
+ */
+
+@Documented
+@TypeQualifierNickname
+@Nonnegative(when = When.MAYBE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface CheckForSigned {
+
+}

resources/javax/annotation/CheckReturnValue.java

@@ -0,0 +1,17 @@
+package javax.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;
+
+import javax.annotation.meta.When;
+
+@Documented
+@Target( { ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.TYPE,
+        ElementType.PACKAGE })
+@Retention(RetentionPolicy.RUNTIME)
+public @interface CheckReturnValue {
+    When when() default When.ALWAYS;
+}

resources/javax/annotation/Detainted.java

@@ -0,0 +1,16 @@
+package javax.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+import javax.annotation.meta.TypeQualifierNickname;
+import javax.annotation.meta.When;
+
+@Documented
+@TypeQualifierNickname
+@Untainted(when = When.ALWAYS)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Detainted {
+
+}

resources/javax/annotation/MatchesPattern.java

@@ -0,0 +1,30 @@
+package javax.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.util.regex.Pattern;
+
+import javax.annotation.meta.TypeQualifier;
+import javax.annotation.meta.TypeQualifierValidator;
+import javax.annotation.meta.When;
+
+@Documented
+@TypeQualifier(applicableTo = String.class)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface MatchesPattern {
+    @RegEx
+    String value();
+
+    int flags() default 0;
+
+    static class Checker implements TypeQualifierValidator<MatchesPattern> {
+        public When forConstantValue(MatchesPattern annotation, Object value) {
+            Pattern p = Pattern.compile(annotation.value(), annotation.flags());
+            if (p.matcher(((String) value)).matches())
+                return When.ALWAYS;
+            return When.NEVER;
+        }
+
+    }
+}

resources/javax/annotation/Nonnegative.java

@@ -0,0 +1,41 @@
+package javax.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+import javax.annotation.meta.TypeQualifier;
+import javax.annotation.meta.TypeQualifierValidator;
+import javax.annotation.meta.When;
+
+/** Used to annotate a value that should only contain nonnegative values */
+@Documented
+@TypeQualifier(applicableTo = Number.class)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Nonnegative {
+    When when() default When.ALWAYS;
+
+    class Checker implements TypeQualifierValidator<Nonnegative> {
+
+        public When forConstantValue(Nonnegative annotation, Object v) {
+            if (!(v instanceof Number))
+                return When.NEVER;
+            boolean isNegative;
+            Number value = (Number) v;
+            if (value instanceof Long)
+                isNegative = value.longValue() < 0;
+            else if (value instanceof Double)
+                isNegative = value.doubleValue() < 0;
+            else if (value instanceof Float)
+                isNegative = value.floatValue() < 0;
+            else
+                isNegative = value.intValue() < 0;
+
+            if (isNegative)
+                return When.NEVER;
+            else
+                return When.ALWAYS;
+
+        }
+    }
+}

resources/javax/annotation/Nonnull.java

@@ -0,0 +1,26 @@
+package javax.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+import javax.annotation.meta.TypeQualifier;
+import javax.annotation.meta.TypeQualifierValidator;
+import javax.annotation.meta.When;
+
+@Documented
+@TypeQualifier
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Nonnull {
+    When when() default When.ALWAYS;
+
+    static class Checker implements TypeQualifierValidator<Nonnull> {
+
+        public When forConstantValue(Nonnull qualifierqualifierArgument,
+                Object value) {
+            if (value == null)
+                return When.NEVER;
+            return When.ALWAYS;
+        }
+    }
+}

resources/javax/annotation/Nullable.java

@@ -0,0 +1,16 @@
+package javax.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+import javax.annotation.meta.TypeQualifierNickname;
+import javax.annotation.meta.When;
+
+@Documented
+@TypeQualifierNickname
+@Nonnull(when = When.UNKNOWN)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Nullable {
+
+}

resources/javax/annotation/OverridingMethodsMustInvokeSuper.java

@@ -0,0 +1,20 @@
+package javax.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;
+
+/**
+ * When this annotation is applied to a method, it indicates that if this method
+ * is overridden in a subclass, the overriding method should invoke this method
+ * (through method invocation on super).
+ * 
+ */
+@Documented
+@Target( { ElementType.METHOD })
+@Retention(RetentionPolicy.RUNTIME)
+public @interface OverridingMethodsMustInvokeSuper {
+
+}

resources/javax/annotation/ParametersAreNonnullByDefault.java

@@ -0,0 +1,27 @@
+package javax.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+import javax.annotation.meta.TypeQualifierDefault;
+
+/**
+ * This annotation can be applied to a package, class or method to indicate that
+ * the method parameters in that element are nonnull by default unless there is:
+ * <ul>
+ * <li>An explicit nullness annotation
+ * <li>The method overrides a method in a superclass (in which case the
+ * annotation of the corresponding parameter in the superclass applies)
+ * <li> there is a default parameter annotation applied to a more tightly nested
+ * element.
+ * </ul>
+ * 
+ */
+@Documented
+@Nonnull
+@TypeQualifierDefault(ElementType.PARAMETER)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface ParametersAreNonnullByDefault {
+}

resources/javax/annotation/PropertyKey.java

@@ -0,0 +1,15 @@
+package javax.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+import javax.annotation.meta.TypeQualifier;
+import javax.annotation.meta.When;
+
+@Documented
+@TypeQualifier
+@Retention(RetentionPolicy.RUNTIME)
+public @interface PropertyKey {
+    When when() default When.ALWAYS;
+}

resources/javax/annotation/RegEx.java

@@ -0,0 +1,42 @@
+package javax.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.util.regex.Pattern;
+import java.util.regex.PatternSyntaxException;
+
+import javax.annotation.meta.TypeQualifierNickname;
+import javax.annotation.meta.TypeQualifierValidator;
+import javax.annotation.meta.When;
+
+/**
+ * This qualifier is used to denote String values that should be a Regular
+ * expression.
+ * 
+ */
+@Documented
+@Syntax("RegEx")
+@TypeQualifierNickname
+@Retention(RetentionPolicy.RUNTIME)
+public @interface RegEx {
+    When when() default When.ALWAYS;
+
+    static class Checker implements TypeQualifierValidator<RegEx> {
+
+        public When forConstantValue(RegEx annotation, Object value) {
+            if (!(value instanceof String))
+                return When.NEVER;
+
+            try {
+                Pattern.compile((String) value);
+            } catch (PatternSyntaxException e) {
+                return When.NEVER;
+            }
+            return When.ALWAYS;
+
+        }
+
+    }
+
+}

resources/javax/annotation/Signed.java

@@ -0,0 +1,18 @@
+package javax.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+import javax.annotation.meta.TypeQualifierNickname;
+import javax.annotation.meta.When;
+
+/** Used to annotate a value of unknown sign */
+
+@Documented
+@TypeQualifierNickname
+@Nonnegative(when = When.UNKNOWN)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Signed {
+
+}

resources/javax/annotation/Syntax.java

@@ -0,0 +1,44 @@
+package javax.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+import javax.annotation.meta.TypeQualifier;
+import javax.annotation.meta.When;
+
+/**
+ * This annotation a value that is of a particular syntax, such as Java syntax
+ * or regular expression syntax. This can be used to provide syntax checking of
+ * constant values at compile time, run time checking at runtime, and can assist
+ * IDEs in deciding how to interpret String constants (e.g., should a
+ * refactoring that renames method x() to y() update the String constant "x()").
+ * 
+ * 
+ */
+@Documented
+@TypeQualifier(applicableTo = String.class)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Syntax {
+    /**
+     * Value indicating the particular syntax denoted by this annotation.
+     * Different tools will recognize different syntaxes, but some proposed
+     * canonical values are:
+     * <ul>
+     * <li> "Java"
+     * <li> "RegEx"
+     * <li> "JavaScript"
+     * <li> "Ruby"
+     * <li> "Groovy"
+     * <li> "SQL"
+     * <li> "FormatString"
+     * </ul>
+     * 
+     * Syntax names can be followed by a colon and a list of key value pairs,
+     * separated by commas. For example, "SQL:dialect=Oracle,version=2.3". Tools
+     * should ignore any keys they don't recognize.
+     */
+    String value();
+
+    When when() default When.ALWAYS;
+}

resources/javax/annotation/Tainted.java

@@ -0,0 +1,16 @@
+package javax.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+import javax.annotation.meta.TypeQualifierNickname;
+import javax.annotation.meta.When;
+
+@Documented
+@TypeQualifierNickname
+@Untainted(when = When.MAYBE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Tainted {
+
+}

resources/javax/annotation/Untainted.java

@@ -0,0 +1,15 @@
+package javax.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+import javax.annotation.meta.TypeQualifier;
+import javax.annotation.meta.When;
+
+@Documented
+@TypeQualifier
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Untainted {
+    When when() default When.ALWAYS;
+}

resources/javax/annotation/WillClose.java

@@ -0,0 +1,15 @@
+package javax.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+/**
+ * Used to annotate a method parameter to indicate that this method will close
+ * the resource.
+ */
+public @interface WillClose {
+
+}

resources/javax/annotation/WillCloseWhenClosed.java

@@ -0,0 +1,15 @@
+package javax.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+/**
+ * Used to annotate a constructor/factory parameter to indicate that returned
+ * object (X) will close the resource when X is closed.
+ */
+public @interface WillCloseWhenClosed {
+
+}

resources/javax/annotation/WillNotClose.java

@@ -0,0 +1,15 @@
+package javax.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+/**
+ * Used to annotate a method parameter to indicate that this method will not
+ * close the resource.
+ */
+public @interface WillNotClose {
+
+}

resources/javax/annotation/concurrent/GuardedBy.java

@@ -0,0 +1,38 @@
+package javax.annotation.concurrent;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/*
+ * Copyright (c) 2005 Brian Goetz
+ * Released under the Creative Commons Attribution License
+ *   (http://creativecommons.org/licenses/by/2.5)
+ * Official home: http://www.jcip.net
+ */
+
+/**
+ * GuardedBy
+ * 
+ * The field or method to which this annotation is applied can only be accessed
+ * when holding a particular lock, which may be a built-in (synchronization)
+ * lock, or may be an explicit java.util.concurrent.Lock.
+ * 
+ * The argument determines which lock guards the annotated field or method: this :
+ * The string literal "this" means that this field is guarded by the class in
+ * which it is defined. class-name.this : For inner classes, it may be necessary
+ * to disambiguate 'this'; the class-name.this designation allows you to specify
+ * which 'this' reference is intended itself : For reference fields only; the
+ * object to which the field refers. field-name : The lock object is referenced
+ * by the (instance or static) field specified by field-name.
+ * class-name.field-name : The lock object is reference by the static field
+ * specified by class-name.field-name. method-name() : The lock object is
+ * returned by calling the named nil-ary method. class-name.class : The Class
+ * object for the specified class should be used as the lock object.
+ */
+@Target( { ElementType.FIELD, ElementType.METHOD })
+@Retention(RetentionPolicy.CLASS)
+public @interface GuardedBy {
+    String value();
+}

resources/javax/annotation/concurrent/Immutable.java

@@ -0,0 +1,36 @@
+package javax.annotation.concurrent;
+
+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;
+
+/*
+ * Copyright (c) 2005 Brian Goetz
+ * Released under the Creative Commons Attribution License
+ *   (http://creativecommons.org/licenses/by/2.5)
+ * Official home: http://www.jcip.net
+ */
+
+/**
+ * Immutable
+ * 
+ * The class to which this annotation is applied is immutable. This means that
+ * its state cannot be seen to change by callers. Of necessity this means that
+ * all public fields are final, and that all public final reference fields refer
+ * to other immutable objects, and that methods do not publish references to any
+ * internal state which is mutable by implementation even if not by design.
+ * Immutable objects may still have internal mutable state for purposes of
+ * performance optimization; some state variables may be lazily computed, so
+ * long as they are computed from immutable state and that callers cannot tell
+ * the difference.
+ * 
+ * Immutable objects are inherently thread-safe; they may be passed between
+ * threads or published without synchronization.
+ */
+@Documented
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.CLASS)
+public @interface Immutable {
+}

resources/javax/annotation/concurrent/NotThreadSafe.java

@@ -0,0 +1,30 @@
+package javax.annotation.concurrent;
+
+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;
+
+/*
+ * Copyright (c) 2005 Brian Goetz
+ * Released under the Creative Commons Attribution License
+ *   (http://creativecommons.org/licenses/by/2.5)
+ * Official home: http://www.jcip.net
+ */
+
+/**
+ * NotThreadSafe
+ * 
+ * The class to which this annotation is applied is not thread-safe. This
+ * annotation primarily exists for clarifying the non-thread-safety of a class
+ * that might otherwise be assumed to be thread-safe, despite the fact that it
+ * is a bad idea to assume a class is thread-safe without good reason.
+ * 
+ * @see ThreadSafe
+ */
+@Documented
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.CLASS)
+public @interface NotThreadSafe {
+}

resources/javax/annotation/concurrent/ThreadSafe.java

@@ -0,0 +1,22 @@
+package javax.annotation.concurrent;
+
+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;
+
+/**
+ * ThreadSafe
+ * 
+ * The class to which this annotation is applied is thread-safe. This means that
+ * no sequences of accesses (reads and writes to public fields, calls to public
+ * methods) may put the object into an invalid state, regardless of the
+ * interleaving of those actions by the runtime, and without requiring any
+ * additional synchronization or coordination on the part of the caller.
+ */
+@Documented
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.CLASS)
+public @interface ThreadSafe {
+}

resources/javax/annotation/meta/Exclusive.java

@@ -0,0 +1,26 @@
+package javax.annotation.meta;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/**
+ * This annotation can be applied to the value() element of an annotation that
+ * is annotated as a TypeQualifier.
+ * 
+ * For example, the following defines a type qualifier such that if you know a
+ * value is {@literal @Foo(1)}, then the value cannot be {@literal @Foo(2)} or {{@literal @Foo(3)}.
+ * 
+ * <code>
+ * @TypeQualifier @interface Foo {
+ *     @Exclusive int value();
+ *     }
+ *  </code>
+ * 
+ */
+
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Exclusive {
+
+}

resources/javax/annotation/meta/Exhaustive.java

@@ -0,0 +1,33 @@
+package javax.annotation.meta;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/**
+ * This annotation can be applied to the value() element of an annotation that
+ * is annotated as a TypeQualifier. This is only appropriate if the value field
+ * returns a value that is an Enumeration.
+ * 
+ * Applications of the type qualifier with different values are exclusive, and
+ * the enumeration is an exhaustive list of the possible values.
+ * 
+ * For example, the following defines a type qualifier such that if you know a
+ * value is neither {@literal @Foo(Color.Red)} or {@literal @Foo(Color.Blue)},
+ * then the value must be {@literal @Foo(Color.Green)}. And if you know it is
+ * {@literal @Foo(Color.Green)}, you know it cannot be
+ * {@literal @Foo(Color.Red)} or {@literal @Foo(Color.Blue)}
+ * 
+ * <code>
+ * @TypeQualifier  @interface Foo {
+ *     enum Color {RED, BLUE, GREEN};
+ *     @Exhaustive Color value();
+ *     }
+ *  </code>
+ */
+
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Exhaustive {
+
+}

resources/javax/annotation/meta/TypeQualifier.java

@@ -0,0 +1,27 @@
+package javax.annotation.meta;
+
+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 qualifier is applied to an annotation to denote that the annotation
+ * should be treated as a type qualifier.
+ */
+
+@Documented
+@Target(ElementType.ANNOTATION_TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface TypeQualifier {
+
+    /**
+     * Describes the kinds of values the qualifier can be applied to. If a
+     * numeric class is provided (e.g., Number.class or Integer.class) then the
+     * annotation can also be applied to the corresponding primitive numeric
+     * types.
+     */
+    Class<?> applicableTo() default Object.class;
+
+}

resources/javax/annotation/meta/TypeQualifierDefault.java

@@ -0,0 +1,20 @@
+package javax.annotation.meta;
+
+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 qualifier is applied to an annotation to denote that the annotation
+ * defines a default type qualifier that is visible within the scope of the
+ * element it is applied to.
+ */
+
+@Documented
+@Target(ElementType.ANNOTATION_TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface TypeQualifierDefault {
+    ElementType[] value() default {};
+}

resources/javax/annotation/meta/TypeQualifierNickname.java

@@ -0,0 +1,33 @@
+package javax.annotation.meta;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+/**
+ * 
+ * This annotation is applied to a annotation, and marks the annotation as being
+ * a qualifier nickname. Applying a nickname annotation X to a element Y should
+ * be interpreted as having the same meaning as applying all of annotations of X
+ * (other than QualifierNickname) to Y.
+ * 
+ * <p>
+ * Thus, you might define a qualifier SocialSecurityNumber as follows:
+ * </p>
+ * 
+ * 
+ * <code>
+ @Documented
+ @TypeQualifierNickname @Pattern("[0-9]{3}-[0-9]{2}-[0-9]{4}") 
+ @Retention(RetentionPolicy.RUNTIME)
+ public @interface SocialSecurityNumber {
+ }
+ </code>
+ * 
+ * 
+ */
+@Documented
+@Target(ElementType.ANNOTATION_TYPE)
+public @interface TypeQualifierNickname {
+
+}

resources/javax/annotation/meta/TypeQualifierValidator.java

@@ -0,0 +1,21 @@
+package javax.annotation.meta;
+
+import java.lang.annotation.Annotation;
+
+import javax.annotation.Nonnull;
+
+public interface TypeQualifierValidator<A extends Annotation> {
+    /**
+     * Given a type qualifier, check to see if a known specific constant value
+     * is an instance of the set of values denoted by the qualifier.
+     * 
+     * @param annotation
+     *                the type qualifier
+     * @param value
+     *                the value to check
+     * @return a value indicating whether or not the value is an member of the
+     *         values denoted by the type qualifier
+     */
+    public @Nonnull
+    When forConstantValue(@Nonnull A annotation, Object value);
+}

resources/javax/annotation/meta/When.java

@@ -0,0 +1,23 @@
+package javax.annotation.meta;
+
+/**
+ * Used to describe the relationship between a qualifier T and the set of values
+ * S possible on an annotated element.
+ * 
+ * In particular, an issues should be reported if an ALWAYS or MAYBE value is
+ * used where a NEVER value is required, or if a NEVER or MAYBE value is used
+ * where an ALWAYS value is required.
+ * 
+ * 
+ */
+public enum When {
+    /** S is a subset of T */
+    ALWAYS,
+    /** nothing definitive is known about the relation between S and T */
+    UNKNOWN,
+    /** S intersection T is non empty and S - T is nonempty */
+    MAYBE,
+    /** S intersection T is empty */
+    NEVER;
+
+}