Jackfruit processes annotations on Java interfaces and abstract classes to generate code that can read and write Apache Configuration files. In the top level directory, run mvn clean package, which will build the annotation library in the jackfruit module and run the annotation processor in the demo module. The file demo/src/main/java/jackfruit/demo/JackfruitDemo.java shows some simple examples of use.
Include Jackfruit in your project with the following POM:
<dependency>
<groupId>edu.jhuapl.ses</groupId>
<artifactId>jackfruit</artifactId>
<version>$VERSION</version>
<type>pom</type>
</dependency>
Find the latest version at Maven Central.
The annotation processor runs on any interface or abstract class annotated with @Jackfruit
@Jackfruit(prefix = "prefix")
public interface DemoInterface {
// default key is field name
@Key("key")
@Comment("One line comment")
@DefaultValue("1")
int intMethod();
@Comment("This is a very long comment line that really should be wrapped into more than one line but that's really up to you.")
@DefaultValue("0.")
Double doubleMethod();
@Comment("""
This is a multiline
java text block.
This is a new paragraph.
""")
@DefaultValue("Default String")
String StringMethod();
@Comment("This string is serialized into an object\n\tThis comment contains a newline character, and this line starts with a tab.")
@DefaultValue("serialized string")
@ParserClass(SomeRandomClassParser.class)
SomeRandomClass randomClass();
@Comment("List of Doubles")
@DefaultValue("0. 5.34 17")
List<Double> doubles();
@Comment("List of RandomClass")
@DefaultValue("""
obj1
obj2
obj3 obj4
""")
@ParserClass(SomeRandomClassParser.class)
List<SomeRandomClass> randoms();
}
This corresponds to the following Apache Configuration file:
# One line comment
prefix.key = 1
# This is a very long comment line that really should be wrapped into more than one line but that's really up to you.
prefix.doubleMethod = 0.0
# This is a multiline
# java text block.
# This is a new paragraph.
prefix.StringMethod = Default String
# This string is serialized into an object
# This comment contains a newline character, and this line starts with a tab.
prefix.randomClass = serialized string
# List of Doubles
prefix.doubles = 0.0
prefix.doubles = 5.34
prefix.doubles = 17.0
# List of RandomClass
prefix.randoms = obj1
prefix.randoms = obj2
prefix.randoms = obj3
prefix.randoms = obj4
The annotation processor generates a class called DemoInterfaceFactory. An example of use is
// this factory is built by the annotation processor after reading the DemoConfig interface
DemoInterfaceFactory factory = new DemoInterfaceFactory();
// get an example config object
DemoInterface template = factory.getTemplate();
// generate an Apache PropertiesConfiguration object. This can be written out to a file
PropertiesConfiguration config = factory.toConfig(template);
try {
// this is the template, with comments
config.write(new PrintWriter(System.out));
// write to file
File tmpFile = File.createTempFile("tmp", ".config");
tmpFile.deleteOnExit();
// System.out.println("wrote "+tmpFile.getAbsolutePath());
config.write(new PrintWriter(tmpFile));
// read from file
config = new Configurations().properties(tmpFile);
// print to screen
config.write(new PrintWriter(System.out));
} catch (ConfigurationException | IOException e) {
e.printStackTrace();
}
// create a config object from an Apache PropertiesConfiguration
template = factory.fromConfig(config);
// get one of the config object's properties
System.out.println("\n*** Retrieving a configuration value");
List<SomeRandomClass> randoms = template.randoms();
for (SomeRandomClass random : randoms)
System.out.println("random.toUpperCase() = " + random.toUpperCase());
Jackfruit annotations can be inherited by derived classes. The @Jackfruit annotation must be present on the parent class as well as the inherited class. The annotation processor will build factory classes for both parent and child classes.
The @Jackfruit annotation goes on the abstract type. The remaining annotations are for use on methods. Jackfruit will only process methods annotated either with @DefaultValue or @Include.
This annotation goes on the abstract type to signify that it should be run through the annotation processor. There is an optional "prefix" argument that can be used to add a prefix to all of the configuration keys created by the processor. The Jackfruit annotation is not inherited by derived classes.
Every Factory class has a default constructor with this prefix (or an empty string if no prefix is specified) and a constructor where a prefix may be supplied. This is useful in case the user wants to create many configurations with the same parameters but different prefixes.
To use the same set of parameters with a different prefix:
DemoInterfaceFactory factory = new DemoInterfaceFactory("anotherPrefix");
The @Comment annotation specifies the comment that appears in the configuration file above the parameter itself. This can be a multiline text block and include newlines and tabs.
The @DefaultValue annotation is a String used to initialize the parameter. Strings and primitives (and their corresponding wrapper types) are read natively. Other objects will need to use the @ParserClass annotation to specify a class which implements the jackfruit.annotations.Parser interface to convert the object to and from a String. This annotation must be present if @Include is not used.
The @Include annotation allows the user to include another configuration class within this one. For example, if ThisBlock.java contains
@Jackfruit(prefix = "thisBlock")
public interface ThisBlock {
@Comment("thisBlock")
@DefaultValue("1")
int intMethod();
@Include
OtherBlock otherBlock();
}
and OtherBlock.java contains
@Jackfruit(prefix = "otherBlock")
public interface OtherBlock {
@Comment("OtherBlock")
@DefaultValue("2")
int intMethod();
}
running new ThisBlockFactory().getTemplate() will create
# thisBlock
thisBlock.intMethod = 1
# OtherBlock
otherBlock.intMethod = 2
If @Include is present, no other annotations will be honored.
The @Key annotation can be used to specify the name for the configuration key. The default is to use the name of the method.
The @ParserClass annotation specifies a class which implements the jackfruit.annotations.Parser interface to convert an object to and from a String. The Parser interface implements two methods:
public interface Parser<T> {
public T fromString(String s);
public String toString(T t);
}
If you'd like to create a configuration object that differs from the template populated with default values or one you've loaded from a file, the factory has "with" methods that will return a new PropertiesConfiguration object with a value replaced. For example:
DemoInterfaceFactory factory = new DemoInterfaceFactory();
DemoInterface template = factory.getTemplate();
PropertiesConfiguration config = factory.toConfig(template);
// add 999 to the default double values
List<Double> doubles = template.doubles();
doubles.add(999.);
config = factory.withDoubles(config, doubles);
config = factory.withIntMethod(config, 4);
This replaces the "doubles" and the "key" properties. The "with" methods are just wrappers around the "setProperty" method of the PropertiesConfiguration class. You can now use fromConfig() to create a new DemoInterface object with the updated values.