Added additional constraints and tests

constraints/README.md

@@ -0,0 +1,63 @@
+# WARNING - THIS FEATURE IS STILL IN EXPERIMENTAL AND MIGHT BE REMOVED
+
+# Constraints on Annotations
+A lot of the commonly used tools in Java development are somehow based on annotations. 
+In most cases there are kind of constraints about how those annotations must be used.
+
+One example is the Target annotation provided by Java itself which is used to allow annotations to be placed on certain kind of Elements.
+But there are other kinds of possible constraints like that annotated types must implement a specific interface or that a String based annotation attribute must not be empty.
+Such kind of constraints often just mentioned in the Javadoc and errors might only be triggered at runtime - this is the case for most tools which doesn't have an annotation processor involved.
+
+If there is an annotation processor present,  it will be possible to check those constraints during the processing and trigger compiler messages in the compilation process.
+This can be warnings or even errors that make the compilation fail.
+
+This subproject of APTK tries to ease applying and documenting of annotation constraints by providing general purpose constraint annotations which can be placed on annotation types or attributes.
+
+Just think about the Java's _Target_ annotation again. It allows restraining the usage on types by declaring:
+
+```java
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface TestAnnotation {
+
+}
+```
+
+Unfortunately the _ElementType.TYPE_ is kind of ambiguous and represents classes, interfaces, enums and records. 
+This tool provides the _On_ constraint annotation which can be used to further restrict the usage of annotations.
+So if annotations must only be applicable on interfaces rather than on classes, enums and records.
+
+```java
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import io.toolisticon.aptk.constraints.WithTargetOfKind;
+import io.toolisticon.aptk.constraints.WithTargetOfKind.TargetKind;
+
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+@On(Location.INTERFACE)
+public @interface TestAnnotation {
+
+}
+```
+
+The library provides a standalone annotation processor that scans all annotations if they are annotated with any kind of constraint annotation. Additionally, it's possible to embed the validation into an existing processor.
+
+A constraint annotation is just an annotation that is annotated with the _Constraint_ meta annotation. It must be either be placeable on annotations or annotation attributes.
+It's also possible to use constraint annotations on other constraint annotations.
+
+The constraint implementation will be bound to the constraint annotation via the _AnnotationConstraintSpi_ SPI. By doing this it's relatively easy to provide custom constraints.
+
+In some cases it's useful to manually implement constraints for some annotations. This can be done by implementing the _ManualConstraintSpi_ SPI.
+
+If we take a look at the _On_ annotation we will see that it is implenting both SPIs. One for applying constraints on other annotations and the other to make sure that it itself is used correctly.
+

constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/TargetElement.java

@@ -0,0 +1,9 @@
+package io.toolisticon.aptk.constraints;
+
+public enum TargetElement {
+
+    ANNOTATED_ELEMENT,
+    PARENT_TYPE_ELEMENT,
+    TOP_LEVEL_TYPE_ELEMENT
+
+}

constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/OnAnnotationAttributeOfType.java → constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/WithAnnotationAttributeTargetOfType.java

@@ -8,7 +8,7 @@
 @Constraint
 @Target(ElementType.ANNOTATION_TYPE)
 @Retention(RetentionPolicy.RUNTIME)
