com.fortyoneconcepts.valjogen.annotations

Annotation Type VALJOConfigure

@Retention(value=SOURCE)
 @Target(value={TYPE,PACKAGE})
public @interface VALJOConfigure

Specifies details about the code that should be generated. May be specified on a package (package-info.java) or on a interface alongside the VALJOGenerate annotation. If specified on both a package and an interface then the package specification is ignored. Has no effect unless affected interfaces also has a VALJOGenerate annotation. All options may be overruled by setting identically named qualified key/values in the annotation processor using the -Acom.fortyoneconcepts.valjogen.optionName=value option to javac. Indeed some details like logLevel are usally better specified as a runtime option instead of hardcoding in the source using this annotation.

Usage example (package-info.java):

 @VALJOConfigure(outputPackage="test.impl", baseClazzName="test.CommonBaseClass")
 package test;
 

The above code will instruct the VALJOGen annotation processor to have generated value object classes from interfaces in this package belong to the "test.impl" package and to inherit from a common base class with qualified name "test.CommonBaseClass". Note that generation requires a seperate VALJOGenerate annotation. This other annotation is also used to specify what name the generated class should have.

For advanced customization do refer to the customJavaTemplateFileName option. This is the ultimate swiss army knife that lets you change and extend everything you want. It is a bit more difficult to use then other features though so look at the other options first.

* All string properties expand system properties as macros when enclosed in $() as well as the following macros:

$(This) which resolves to the fully qualified name of the generated class. The macro can be especially useful when implementing the Comparable interface using the extraInterfaceNames option.

$(IThis) which resolves to the the fully qualified name of the interface that is used for generation.

$(ExecutionDate) which resolves to the the time the annotation processes ran.

