io.jstach.rainbowgum.annotation.LogConfigurable Maven / Gradle / Ivy
package io.jstach.rainbowgum.annotation;
import static java.lang.annotation.RetentionPolicy.CLASS;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
// @formatter:off
/**
* Used to generate Rainbow Gum config builder objects that once built will call the
* method annotated with the properties from the generated builder on build. The method
* annotated is essentially a factory method that a builder will be generated to configure
* each parameter in the factory method. The build call on the builder will call the
* annotated factory method.
*
* While there exist many annotation processors that generate builders (Immutables for
* example) the builders generated by this annotation (and corresponding processor) are
* LogProperties aware such that the builder can extract its arguments from LogProperties.
*
* Here is an example:
* {@snippet :
class final SomeFactory {
@LogConfigurable(name="MyPluginBuilder", prefix="logging.myplugin.{name}.")
static MyPlugin of(@KeyParameter String name, Integer myParameter) {
// do some additional logic.
return new MyPlugin(name, myParameter);
}
}
* }
* The above will create a builder called MyPluginBuilder with a setter of
* myParameter and its constructor will take a String name argument.
* {@snippet :
* MyPlugin plugin = new MyPluginBuilder("example").myParameter(80).fromProperties(properties).build();
* }
* The builder will try the property logging.myplugin.example.myParameter and
* use it if it exists to override the 80 value.
*/
// @formatter:on
@Retention(CLASS)
@Target({ ElementType.CONSTRUCTOR, ElementType.METHOD })
@Documented
public @interface LogConfigurable {
/**
* Name of builder.
* @return name of builder by default if not set Builder will be suffixed to
* targetType.
*/
String name() default "";
/**
* Property prefix to use for property lookup. Usually these come from LogProperties
* string constants and have a parameter of "name". If the prefix has parameters they
* can be specified with {@link KeyParameter} as arguments on the static factory
* method.
*
* An example might be: "logging.component.{name}." which has a parameter of "name".
* @return prefix in general should end in ".".
* @see KeyParameter
*/
String prefix();
/**
* Use as parameter to property keys with parameters. This annotation should only be
* used on String arguments and the builder will require it as an initial constructor
* argument to avoid it being missing.
*/
@Retention(CLASS)
@Target({ ElementType.PARAMETER })
@Documented
public @interface KeyParameter {
/**
* Use as parameter to a property name specified in
* {@link LogConfigurable#prefix()}. An example is a parameter called
* name with a prefix like logging.myplugin.{name}.
* @return by default will use the parameter name.
*/
String value() default "";
}
/**
* Use to set static defaults to parameters.
*/
@Retention(CLASS)
@Target({ ElementType.PARAMETER })
@Documented
public @interface DefaultParameter {
/**
* Will use use a static field on the factory class (the class that contains the
* annotated {@link LogConfigurable} method) as a default value if missing from
* properties or not set.
* @return by default will use the static field
* DEFAULT_parameterName.
*/
String value() default "";
}
/**
* Wall call a static method on the factory class (the class that contains the
* annotated {@link LogConfigurable} method) with the property value as a string to be
* converted.
*/
@Retention(CLASS)
@Target({ ElementType.PARAMETER })
@Documented
public @interface ConvertParameter {
/**
* Static method on target type to call to convert the parameter. The method must
* be return a type and have a single argument.
* @return static method name.
*/
String value();
}
/**
* A parameter not to be configured with properties that will just pass through to the
* build method.
*/
@Retention(CLASS)
@Target({ ElementType.PARAMETER })
@Documented
public @interface PassThroughParameter {
}
}