-public @interface OnAnnotationAttributeOfType {
+public @interface WithAnnotationAttributeTargetOfType {
 
     enum AttributeType {
         FLOAT,

constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/WithDoubleInBounds.java

@@ -0,0 +1,25 @@
+package io.toolisticon.aptk.constraints;
+
+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;
+
+@Documented
+@Constraint
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+@WithTargetOfKind(WithTargetOfKind.TargetKind.ANNOTATION_ATTRIBUTE)
+@WithAnnotationAttributeTargetOfType({WithAnnotationAttributeTargetOfType.AttributeType.DOUBLE, WithAnnotationAttributeTargetOfType.AttributeType.DOUBLE_ARRAY})
+public @interface WithDoubleInBounds {
+
+    double lowerBound() default Double.MIN_VALUE;
+
+    boolean inclusiveLowerBound() default true;
+
+    double upperBound() default Double.MAX_VALUE;
+
+    boolean inclusiveUpperBound() default true;
+
+}

constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/WithFloatInBounds.java

@@ -0,0 +1,25 @@
+package io.toolisticon.aptk.constraints;
+
+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;
+
+@Documented
+@Constraint
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+@WithTargetOfKind(WithTargetOfKind.TargetKind.ANNOTATION_ATTRIBUTE)
+@WithAnnotationAttributeTargetOfType({WithAnnotationAttributeTargetOfType.AttributeType.FLOAT, WithAnnotationAttributeTargetOfType.AttributeType.FLOAT_ARRAY})
+public @interface WithFloatInBounds {
+
+    float lowerBound() default Float.MIN_VALUE;
+
+    boolean inclusiveLowerBound() default true;
+
+    float upperBound() default Float.MAX_VALUE;
+
+    boolean inclusiveUpperBound() default true;
+
+}

constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/WithIntegerInBounds.java

@@ -0,0 +1,25 @@
+package io.toolisticon.aptk.constraints;
+
+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;
+
+@Documented
+@Constraint
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+@WithTargetOfKind(WithTargetOfKind.TargetKind.ANNOTATION_ATTRIBUTE)
+@WithAnnotationAttributeTargetOfType({WithAnnotationAttributeTargetOfType.AttributeType.INTEGER, WithAnnotationAttributeTargetOfType.AttributeType.INTEGER_ARRAY})
+public @interface WithIntegerInBounds {
+
+    int lowerBound() default Integer.MIN_VALUE;
+
+    boolean inclusiveLowerBound() default true;
+
+    int upperBound() default Integer.MAX_VALUE;
+
+    boolean inclusiveUpperBound() default true;
+
+}

constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/WithLongInBounds.java

@@ -0,0 +1,25 @@
+package io.toolisticon.aptk.constraints;
+
+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;
+
+@Documented
+@Constraint
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+@WithTargetOfKind(WithTargetOfKind.TargetKind.ANNOTATION_ATTRIBUTE)
+@WithAnnotationAttributeTargetOfType({WithAnnotationAttributeTargetOfType.AttributeType.LONG, WithAnnotationAttributeTargetOfType.AttributeType.LONG_ARRAY})
+public @interface WithLongInBounds {
+
+    long lowerBound() default Long.MIN_VALUE;
+
+    boolean inclusiveLowerBound() default true;
+
+    long upperBound() default Long.MAX_VALUE;
+
+    boolean inclusiveUpperBound() default true;
+
+}

constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/NonEmptyArray.java → constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/WithNonEmptyArray.java

@@ -10,7 +10,7 @@
 @Constraint
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
-@On(On.Location.ANNOTATION_ATTRIBUTE)
-@OnAnnotationAttributeOfType({OnAnnotationAttributeOfType.AttributeType.ARRAY})
-public @interface NonEmptyArray {
+@WithTargetOfKind(WithTargetOfKind.TargetKind.ANNOTATION_ATTRIBUTE)
+@WithAnnotationAttributeTargetOfType({WithAnnotationAttributeTargetOfType.AttributeType.ARRAY})
+public @interface WithNonEmptyArray {
 }

constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/NonEmptyString.java → constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/WithNonEmptyString.java

@@ -10,7 +10,7 @@
 @Constraint
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
-@On(On.Location.ANNOTATION_ATTRIBUTE)
-@OnAnnotationAttributeOfType({OnAnnotationAttributeOfType.AttributeType.STRING, OnAnnotationAttributeOfType.AttributeType.STRING_ARRAY})
-public @interface NonEmptyString {
+@WithTargetOfKind(WithTargetOfKind.TargetKind.ANNOTATION_ATTRIBUTE)
+@WithAnnotationAttributeTargetOfType({WithAnnotationAttributeTargetOfType.AttributeType.STRING, WithAnnotationAttributeTargetOfType.AttributeType.STRING_ARRAY})
+public @interface WithNonEmptyString {
 }

constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/StringMustMatch.java → constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/WithStringMatching.java

@@ -11,9 +11,9 @@
 @Constraint
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
-@On(On.Location.ANNOTATION_ATTRIBUTE)
-@OnAnnotationAttributeOfType({OnAnnotationAttributeOfType.AttributeType.STRING, OnAnnotationAttributeOfType.AttributeType.STRING_ARRAY})
-public @interface StringMustMatch {
+@WithTargetOfKind(WithTargetOfKind.TargetKind.ANNOTATION_ATTRIBUTE)
+@WithAnnotationAttributeTargetOfType({WithAnnotationAttributeTargetOfType.AttributeType.STRING, WithAnnotationAttributeTargetOfType.AttributeType.STRING_ARRAY})
+public @interface WithStringMatching {
 
     String value();
 

constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/TargetMustBeAnnotatedWith.java → constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/WithTargetElementAnnotatedWith.java

@@ -13,19 +13,12 @@
 @Constraint
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.ANNOTATION_TYPE)
-@On(On.Location.ANNOTATION)
-@Repeatable(TargetMustBeAnnotatedWiths.class)
-public @interface TargetMustBeAnnotatedWith {
-
-    enum TargetElement {
-        ANNOTATED_ELEMENT,
-        PARENT_TYPE_ELEMENT,
-        TOP_LEVEL_TYPE_ELEMENT
-    }
-
+@WithTargetOfKind(WithTargetOfKind.TargetKind.ANNOTATION)
+@Repeatable(WithTargetElementAnnotatedWithRepeatable.class)
+public @interface WithTargetElementAnnotatedWith {
 
     Class<? extends Annotation> value();
 
-    TargetMustBeAnnotatedWith.TargetElement target() default TargetMustBeAnnotatedWith.TargetElement.ANNOTATED_ELEMENT;
+   TargetElement targetElement() default TargetElement.ANNOTATED_ELEMENT;
 
 }

constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/TargetMustBeAnnotatedWiths.java → constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/WithTargetElementAnnotatedWithRepeatable.java

@@ -11,7 +11,7 @@
 @Constraint
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.ANNOTATION_TYPE)
-@On(On.Location.ANNOTATION)
-public @interface TargetMustBeAnnotatedWiths {
-    TargetMustBeAnnotatedWith[] value();
+@WithTargetOfKind(WithTargetOfKind.TargetKind.ANNOTATION)
+public @interface WithTargetElementAnnotatedWithRepeatable {
+    WithTargetElementAnnotatedWith[] value();
 }

constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/TargetMustBeAssignableTo.java → constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/WithTargetElementAssignableTo.java

@@ -2,7 +2,6 @@
 
 import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
-import java.lang.annotation.Repeatable;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
@@ -11,15 +10,9 @@
 @Constraint
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
-@On(On.Location.ANNOTATION_ATTRIBUTE)
-@OnAnnotationAttributeOfType({OnAnnotationAttributeOfType.AttributeType.CLASS, OnAnnotationAttributeOfType.AttributeType.CLASS_ARRAY})
-public @interface TargetMustBeAssignableTo {
-
-    enum TargetElement {
-        ANNOTATED_ELEMENT,
-        PARENT_TYPE_ELEMENT,
-        TOP_LEVEL_TYPE_ELEMENT
-    }
+@WithTargetOfKind(WithTargetOfKind.TargetKind.ANNOTATION_ATTRIBUTE)
+@WithAnnotationAttributeTargetOfType({WithAnnotationAttributeTargetOfType.AttributeType.CLASS, WithAnnotationAttributeTargetOfType.AttributeType.CLASS_ARRAY})
+public @interface WithTargetElementAssignableTo {
 
     TargetElement targetElement() default TargetElement.ANNOTATED_ELEMENT;
 

constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/On.java → constraints/constraint-api/src/main/java/io/toolisticon/aptk/constraints/WithTargetOfKind.java

@@ -16,17 +16,18 @@
  */
 @Documented
 @Constraint
-@Target(ElementType.ANNOTATION_TYPE)
+@Target({ElementType.ANNOTATION_TYPE})
 @Retention(RetentionPolicy.RUNTIME)
-public @interface On {
+public @interface WithTargetOfKind {
 
-    enum Location {
+    enum TargetKind {
         PACKAGE,
         ANNOTATION_ATTRIBUTE,
         ANNOTATION,
         CLASS,
         INTERFACE,
         ENUM,
+        RECORD,
         METHOD,
         CONSTRUCTOR,
         PARAMETER,
@@ -36,6 +37,6 @@ enum Location {
 
     }
 
-    Location[] value();
+    TargetKind[] value();
 
 }

constraints/constraint-impl/src/main/java/io/toolisticon/aptk/constraints/OnAnnotationAttributeOfTypeConstraintImpl.java → constraints/constraint-impl/src/main/java/io/toolisticon/aptk/constraints/WithAnnotationAttributeTargetOfTypeConstraintImpl.java

@@ -13,11 +13,11 @@
 
 @SpiService(value = AnnotationConstraintSpi.class)
 @DeclareCompilerMessage(code = "ONATTRIBUTETYPE_001", enumValueName = "ONATTRIBUTETYPE_ERROR_WRONG_USAGE", message = "'${0}' Constraint violated: Annotation ${1} must be placed on annotation attribute of kind ${2}", processorClass = BasicConstraints.class)
-public class OnAnnotationAttributeOfTypeConstraintImpl implements AnnotationConstraintSpi {
+public class WithAnnotationAttributeTargetOfTypeConstraintImpl implements AnnotationConstraintSpi {
 
     @Override
     public Class<? extends Annotation> getSupportedAnnotation() {
-        return OnAnnotationAttributeOfType.class;
+        return WithAnnotationAttributeTargetOfType.class;
     }
 
 
@@ -37,11 +37,11 @@ public boolean checkConstraints(Element annotatedElement, AnnotationMirror annot
         ExecutableElementWrapper attributeElementWrapper = ExecutableElementWrapper.wrap((ExecutableElement) annotatedElement);
 
         // Now check if annotation
-        OnAnnotationAttributeOfTypeWrapper onAnnotationOfType = OnAnnotationAttributeOfTypeWrapper.wrap(constraintAnnotationMirror);
+        WithAnnotationAttributeTargetOfTypeWrapper onAnnotationOfType = WithAnnotationAttributeTargetOfTypeWrapper.wrap(constraintAnnotationMirror);
 
         boolean foundMatchingElementType = false;
         loop:
-        for (OnAnnotationAttributeOfType.AttributeType targetAttributeType : onAnnotationOfType.value()) {
+        for (WithAnnotationAttributeTargetOfType.AttributeType targetAttributeType : onAnnotationOfType.value()) {
 
             switch (targetAttributeType) {
                 case ARRAY: {