All Implemented Interfaces:: Serializable

@Versioned
public final class Version
extends Object
implements Serializable

Describe the version of a specific Java delivery (app or library).

The version contains three pieces of information:

maven artifact id, which is defined by ${project.artifactId}
maven project version, which is defined by ${project.version}
scm build version, usually provided by buildnumber-maven-plugin

Usage

1. Prepare version file

Application or library developer put a file named .version into a dir corresponding to app/lib’s package inside the resources dir. For example if a library package name is org.mrcool.swissknife, then put the .version file under

src/main/resources/org/mrcool/swissknife

The content of the .version file should be

# artifact is optional, if not provided the package name will be used
artifact=${project.artifactId}

# version is mandatory, if not provided then UNKNOWN version will be returned
version=${project.version}

# build is optional, if not provided then empty string will be used
build=${buildNumber} # optional

Note don’t forget to set resource filter in the library’s pom.xml file:

<resources>
  <resource>
    <directory>src/main/resources</directory>
    <filtering>true</filtering>
   </resource>
</resources>

Note as a general rule, do NOT put the .version file for the first level package, e.g. org, com, net etc. Version tool will never read the .version file for a package name that does not contain a . inside

2. Retrieve the version info

In order to obtain the version information about a library or app’s class, one can use the API provided by this Version class:

Version swissKnifeVersion = Version.of(org.mrcool.siwssknife.SwissKnife.class);
System.out.println(swissKnifeVersion.getPackage()); // print `org.mrcool.swissknife`
System.out.println(swissKnifeVersion.getArtifactId()); // print `swissknife`
System.out.println(swissKnifeVersion.getProjectVersion()); // print `1.0`
System.out.println(swissKnifeVersion.getBuildNumber()); // print `ebf1`
System.out.println(swissKnifeVersion.getVersion()); // print `r1.0-ebf1`
System.out.println(swissKnifeVersion); // print `swissknife-r1.0-ebf1`

See Also:: Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`PROP_SUPPRESS_VAR_FOUND_WARNING` The system property name used to check if it should suppress warning when variables found in version string
`static Version`	`UNKNOWN` The `UNKNOWN` version instance.
`static String`	`UNKNOWN_STR` The string literal `unknown`.
`static Version`	`VERSION` Keep track the version of osgl-version library.

Constructor Summary

Constructors
Constructor and Description
`Version(String packageName, String artifactId, String projectVersion, String buildNumber)` Construct a `Version` instance with packageName, artifactId, projectVersion and buildName.

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`equals(Object o)`
`static Version`	`get()` Returns `Version` of the caller class.
`String`	`getArtifactId()` Returns artifact id, i.e.
`String`	`getBuildNumber()` Returns the build number which is defined in `${buildNumber}` maven environment variable when buildnumber-maven-plugin is provided
`String`	`getPackageName()` Returns app/library package name.
`String`	`getProjectVersion()` Returns project version which is defined in `${project.version}` maven environment variable
`String`	`getVersion()` Returns version tag: a full version string.
`int`	`hashCode()`
`boolean`	`isUnknown()` Check if a `Version` instance is `UNKNOWN`.
`static Version`	`of(Class<?> clazz)` Returns a `Version` of the library contains the class specified.
`static Version`	`of(Package pkg)` Returns a `Version` of the library contains the package specified.
`static Version`	`ofPackage(String packageName)` Returns a `Version` corresponding to the package name specified.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - PROP_SUPPRESS_VAR_FOUND_WARNING
```
public static String PROP_SUPPRESS_VAR_FOUND_WARNING
```
    The system property name used to check if it should suppress warning when variables found in version string
  - UNKNOWN_STR
```
public static final String UNKNOWN_STR
```
    The string literal unknown.
    
    See Also:
    Constant Field Values
  - UNKNOWN
```
public static final Version UNKNOWN
```
    The UNKNOWN version instance.
    
    This is used when a certain library/app does not have .version file defined.
    
    The UNKNOWN is constructed with
    - empty string for getPackageName()
    - UNKNOWN_STR for getArtifactId() and getProjectVersion()
    - null for getBuildNumber()
  - VERSION
```
public static final Version VERSION
```
    Keep track the version of osgl-version library.
- Constructor Detail
  - Version
```
public Version(String packageName,
       String artifactId,
       String projectVersion,
       String buildNumber)
```
    Construct a Version instance with packageName, artifactId, projectVersion and buildName.
    
    Parameters:
    packageName - the package name
    artifactId - the artifact id
    projectVersion - the project version
    buildNumber - the build number
- Method Detail
  - getArtifactId
```
public String getArtifactId()
```
    Returns artifact id, i.e. the name of the library or application
    
    Returns:
    artifact id
  - getPackageName
```
public String getPackageName()
```
    Returns app/library package name.
    
    package name is used to find the .version file when loading the version information
    
    Returns:
    the package name
  - getProjectVersion
```
public String getProjectVersion()
```
    Returns project version which is defined in ${project.version} maven environment variable
    
    Returns:
    the project version
  - getVersion
```
public String getVersion()
```
    Returns version tag: a full version string.
    
    When buildNumber exists the version tag is composed of projectVersion a buildNumber with the following pattern:
    
    ${patched-projectVersion}-${patched-buildNumber}
    
    Where patched-projectVersion could be one of the following:
    - If projectVersion ends with -SNAPSHOT, then "v" + projectVersion
    - Otherwise, "R" + projectVersion
    patched-buildNumber is "b" + buildNumber
    
    If buildNumber is not defined then the version tag is the patched-projectVersion as described above
    Returns:
    a version tag as described
  - getBuildNumber
```
public String getBuildNumber()
```
    Returns the build number which is defined in ${buildNumber} maven environment variable when buildnumber-maven-plugin is provided
    
    Returns:
    the SCM build number
  - isUnknown
```
public boolean isUnknown()
```
    Check if a Version instance is UNKNOWN.
    
    Returns:
    true if this version is unknown or false otherwise
  - equals
```
public boolean equals(Object o)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - get
```
public static Version get()
```
    Returns Version of the caller class.
    
    Returns:
    the caller class version
  - ofPackage
```
public static Version ofPackage(String packageName)
```
    Returns a Version corresponding to the package name specified.
    
    This method will tried to check if local cache contains the package name first, and return the version instance mapped to the package name in local cache, or if not found in local cache try to load the .version file as a resource corresponding to the package name.
    
    If the .version file not found, this method will try to get version of parent package until the package name is empty, in which case the UNKNOWN will be returned
    
    Parameters:
    packageName - the package name
    
    Returns:
    a Version instance for that package
  - of
```
public static Version of(Class<?> clazz)
```
    Returns a Version of the library contains the class specified.
    
    Parameters:
    clazz - the class
    
    Returns:
    a Version for that class if provided or UNKNOWN if not provided
    
    Throws:
    
    NullPointerException - if the class specified is null
    See Also:
    ofPackage(String)
  - of
```
public static Version of(Package pkg)
```
    Returns a Version of the library contains the package specified.
    
    Parameters:
    pkg - the package
    
    Returns:
    a Version for the package if provided or UNKNOWN if not provided
    
    Throws:
    
    NullPointerException - if the class specified is null
    See Also:
    ofPackage(String)

Class Version

Usage

1. Prepare version file

2. Retrieve the version info

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

PROP_SUPPRESS_VAR_FOUND_WARNING

UNKNOWN_STR

UNKNOWN

VERSION

Constructor Detail

Version

Method Detail

getArtifactId

getPackageName

getProjectVersion

getVersion

getBuildNumber

isUnknown

equals

hashCode

toString

get

ofPackage

of

of