diff --git a/README.md b/README.md index cc07ea03..af5f904a 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,7 @@ compile time and runtime model by shading common pitfalls behind it's api. # Features - provides a processor for generating wrapper classes for accessing annotation attributes +- provides wrappers for _Elements_ and _TypeMirror_ that provide a lot of useful utility functions - provides support for Class conversion from runtime to compile time model (Class / FQN to Element and TypeMirror) - provides support for accessing the compile time element tree - provides generic Element based filters, validator and matchers @@ -49,9 +50,16 @@ This project provides the abstract base class _io.toolisticon.annotationprocesso which extends the AbstractProcessor class provided by java. Your annotation processor needs to extends this class to be able to use the utilities offered by this project and to build your annotation processor. -Since your annotation processor later mostly will be bound as a provided dependency you should use the maven shade -plugin to embed the annotation-processor-toolkit and all other 3rd party dependency classes into your annotation -processor artifact. This can be done by adding the following to your annotation processors pom.xml: +## Manually init ToolingProvider if you don't use the AbstractAnnotationProcessor +Nevertheless, you can even use this library if your processor doesn't extend the _io.toolisticon.annotationprocessortoolkit.AbstractAnnotationProcessor_. You need to initialize the _ToolingProvider_ manually in your processor - best place to do this is either in your processors _init_ or _process_ method: + +```java +ToolingProvider.setTooling(processingEnv); +``` + +## Delivering your processor +In general, you should consider to have as few external dependencies as possible used by your processor. +It's a good approach to use the maven shade plugin to repackage and embed the annotation-processor-toolkit and all other 3rd party dependencies into your annotation processor artifact. This can be done by adding the following to your annotation processors pom.xml: ```xml @@ -60,14 +68,14 @@ processor artifact. This can be done by adding the following to your annotation io.toolisticon.aptk aptk-tools - 0.18.0 + 0.22.5 io.toolisticon.cute cute - 0.11.1 + 0.12.1 test @@ -116,10 +124,10 @@ Please check our example provided in the github. ## Annotation Wrapper Reading attribute values can be very complicated if it comes to annotation type or Class based attributes. In this case -you are often forced to read the attribute values via the AnnotationMirror api. Additionally, you usually have to create +you are often forced to read the attribute values via the _AnnotationMirror_ api. Additionally, you usually have to create some kind of class to store those annotation configurations of the annotation. -The APTK provides an annotation processor that generates wrapper classes that allow you to access like if you are +The APTK provides an annotation processor that generates wrapper classes that allow you to access the annotation attribiute like if you are accessing the annotation directly. Only difference is that Class type based attributes will be accessible as FQN String, TypeMirror or TypeMirrorWrapper. Annotation type based attributes will be also wrapped to ease access. @@ -195,6 +203,14 @@ Optional method = TypeElementWrapper.wrap(typeElement) ``` +## TypeMirror wrapper +There is a wrapper for TypeMirrors as well. It's called _TypeMirrorWrapper_ and provides a lot of usefull tools like checking Assignability. +Usage is similar to the Element wrapper: + +```java +TypeMirrorWrapper.wrap(typeMirror); +``` + ## Enhanced utility support @@ -210,6 +226,7 @@ There are some more helpful utility classes: - _AnnotationUtils_ : provides support for reading annotation attribute values - _AnnotationValueUtils_ : provides support for handling _AnnotationValue_; +- _InterfaceUtils_ : provides support for handling generic interfaces and superclasses, for example to determine concrete types of type variables in super classes or parent interfaces (still experimental) Example: @@ -231,14 +248,14 @@ List enclosedElements=ElementUtils.AccessEnclosedElements.getE These are just a few examples of the provided tools. Please check the javadoc for more information. -## Characteristic matching, validation and filtering of Elements with core mathcers and fluent API +## Characteristic matching, validation and filtering of Elements with core matchers and fluent API The framework provides a set of core matchers that can be used to check if an Element matches a specific characteristic. Those core matchers can also be used for validation - validators allow you to check if an element matches none, one, at least one or all of the passed characteristics. -Additionally, the Core matchers can be used to filter a List of Elements by specific characteristics. +Additionally, the core matchers can be used to filter a List of Elements by specific characteristics. The framework provides a _FluentElementValidator_ and a _FluentElementFilter_ class that allow you to combine multiple filters and validations by providing a simple and powerful fluent api. @@ -332,16 +349,18 @@ The FilerUtils utility class also provides a way to write Strings to Source and builder classes for bean classes - [SPIAP](https://github.com/toolisticon/SPI-Annotation-Processor) : An annotation processor that helps you to generate SPI configuration files and service locator classes +- [FluApiGen](https://github.com/toolisticon/FluApiGen) : An annotation processor that generates fluent api implementation based on annotated interfaces +- APTK itself provides some annotation processors based on the APTK for generating wrappers for annotations or compiler messages # Useful links ## Compile time testing of annotation processors - [Toolisticon CUTE](https://github.com/toolisticon/cute) : A simple compile testing framework that allows you to test - annotation processors. It was extracted from this project is a great help to unit test your annotation processor code. + annotation processors. It was extracted from this project is a great help to unit test your annotation processor code. It supports both unit and black box testing of the processors code. - [google compile-testing](https://github.com/google/compile-testing) : Another compile testing framework which was used in the past by this framework. It has some flaws like missing compatibility with different Java versions, is binding a - lot of common 3rd party libraries, and has almost no documentation + lot of common 3rd party libraries, and has almost no documentation. # Contributing diff --git a/annotationwrapper/api/pom.xml b/annotationwrapper/api/pom.xml index 9d110635..14d0c9da 100644 --- a/annotationwrapper/api/pom.xml +++ b/annotationwrapper/api/pom.xml @@ -8,7 +8,7 @@ io.toolisticon.aptk aptk-annotationwrapper-parent - 0.22.5 + 0.22.6 aptk-annotationwrapper-api diff --git a/annotationwrapper/integrationtest/pom.xml b/annotationwrapper/integrationtest/pom.xml index 79e95738..e6f8189e 100644 --- a/annotationwrapper/integrationtest/pom.xml +++ b/annotationwrapper/integrationtest/pom.xml @@ -9,7 +9,7 @@ io.toolisticon.aptk aptk-annotationwrapper-parent - 0.22.5 + 0.22.6 aptk-annotationwrapper-integrationTest diff --git a/annotationwrapper/pom.xml b/annotationwrapper/pom.xml index af5aac5c..6c68eef5 100644 --- a/annotationwrapper/pom.xml +++ b/annotationwrapper/pom.xml @@ -11,7 +11,7 @@ io.toolisticon.aptk aptk-parent - 0.22.5 + 0.22.6 diff --git a/annotationwrapper/processor/pom.xml b/annotationwrapper/processor/pom.xml index 60184c31..4d39bfb5 100644 --- a/annotationwrapper/processor/pom.xml +++ b/annotationwrapper/processor/pom.xml @@ -9,7 +9,7 @@ io.toolisticon.aptk aptk-annotationwrapper-parent - 0.22.5 + 0.22.6 aptk-annotationwrapper-processor diff --git a/common/pom.xml b/common/pom.xml index 9f397ec2..1128dfc0 100644 --- a/common/pom.xml +++ b/common/pom.xml @@ -7,7 +7,7 @@ io.toolisticon.aptk aptk-parent - 0.22.5 + 0.22.6 aptk-common diff --git a/compilermessages/api/pom.xml b/compilermessages/api/pom.xml index 00d7bcf7..994ef7f8 100644 --- a/compilermessages/api/pom.xml +++ b/compilermessages/api/pom.xml @@ -8,7 +8,7 @@ io.toolisticon.aptk aptk-compilermessages-parent - 0.22.5 + 0.22.6 aptk-compilermessages-api diff --git a/compilermessages/integrationtest/pom.xml b/compilermessages/integrationtest/pom.xml index 82be81f5..4aadca7d 100644 --- a/compilermessages/integrationtest/pom.xml +++ b/compilermessages/integrationtest/pom.xml @@ -9,7 +9,7 @@ io.toolisticon.aptk aptk-compilermessages-parent - 0.22.5 + 0.22.6 aptk-compilermessages-integrationTest diff --git a/compilermessages/pom.xml b/compilermessages/pom.xml index 9ed68835..057357e1 100644 --- a/compilermessages/pom.xml +++ b/compilermessages/pom.xml @@ -11,7 +11,7 @@ io.toolisticon.aptk aptk-parent - 0.22.5 + 0.22.6 diff --git a/compilermessages/processor/pom.xml b/compilermessages/processor/pom.xml index e5337c25..27cdb9db 100644 --- a/compilermessages/processor/pom.xml +++ b/compilermessages/processor/pom.xml @@ -9,7 +9,7 @@ io.toolisticon.aptk aptk-compilermessages-parent - 0.22.5 + 0.22.6 aptk-compilermessages-processor diff --git a/cute/pom.xml b/cute/pom.xml index 2bb8f61d..5ecd3df8 100644 --- a/cute/pom.xml +++ b/cute/pom.xml @@ -8,7 +8,7 @@ io.toolisticon.aptk aptk-parent - 0.22.5 + 0.22.6 aptk-cute diff --git a/example/example-annotationprocessor/pom.xml b/example/example-annotationprocessor/pom.xml index 87d81c20..6ce5e2c4 100644 --- a/example/example-annotationprocessor/pom.xml +++ b/example/example-annotationprocessor/pom.xml @@ -8,7 +8,7 @@ io.toolisticon.aptk aptk-example-parent - 0.22.5 + 0.22.6 aptk-example-annotationprocessor diff --git a/example/example-annotations/pom.xml b/example/example-annotations/pom.xml index 20512d0e..302537cb 100644 --- a/example/example-annotations/pom.xml +++ b/example/example-annotations/pom.xml @@ -7,7 +7,7 @@ io.toolisticon.aptk aptk-example-parent - 0.22.5 + 0.22.6 aptk-example-annotations diff --git a/example/example-usecase/pom.xml b/example/example-usecase/pom.xml index 68b89575..9ea1ca28 100644 --- a/example/example-usecase/pom.xml +++ b/example/example-usecase/pom.xml @@ -7,7 +7,7 @@ io.toolisticon.aptk aptk-example-parent - 0.22.5 + 0.22.6 aptk-example-usecase diff --git a/example/pom.xml b/example/pom.xml index 906174a8..0a3864fa 100644 --- a/example/pom.xml +++ b/example/pom.xml @@ -7,7 +7,7 @@ io.toolisticon.aptk aptk-parent - 0.22.5 + 0.22.6 aptk-example-parent diff --git a/extensions/java9/pom.xml b/extensions/java9/pom.xml index 1755020c..4c81f7d6 100644 --- a/extensions/java9/pom.xml +++ b/extensions/java9/pom.xml @@ -8,7 +8,7 @@ io.toolisticon.aptk extension-parent - 0.22.5 + 0.22.6 aptk-tools-java9 diff --git a/extensions/pom.xml b/extensions/pom.xml index de931983..92771e1c 100644 --- a/extensions/pom.xml +++ b/extensions/pom.xml @@ -7,7 +7,7 @@ io.toolisticon.aptk aptk-parent - 0.22.5 + 0.22.6 extension-parent diff --git a/pom.xml b/pom.xml index 640c9232..99ac4e3c 100644 --- a/pom.xml +++ b/pom.xml @@ -4,7 +4,7 @@ io.toolisticon.aptk aptk-parent - 0.22.5 + 0.22.6 pom aptk-parent diff --git a/templating/pom.xml b/templating/pom.xml index 3efaaaef..31b31cb9 100644 --- a/templating/pom.xml +++ b/templating/pom.xml @@ -7,7 +7,7 @@ io.toolisticon.aptk aptk-parent - 0.22.5 + 0.22.6 aptk-templating diff --git a/tools/pom.xml b/tools/pom.xml index 43748e85..247332dd 100644 --- a/tools/pom.xml +++ b/tools/pom.xml @@ -8,7 +8,7 @@ io.toolisticon.aptk aptk-parent - 0.22.5 + 0.22.6 aptk-tools diff --git a/tools/src/main/java/io/toolisticon/aptk/tools/TypeMirrorWrapper.java b/tools/src/main/java/io/toolisticon/aptk/tools/TypeMirrorWrapper.java index 6c7035db..77572d68 100644 --- a/tools/src/main/java/io/toolisticon/aptk/tools/TypeMirrorWrapper.java +++ b/tools/src/main/java/io/toolisticon/aptk/tools/TypeMirrorWrapper.java @@ -898,6 +898,16 @@ public static Optional getTypeElement(TypeMirror typeMirror) return Optional.empty(); } + /** + * Gets the TypeElements wrapped TypeMirror. + * + * @param typeElement the TypeElement to get the TypeMirror for + * @return The wrapped TypeMirror of the TypeElement + */ + public static TypeMirrorWrapper wrap(TypeElement typeElement) { + return TypeElementWrapper.wrap(typeElement).asType(); + } + /** * Wraps a TypeMirror instance to provide some convenience methods * diff --git a/tools/src/main/java/io/toolisticon/aptk/tools/wrapper/AnnotationMirrorWrapper.java b/tools/src/main/java/io/toolisticon/aptk/tools/wrapper/AnnotationMirrorWrapper.java index 678fc6f7..7d99978a 100644 --- a/tools/src/main/java/io/toolisticon/aptk/tools/wrapper/AnnotationMirrorWrapper.java +++ b/tools/src/main/java/io/toolisticon/aptk/tools/wrapper/AnnotationMirrorWrapper.java @@ -7,6 +7,7 @@ import javax.lang.model.element.AnnotationValue; import javax.lang.model.element.Element; import javax.lang.model.element.ElementKind; +import javax.lang.model.type.DeclaredType; import java.lang.annotation.Annotation; import java.util.Arrays; import java.util.Optional; @@ -38,6 +39,24 @@ public AnnotationMirror unwrap() { return annotationMirror; } + /** + * Get DeclaredType of wrapped annotation. + * @return the annotations declared type + */ + DeclaredType getAnnotationType() { + return this.annotationMirror.getAnnotationType(); + } + + /** + * Get wrapped DeclaredType of wrapped annotation. + * @return the annotations declared type + */ + TypeMirrorWrapper getWrappedAnnotationType() { + return TypeMirrorWrapper.wrap(getAnnotationType()); + } + + + /** * Returns the "value" attribute * diff --git a/tools/src/main/java/io/toolisticon/aptk/tools/wrapper/ElementWrapper.java b/tools/src/main/java/io/toolisticon/aptk/tools/wrapper/ElementWrapper.java index 884ea4f2..b51450dd 100644 --- a/tools/src/main/java/io/toolisticon/aptk/tools/wrapper/ElementWrapper.java +++ b/tools/src/main/java/io/toolisticon/aptk/tools/wrapper/ElementWrapper.java @@ -173,6 +173,14 @@ public FluentElementFilter filterFlattenedEnclosedElementTree(boolean i return FluentElementFilter.createFluentElementFilter(getFlattenedEnclosedElementTree(includeSelf, maxDepth).stream().map(ElementWrapper::unwrap).collect(Collectors.toList())); } + /** + * Gets all wrapped annotations of element. + * @return a list containing all annotations of the element + */ + public List getAnnotations() { + return this.element.getAnnotationMirrors().stream().map(AnnotationMirrorWrapper::wrap).collect(Collectors.toList()); + } + /** * Gets the annotation * diff --git a/tools/src/test/java/io/toolisticon/aptk/tools/wrapper/ElementWrapperTest.java b/tools/src/test/java/io/toolisticon/aptk/tools/wrapper/ElementWrapperTest.java index 3bcc09c7..5e8b80dc 100644 --- a/tools/src/test/java/io/toolisticon/aptk/tools/wrapper/ElementWrapperTest.java +++ b/tools/src/test/java/io/toolisticon/aptk/tools/wrapper/ElementWrapperTest.java @@ -185,7 +185,15 @@ public void test_validate() { } + @Test + public void test_getAnnotations() { + + CompileTestBuilder.unitTest().defineTestWithPassedInElement(TestClass.class, (processingEnvironment, element) -> { + ElementWrapper unit = ElementWrapper.wrap(element); + MatcherAssert.assertThat("Should find annotation", unit.getAnnotations(),Matchers.hasSize(1)); + }).executeTest(); + } @Test public void test_getAnnotation_byFqnString() {