Package jmri

Class Version

java.lang.Object
jmri.Version
public class Version extends Object
Defines a simple place to get the JMRI version string.

JMRI version strings are of the form x.y.z-m:

  • x, called the "major" number, is a small integer that increases with time
  • y, called the "minor" number, is a small integer that increases with time
  • z, called the "test" or "build" number, is a small integer increasing with time, perhaps followed by a couple of modifier characters. As a special case, this is omitted for Production Releases.
  • m, called the modifier, is a string that further describes the build. A common modifier is "plus" which denotes an unofficial build.
Hence you expect to see JMRI versions called things like "4.7.2", "4.6", "4.7.3plus", "4.7.2-pjc", "4.7.2plus-pjc".

The version string shown by a JMRI program or used to label a download comes in two forms, depending on whether it was built by an "official" process or not, which in turn is determined by the "release.official" property:

Official
  • If the revision number e.g. 123abc (git hash) is available in release.revision_id, then "4.1.1+R123abc". Note the "R".
  • Else "4.1.1+(date)", where the date comes from the release.build_date property.
Unofficial
Unofficial releases are marked by "plus" after the version number, and inclusion of the building user's ID.
  • If the revision number e.g. 123abc (git hash) is available in release.revision_id, then "4.1.1plus+(user)+(date)+R123abc". Note the "R".
  • Else "4.1.1+(user)+(date)", where the date comes from the release.build_date property.
The release.revision_id, release.build_user and release.build_date properties are set at build time by Ant.

Generally, JMRI updates its version string in the code repository right after a release. Between formal release 1.2.3 and 1.2.4, the string will be 1.2.4plus.

This file is part of JMRI.

JMRI is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation. See the "COPYING" file for a copy of this license.

JMRI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    buildDate
    The date/time of this build.
    static final String
    buildUser
    The user who built this versionBundle, as determined by the build machine.
    static final int
    major
    Major number changes with large incompatible changes in requirements or API.
    static final int
    minor
    Minor number changes with each production versionBundle.
    static final String
    MODIFIER
    The additional MODIFIER for the release.
    static final String
    NON_OFFICIAL
    Descriptor for non-official build.
    static final boolean
    official
    Has this build been created as a possible "official" versionBundle?
    static final String
    revisionId
    The Git revision ID for this versionBundle (if known).
    static final int
    test
    Test number changes with individual releases, generally fastest for test releases.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Version()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static int
    compareCanonicalVersions(String version)
    Compares a canonical version string to the JMRI canonical version and returns an integer indicating if the string is less than, equal to, or greater than the JMRI canonical version.
    static int
    compareCanonicalVersions(String version1, String version2)
    Compares two canonical version strings and returns an integer indicating if the first string is less than, equal to, or greater than the second string.
    static String
    getCanonicalVersion()
    Return the version as major.minor.test-modifiers.
    static String
    getCopyright()
    Return the application copyright as a String.
    static String
    getModifier()
    Get the MODIFIER in the 1.2.3-MODIFIER version name.
    static boolean
    isCanonicalVersion(String version)
    Tests that a string contains a canonical version string.
    static void
    main(String[] args)
    Standalone print of version string and exit.
    static String
    name()
    Provide the current version string.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • major

      public static final int major
      Major number changes with large incompatible changes in requirements or API.

    • minor

      public static final int minor
      Minor number changes with each production versionBundle. Odd is development, even is production.

    • test

      public static final int test
      Test number changes with individual releases, generally fastest for test releases. In production releases, if non-zero, indicates a bug fix only release.

    • MODIFIER

      public static final String MODIFIER
      The additional MODIFIER for the release. Used to indicate a parallel release of a feature that has not been accepted into main stream development.

    • NON_OFFICIAL

      public static final String NON_OFFICIAL
      Descriptor for non-official build. Included in name(), but not in getCanonicalVersion().
      See Also:

    • buildUser

      public static final String buildUser
      The user who built this versionBundle, as determined by the build machine.

    • revisionId

      public static final String revisionId
      The Git revision ID for this versionBundle (if known).

    • buildDate

      public static final String buildDate
      The date/time of this build.

    • official

      public static final boolean official
      Has this build been created as a possible "official" versionBundle?

  • Constructor Details

  • Method Details

    • getModifier

      public static String getModifier()
      Get the MODIFIER in the 1.2.3-MODIFIER version name. Non-official versions include "plus" in the MODIFIER.
      Returns:
      the third term, possibly an empty String if test is 0

    • name

      public static String name()
      Provide the current version string.

      This string is built using various known build parameters, including the versionBundle.{major,minor,build} values, the MODIFIER, the Git revision ID (if known) and the official property

      Returns:
      The current version string

    • isCanonicalVersion

      public static boolean isCanonicalVersion(String version)
      Tests that a string contains a canonical version string.

      A canonical version string is a string in the form x.y.z[-a[-b[-...]]] where parts x, y, and z are integers and parts a, b, ... are free-form text and is different than the version string displayed using name(). The canonical version string for a JMRI instance is available using getCanonicalVersion(). The canonical version will not include official indicators or build metadata.

      Parameters:
      version - version string to check
      Returns:
      true if version is a canonical version string

    • compareCanonicalVersions

      public static int compareCanonicalVersions(String version) throws IllegalArgumentException
      Compares a canonical version string to the JMRI canonical version and returns an integer indicating if the string is less than, equal to, or greater than the JMRI canonical version.
      Parameters:
      version - version string to compare
      Returns:
      -1, 0, or 1 if version is less than, equal to, or greater than JMRI canonical version
      Throws:
      IllegalArgumentException - if version is not a canonical version string
      See Also:

    • compareCanonicalVersions

      public static int compareCanonicalVersions(String version1, String version2) throws IllegalArgumentException
      Compares two canonical version strings and returns an integer indicating if the first string is less than, equal to, or greater than the second string. This comparison ignores modifiers.
      Parameters:
      version1 - a canonical version string
      version2 - a canonical version string
      Returns:
      -1, 0, or 1 if version1 is less than, equal to, or greater than version2
      Throws:
      IllegalArgumentException - if either version string is not a canonical version string
      See Also:

    • getCanonicalVersion

      public static String getCanonicalVersion()
      Return the version as major.minor.test-modifiers. The test value is always present. The "plus" modifier is not present in the canonical version.
      Returns:
      the canonical version

    • getCopyright

      public static String getCopyright()
      Return the application copyright as a String.
      Returns:
      the copyright

    • main

      public static void main(String[] args)
      Standalone print of version string and exit. This is used in the build.xml to generate parts of the installer versionBundle file name, so take care in altering this code to make sure the ant recipes are also suitably modified.
      Parameters:
      args - command-line arguments