$(N/A) which signifies the value is unspecified (internally represented as a 'null').

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
String[]	baseClazzConstructors Specifies the base class constructors to delegate to in generated constructors and factory methods.
String	baseClazzName Specifies the base class of the generated class.
String[]	clazzAnnotations Specifies annotation strings with arguments that should be added to the generated class.
String	clazzJavaDoc Javadoc text string (without leading/ending comment characters) that should be added to generated class.
String[]	clazzModifiers Explicitly defined modifiers such as PUBLIC, PROTECTED, PRIVATE, FINAL or ABSTRACT to set in generated class.
String	comment An optional user supplied comment.
String[]	comparableMembers For classes that implement the Comparable interface this is the ordered names of members to use in a compareTo implementation.
String	customJavaTemplateFileName This is the ultimate customization power feature as it allows all aspects of the generated class to be changed or extended.
DataConversion	dataConversion Specifies if generated object should be easily convertable to/from xml or json.
boolean	debugStringTemplates Experimental debugging feature that specifies if the annotation processor should open the STViz GUI Inspector for debugging the internal stringtemplates.
boolean	ensureNotNullEnabled Specifies assignments to local variables should guard against null.
boolean	equalsEnabled Specifies if equals method should be generated for the class.
String[]	extraInterfaceNames Specifies if additional interfaces should be implemented to the generated class.
boolean	finalMembersAndParametersEnabled Specifies if generated members and method parameters should be final if possible.
boolean	finalMethodsEnabled Specifies if generated methods (incl.
boolean	forceThisAsImmutableSetterReturnType Specifies if return type of immutable setters should be fixed to be the class itself (covariannce) instead of what interfaces declare.
String[]	getterPrefixes Specifies the prefixes of javaBean-style getter methods.
boolean	hashEnabled Specifies if hash method should be generated for the class.
String	headerFileName UTF-8 formatted file that contains a header that should be added at the top of the generated output.
boolean	ignoreMalformedProperties Specifies if errors should be issued for malformed getter and setter methods.
String[]	importClasses Fully qualified extra classes to import into the generated code (in addition to implemented interfaces and baseclass which is imported as needed).
boolean	insertInheritDocOnMethodsEnabled Specifies if inheritDoc javaDoc comments should be added to the generated class for methods.
int	lineWidth Linewidth for generated code.
String	localeTag Experimental IETF BCP 47 language tag string descripting internal locale to use for annotation processor.
String	logLevel Specifies the Level log level to use inside the annotation processor.
String[]	memberAnnotations Specifies individual annotations for member fields as key-value entries.
String[]	methodAnnotations Specifies individual annotations for individual methods as key-value entries.
Mutability	mutability Specifies if generated object should be immutable or mutable.
String	outputPackage Package name of generated class.
long	serialVersionUID Specifies the serialization ID to use for generated classes or ZERO if not set.
String[]	setterPrefixes Specifies the prefixes of javaBean-style getter methods.
boolean	staticFactoryMethodEnabled Specifie if a static factory method should be generated instead of having the constructor being public.
String	suggestedVariablesPrefix Specifies prefix to use by temporary variables in method in order to avoid clashing with members.
boolean	synchronizedAccessEnabled Specifies if generated properties/methods for mutable members should be synchronized.
boolean	toStringEnabled Specifies if a toString method should be generated the class.
boolean	warnAboutSynthesisedNames Specifies if the annotation processor should warn about parameter names that are synthesised because -parameter option is missing.

Element Detail

outputPackage

public abstract String outputPackage

Package name of generated class. May be overruled by a fully qualified name on VALJOGenerate or by equivalent annotation processor key. If not specified, the output package will be the same as the interface used to generate the class.

Returns:

Package name.

Default:

"$(N/A)"

clazzModifiers

public abstract String[] clazzModifiers

Explicitly defined modifiers such as PUBLIC, PROTECTED, PRIVATE, FINAL or ABSTRACT to set in generated class. If none are present they will be auto-generated with a preference for PUBLIC FINAL or PUBLIC ABSTRACT classes. May be overruled by equivalent annotation processor key.

Returns:

Modifiers to apply to the generated class.

Default:

{}

lineWidth

public abstract int lineWidth

Linewidth for generated code. 0 if unlimited. May be overruled by equivalent annotation processor key.

Returns:

line width to use when generating output.

Default:

-1

mutability

public abstract Mutability mutability

Specifies if generated object should be immutable or mutable. May be overruled by equivalent annotation processor key. Default value is undefined, which means that the annotation processor will guess what the desired mutability (look and see if there are mutable setters).

Returns:

The desired mutability of the generated object.

Default:

com.fortyoneconcepts.valjogen.annotations.types.Mutability.Undefined

dataConversion

public abstract DataConversion dataConversion

Specifies if generated object should be easily convertable to/from xml or json. May be overruled by equivalent annotation processor key.

Returns:

The desired conversion approach to use if any.

Default:

com.fortyoneconcepts.valjogen.annotations.types.DataConversion.NONE

finalMembersAndParametersEnabled

public abstract boolean finalMembersAndParametersEnabled

Specifies if generated members and method parameters should be final if possible. May be overruled by equivalent annotation processor key.

Returns:

True if generated members and method parameters are prefered to be final.

Default:

true

finalMethodsEnabled

public abstract boolean finalMethodsEnabled

Specifies if generated methods (incl. property methods) should be final. May be overruled by equivalent annotation processor key.

Returns:

True if generated methods are prefered to be final

Default:

false

ensureNotNullEnabled

public abstract boolean ensureNotNullEnabled

Specifies assignments to local variables should guard against null. May be overruled by equivalent annotation processor key.

Returns:

True if local variables should be guarded against null assignments

Default:

true

staticFactoryMethodEnabled

public abstract boolean staticFactoryMethodEnabled

Specifie if a static factory method should be generated instead of having the constructor being public. May be overruled by equivalent annotation processor key.

Returns:

True a static factory method should be generated.

Default:

true

synchronizedAccessEnabled

public abstract boolean synchronizedAccessEnabled

Specifies if generated properties/methods for mutable members should be synchronized. May be overruled by equivalent annotation processor key.

Returns:

True if generated properties/methods are prefered to be synchronized.

Default:

false

suggestedVariablesPrefix

public abstract String suggestedVariablesPrefix

Specifies prefix to use by temporary variables in method in order to avoid clashing with members. May be overruled by equivalent annotation processor key.

Returns:

Prefix to use by local variables.

Default:

"_"

serialVersionUID

public abstract long serialVersionUID

Specifies the serialization ID to use for generated classes or ZERO if not set. Any non-zero value will automatically be inserted into classes that directly or indirectly implement the Serializable interface. May be overruled by equivalent annotation processor key.

Returns:

The serialization ID to use or '0' if not set.

Default:

1L

equalsEnabled

public abstract boolean equalsEnabled

Specifies if equals method should be generated for the class. May be overruled by equivalent annotation processor key. Remember to supply a hash method when generating equals methods.

Returns:

True if a equals method should be generated for the class.

See Also:

hashEnabled()

Default:

true

hashEnabled

public abstract boolean hashEnabled

Specifies if hash method should be generated for the class. May be overruled by equivalent annotation processor key. The generated hash method will be consistent with equals if this method is generated as well.

Returns:

True if a hash method should be generated for the class.

See Also:

equalsEnabled()

Default:

true

comparableMembers

public abstract String[] comparableMembers

For classes that implement the Comparable interface this is the ordered names of members to use in a compareTo implementation. This may include accessible members of a base class. If left unspecified it defaults to all members of the generated class in declaration order. May be overruled by equivalent annotation processor key.

Returns:

Array of names of all members to use in compareTo method and in specified order.

Default:

{}

toStringEnabled

public abstract boolean toStringEnabled

Specifies if a toString method should be generated the class. May be overruled by equivalent annotation processor key.

Returns:

True if a toString method should be generated for the class.

Default:

true

insertInheritDocOnMethodsEnabled

public abstract boolean insertInheritDocOnMethodsEnabled

Specifies if inheritDoc javaDoc comments should be added to the generated class for methods. May be overruled by equivalent annotation processor key.

Returns:

True if sinple javaDoc with inheritDoc reference should be generated for methods on the generated class.

Default:

true

ignoreMalformedProperties

public abstract boolean ignoreMalformedProperties

Specifies if errors should be issued for malformed getter and setter methods. May be overruled by equivalent annotation processor key.

Returns:

True if malformed getter/setter methods should be ignored. False if they should give errors.

Default:

false

importClasses

public abstract String[] importClasses

Fully qualified extra classes to import into the generated code (in addition to implemented interfaces and baseclass which is imported as needed).

Returns:

Array of all qualified classes to import.

Default:

{"java.util.Arrays", "java.util.Objects", "javax.annotation.Generated"}

getterPrefixes

public abstract String[] getterPrefixes

Specifies the prefixes of javaBean-style getter methods. Governs which memebers are inserted into the target class and which property method are implemented. By default only standard javaBean prefixes are included but additional custom prefixes can be added. Prefixes may be overruled by equivalent annotation processor key.

Returns:

Array of prefixes for getter methods.

Default:

{"is", "get"}

setterPrefixes

public abstract String[] setterPrefixes

Specifies the prefixes of javaBean-style getter methods. Governs which memebers are inserted into the target class and which property method are implemented. By default only the standard javaBean prefix is included but additional custom prefixes can be added. For instance "withXXX" methods for immutable properties might be useful. Prefixes may be overruled by equivalent annotation processor key.

Returns:

Array of prefixes for setter methods.

Default:

"set"

forceThisAsImmutableSetterReturnType

public abstract boolean forceThisAsImmutableSetterReturnType

Specifies if return type of immutable setters should be fixed to be the class itself (covariannce) instead of what interfaces declare. May be overruled by equivalent annotation processor key.

Returns:

True if return types of immutable setters should always be the implementation class.

Default:

true

extraInterfaceNames

public abstract String[] extraInterfaceNames

Specifies if additional interfaces should be implemented to the generated class. May be overruled by equivalent annotation processor key. Hint: For generic interfaces using the macro "$(This)" for the generic qualifier is useful to refer to the name of the generated class. F.x. to implement Comparable write "java.lang.Comparable<(This)>".

Returns:

Array of all additional interfaces

Default:

{}

baseClazzName

public abstract String baseClazzName

Specifies the base class of the generated class. May be overruled by equivalent annotation processor key. Note: The base class must be serializable in itself for serialization of the generated class to work (serialization does not require a default constructor however).

Returns:

Name of the base class for the generated class.

Default:

"java.lang.Object"

baseClazzConstructors

public abstract String[] baseClazzConstructors

Specifies the base class constructors to delegate to in generated constructors and factory methods. Each generated constructor will include arguments for the corresponding base constructor followed by the arguments for the members in the class. By default ALL base constructors will be used. As factory methods (if enabled) follow constructors a corresponding set of factory methods will be generated as well. The specifiers are of form "(" <unqualifed parameter type name> { "," <unqualifed parameter type name> } ")". For example to specify a constructor taking an integer and a String as arguments write (int,String). Note that all type names are unqualified. In addition the wildcard '*' may be used to match a single type name and the wildcard '**' may used to match all set of typenames (i.e. each and every base constructor).

Returns:

List of base class constructors to use when generating constructors for the class.

Default:

"(**)"

clazzAnnotations

public abstract String[] clazzAnnotations

Specifies annotation strings with arguments that should be added to the generated class.

Returns:

annotation string to add to the generated class.

Default:

"@Generated(value = \"com.fortyoneconcepts.valjogen\", date=\"$(ExecutionDate)\", comments=\"Generated by ValjoGen code generator (ValjoGen.41concepts.com) from $(IThis)\")"

methodAnnotations

public abstract String[] methodAnnotations

Specifies individual annotations for individual methods as key-value entries. Each entry is of form <method name> "(" <unqualifed parameter type name> { "," <unqualifed parameter type name> } ")" "=" <annotation string>. For example to annotate a method "f" taking an integer and a String as arguments write f(int,String)=@MyAnnotation(...). Note that all type names are unqualified. To specify a constructor set <method_name> to an empty string. To specify a factory method set method name to "valueOf". In addition the wildcard '*' may be used to match a single type name and the wildcard '**' may used to match all combinations of type name arguments.

Returns:

annotation string to add to the specified method(s) of the generated class class formatted as key-value entries.

Default:

{}

memberAnnotations

public abstract String[] memberAnnotations

Specifies individual annotations for member fields as key-value entries. Each entry is of form <member name> "=" <annotation string>. For example to annotate a member named "x" write x=@MyAnnotation(...).

Returns:

annotation string to add to the specified member(s) of the generated class class formatted as key-value entries.

Default:

{}

clazzJavaDoc

public abstract String clazzJavaDoc

Javadoc text string (without leading/ending comment characters) that should be added to generated class.

Returns:

Javadoc text to add to the generated class.

Default:

"$(N/A)"

headerFileName

public abstract String headerFileName

UTF-8 formatted file that contains a header that should be added at the top of the generated output.

Returns:

Filename of text file containing header.

Default:

"$(N/A)"

customJavaTemplateFileName

public abstract String customJavaTemplateFileName

This is the ultimate customization power feature as it allows all aspects of the generated class to be changed or extended. To enable this feature supply the name of a UTF-8 formatted StringTemplate 4 (ST) group file that should be used. It can be bit more difficult to use compared to other features of this tool, so do look at the other options first.

See ST 4 documentation and the cheat sheet in particular for details about how to write templates. The custom group file that can be added using this option will inherit from the existing templates allowing you to add new templates or override the build-in templates.

Note that ST maintains strict Model-View separation so templates can not contain logic or compare values other then booleans. Note also that templates can call into model getters but with the get/is prefix omitted.

Refer to the existing source (*.stg files) for this processor for how to work with the models available from a template. For details about the model see refer to javadoc or source for the com.fortyoneconcepts.valjogen.model.* classes in the annotation processor tool.

Preferably consider overriding declared ST regions like for example <@preamble> to change output rather then overriding existing templates in your ST file. This should reduce maintaince problems for future updates. ST requires regions to be prefixed with the template method they are declared in, so to add code in beginning of the equals method, add a ST file with a template rule like this:

  @method_equals.preamble() ::= << // initial method code here. >>
 

When you need to generate code for new java methods implementations, first make sure the method signature is declared, then add a template named method_specifier with the template arguments clazz and method in your ST group file. The specifier is the java method name followed by underscore seperated, unqualified type arguments with a leading underscore before first argument (if present). For example to generate the method "void f()" create a template named method_f" and to generate the method "double f(String arg, int value)" create a template named method_f_String_int". The require custom method arguments are of type Clazz and Method in the com.fortyoneconcepts.valjogen.model package. Refer to the JavaDoc for these for details. Declared methods that the implementation can override include methods in the interfaces and base class and their ancestors. In addition, if the generated class is serializable the magic serialization methods readResolve, readObjectNoData, writeObject and writeReplace are also recognized as methods. In you instead need to implement non-declared methods, add nested types or do something special then do override one of the ST regions in the main class template like f.x. @class.before_class_methods, @class.after_class_methods, @class.before_instance_methods or @class.after_instance_methods. When you override regions you have complete freedom to add any kind of code but without help like method signatures etc. The example shown below shows how the main part of the equals method might be defined. Refer to the ST source file for the equals method for the complete and present source code. In any case it is a good idea to study the template sources and example templates for tips about how to write custom templates. Note how getters in the model is accessed (with getter prefixes stripped) to facilitate the generation of the method according of the actal class members, method arguments etc.

 method_equals(clazz, method) ::= <<
  <declare_method(clazz, method)>
  {
     <if(clazz.anyMembers)>
     <clazz.prototypicalName> <uniqueVariableName(clazz,"other")> = (<clazz.prototypicalName>) <first(method.parameters).name>;

     return (<clazz.members:{m | <(equalsTemplateNamesByTypeCategory.(m.type.typeCategory))(clazz, m.name, m.type)>}; wrap, anchor, separator=" && ">);
     <else>
     return true;
     <endif>
  }
 >>
 

This file name may be overruled by equivalent annotation processor key.

Returns:

Filename of string template group file.

Default:

"$(N/A)"

warnAboutSynthesisedNames

public abstract boolean warnAboutSynthesisedNames

Specifies if the annotation processor should warn about parameter names that are synthesised because -parameter option is missing.

Returns:

True if annotation processor should warn about missing -parameter option.

Default:

true

logLevel

public abstract String logLevel

Specifies the Level log level to use inside the annotation processor. Set this to INFO or FINE to inspect model instances, inspect output or to help track errors inside the processor. Set to WARNING otherwise. Note that normally java.util.logging.ConsoleHandler.level needs to be set as well for log levels below INFO to be shown.

Returns:

Log level

Default:

"WARNING"

debugStringTemplates

public abstract boolean debugStringTemplates

Experimental debugging feature that specifies if the annotation processor should open the STViz GUI Inspector for debugging the internal stringtemplates. You should not need to enable this unless you are adding/modifying code templates and run into problems. Be aware that code generation will pause while the generator is shown - you properly do not want to do that when using an IDE. May be overruled by equivalent annotation processor key.

Returns:

True if annotation processor should open StringTemplagte's STViz Gui explorer during code generation phase.

Default:

false

localeTag

public abstract String localeTag

Experimental IETF BCP 47 language tag string descripting internal locale to use for annotation processor. Has undefined behavior. May be overruled by equivalent annotation processor key.

Returns:

Internal language tag describing locale to use for annotation processor.

See Also:

Locale.forLanguageTag(java.lang.String)

Default:

"en-US"

comment

public abstract String comment

An optional user supplied comment. Not used for anything by default but could potentially be used in a custom template or by a build tool. It is up to you what to use this option for.

Returns:

An optional comment.

Default:

"$(N/A)"