Update #0 - First Release

sources/main/java/javax/annotation/meta/Exclusive.java

@@ -0,0 +1,30 @@
+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.
+ * 
+ * <p>
+ * 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)}.
+ * 
+ * <pre>
+ * &#064;TypeQualifier
+ * &#064;interface Foo {
+ * 	&#064;Exclusive
+ * 	int value();
+ * }
+ * </pre>
+ * 
+ */
+
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Exclusive {
+
+}

sources/main/java/javax/annotation/meta/Exhaustive.java

@@ -0,0 +1,40 @@
+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.
+ * 
+ * <p>
+ * Applications of the type qualifier with different values are exclusive, and
+ * the enumeration is an exhaustive list of the possible values.
+ * 
+ * <p>
+ * 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)}
+ * 
+ * <pre>
+ * &#064;TypeQualifier
+ * &#064;interface Foo {
+ * 	enum Color {
+ * 		RED, BLUE, GREEN
+ * 	};
+ * 
+ * 	&#064;Exhaustive
+ * 	Color value();
+ * }
+ * </pre>
+ */
+
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Exhaustive {
+
+}

sources/main/java/javax/annotation/meta/TypeQualifier.java

@@ -0,0 +1,28 @@
+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.
+	 *
+	 * @return a class object which denotes the type of the values the original
+	 *         annotation can be applied to.
+	 */
+	Class<?> applicableTo() default Object.class;
+
+}

sources/main/java/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 {};
+}

sources/main/java/javax/annotation/meta/TypeQualifierNickname.java

@@ -0,0 +1,30 @@
+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>
+ * 
+ * <pre>
+ * &#064;Documented
+ * &#064;TypeQualifierNickname
+ * &#064;Pattern("[0-9]{3}-[0-9]{2}-[0-9]{4}")
+ * &#064;Retention(RetentionPolicy.RUNTIME)
+ * public &#064;interface SocialSecurityNumber {
+ * }
+ * </pre>
+ */
+@Documented
+@Target(ElementType.ANNOTATION_TYPE)
+public @interface TypeQualifierNickname {
+
+}

sources/main/java/javax/annotation/meta/TypeQualifierValidator.java

@@ -0,0 +1,18 @@
+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);
+}

sources/main/java/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;
+
+}