semver/README.md

Semantic Version Annotation Processor

An annotation processor that automatically generates a Version class containing the semantic version (major, minor, patch, etc.) that is read from a Properties file or defined in the annotation.

This processor was inspired by Cédric Beust's version-processor.

Examples

• Using annotation elements:

@Version(major = 1, minor = 0, patch = 0, prerelease = "beta")
public class A {
// ...

• Or using a properties file:

@Version(properties = "version.properties")
public class A {
// ...

# version.properties
version.major=1
version.minor=0
version.patch=0
version.prerelease=beta

Template

Upon running the annotator processor, a source file GeneratedVersion.java is automatically generated with static methods to access the semantic version data. The source is based on a fully customizable Velocity template.

@Version(template = "myversion.vm")
public class A {
// ...

Default Template

The default template implements the following static methods:

Method	Description	Example
getProject	The project name, if any.	MyProject
getBuildDate	The build date.	java.util.Date
getVersion	The full version string.	1.0.0-alpha+001
getMajor	The major version.	1
getMinor	The minor version.	0
getPatch	The patch version.	0
getPreRelease	The pre-release version, if any.	alpha
getBuildMetadata	The build metadata, if any.	001

Custom Template

A very simple custom template might look something like:

/* myversion.vm */
package ${packageName}

import java.util.Date;

public final class ${className} {
	public final static String BUILDMETA = "${buildmeta}";
	public final static Date DATE = new Date(${epoch}L);
	public final static int MAJOR = ${major};
	public final static int MINOR = ${minor};
	public final static int PATCH = ${patch};
	public final static String PRERELEASE = "${prerelease}";
	public final static String PROJECT = "${project}";
}

The Velocity variables are automatically filled in by the processor.

Elements & Properties

The following annotation elements and properties are available:

Element	Property	Description	Default
project	version.project	The project name.
major	version.major	The major version number.	1
minor	version.major	The minor version number.	0
patch	version.patch	The patch version number.	0
prerelease	version.prerelease	The pre-release version.
buildmeta	version.buildmeta	The build metadata version.
className		The name of the generated class.	GeneratedVersion
properties		The properties file.
template		The template file.	version.vm

In order to easily incorporate with existing projects, the property keys may be assigned custom values:

@Version(
  properties = "example.properties", 
  majorKey = "example.major",
  minorKey = "example.minor",
  patchKey = "example.patch",
  prereleaseKey = "example.prerelease",
  buildmetaKey = "example.buildmeta",
  projectKey = "example.project"
)
public class Example {
// ...

# example.properties
example.project=Example
example.major=1
example.minor=0
example.patch=0
...