Version (OSGL Bootstrap 1.0.0-BETA-9 API)

java.lang.Object
- org.osgl.bootstrap.Version

```
public final class Version
extends Object
```
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.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`
```

Field Summary

Fields
Modifier and Type Field and Description

static Version UNKNOWN

static String UNKNOWN_STR

Fields
Modifier and Type	Field and Description
`static Version`	`UNKNOWN`
`static String`	`UNKNOWN_STR`

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

All Methods Static Methods Instance Methods Concrete 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
  - UNKNOWN_STR
```
public static final String UNKNOWN_STR
```
    See Also:
    
    Constant Field Values
  - UNKNOWN
```
public static final Version UNKNOWN
```
- 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

UNKNOWN_STR

UNKNOWN

Constructor Detail

Version

Method Detail

getArtifactId

getPackageName

getProjectVersion

getVersion

getBuildNumber

isUnknown

equals

hashCode

toString

get

ofPackage

of

of