Package org.tquadrat.foundation.config.ap

package org.tquadrat.foundation.config.ap

This is the Annotation Processor for the module org.tquadrat.foundation.config. That module provides a facility for the runtime configuration of a program. The core component is a class, the Configuration, that holds the configuration values. Basically, this class is a POJO (or, more precisely, a JavaBean) that this Annotation Processor generates during compilation from an annotated interface, the configuration bean specification. For the details, refer to the org.tquadrat.foundation.config module itself.

The Annotation Processor can be used with with plain javac as well as with Maven, Gradle or ant.

That javac can find the Annotation Processor requires to add the *.jar file with this code (it should be something like org.tquadrat.foundation.config.ap-<version>.jar) to the CLASSPATH; from there javac will detect it automatically. Alternatively, the class name for the Annotation Processor, ConfigAnnotationProcessor, can be provided explicitly with the processor option.

Finally, the destination for the generated sources has to be set with the -s option.

The documentation for javac says "[…]Unless annotation processing is disabled with the -proc:none option, the compiler searches for any annotation processors that are available. The search path can be specified with the -processorpath option. If no path is specified, then the user class path is used. Processors are located by means of service provider-configuration files named META-INF/services/javax.annotation.processing.Processor on the search path. Such files should contain the names of any annotation processors to be used, listed one per line. Alternatively, processors can be specified explicitly, using the -processor option. […]"

Tests so far are showing inconsistent results with the auto-detection mechanism, so the recommendation is to use the -processor option always instead of relying on the auto-detection mechanism.

To use the Annotation Processor with Maven, the following lines must be added to the pom.xml of the project to build:

…
  …
  <build>
      …
      <plugins>
          …
          <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-compiler-plugin</artifactId>
              …
              <configuration>
                  …
                  <annotationProcessorPaths>
                      <annotationProcessorPath>
                          <groupId>org.tquadrat.tool</groupId>
                          <artifactId>org.tquadrat.foundation.config.ap</artifactId>
                          <version>proper_version</version>
                      </annotationProcessorPath>
                      …
                  </annotationProcessorPaths>
                  …
              </configuration>
              …
              <executions>
                  …
                  <execution>
                      <id>default-compile</id>
                      <phase>compile</phase>
                      <goals>
                          <goal>compile</goal>
                      </goals>
                      <configuration>
                          …
                          <annotationProcessors>
                              <annotationProcessor>org.tquadrat.foundation.config.ap.ConfigAnnotationProcessor</annotationProcessor>
                              …
                          </annotationProcessors>
                          …
                          <compilerArgs>
                              …
                              <arg>-Aorg.tquadrat.foundation.ap.maven.goal=compile</arg>
                              …
                          </compilerArgs>
                          …
                      </configuration>
                      …
                  </execution>
                  …
              </executions>
              …
          </plugin>
          …
      </plugins>
      …
  </build>
TODO Add the configuration for Gradle and for ant.

Unless otherwise stated, null argument values will cause methods and constructors of all classes in this package to throw an Exception, usually a NullArgumentException, but in some rare cases, it could be also a NullPointerException.