Package jmri

Class Version

  • public class Version
extends java.lang.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 java.lang.String buildDate
      The date/time of this build.
      static java.lang.String buildUser
      The user who built this versionBundle, as determined by the build machine.
      static int major
      Major number changes with large incompatible changes in requirements or API.
      static int minor
      Minor number changes with each production versionBundle.
      static java.lang.String MODIFIER
      The additional MODIFIER for the release.
      static java.lang.String NON_OFFICIAL
      Descriptor for non-official build.
      static boolean official
      Has this build been created as a possible "official" versionBundle?
      static java.lang.String revisionId
      The Git revision ID for this versionBundle (if known).
      static int test
      Test number changes with individual releases, generally fastest for test releases.

    • Constructor Summary

      Constructors 
      Constructor Description
      Version()  

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static int compareCanonicalVersions​(java.lang.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​(java.lang.String version1, java.lang.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 java.lang.String getCanonicalVersion()
      Return the version as major.minor.test-modifiers.
      static java.lang.String getCopyright()
      Return the application copyright as a String.
      static java.lang.String getModifier()
      Get the MODIFIER in the 1.2.3-MODIFIER version name.
      static boolean isCanonicalVersion​(java.lang.String version)
      Tests that a string contains a canonical version string.
      static void main​(java.lang.String[] args)
      Standalone print of version string and exit.
      static java.lang.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 Detail

      • 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 java.lang.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.

      • buildUser

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

      • revisionId

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

      • buildDate

        public static final java.lang.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 Detail

    • Method Detail

      • getModifier

        public static java.lang.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 java.lang.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​(java.lang.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​(java.lang.String version)
                                    throws java.lang.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:
        java.lang.IllegalArgumentException - if version is not a canonical version string
        See Also:
        Comparable.compareTo(java.lang.Object)

      • compareCanonicalVersions

        public static int compareCanonicalVersions​(java.lang.String version1,
                                           java.lang.String version2)
                                    throws java.lang.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:
        java.lang.IllegalArgumentException - if either version string is not a canonical version string
        See Also:
        Comparable.compareTo(java.lang.Object)

      • getCanonicalVersion

        public static java.lang.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 java.lang.String getCopyright()
        Return the application copyright as a String.
        Returns:
        the copyright

      • main

        public static void main​(java.lang.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