Package net.ssterling.bukkitversion

Class BukkitVersion

java.lang.Object
net.ssterling.bukkitversion.BukkitVersion
All Implemented Interfaces:
Comparable<BukkitVersion>
public final class BukkitVersion extends Object implements Comparable<BukkitVersion>
The BukkitVersion class derives and contains the values extrapolated from a Bukkit server string.

The simplest way to use this from within a Bukkit plugin is by using the value of getBukkitVersion() to construct a BukkitVersion object, like such: new BukkitVersion(Bukkit.getBukkitVersion());.

For those who learn better by example, refer to the following example usage from within a Bukkit plugin: 

package net.ssterling.exampleplugin;

import org.bukkit.Bukkit;
import org.bukkit.JavaPlugin;
import net.ssterling.bukkitversion.BukkitVersion;

public class ExamplePlugin extends JavaPlugin
{
        @Override
        public void onEnable()
        {
                // Grabs the server version automatically
                BukkitVersion version = new BukkitVersion();
                
                if (version.compareTo(new BukkitVersion("1.12.2-R0.1-SNAPSHOT")) == 0) {
                        getLogger().info("Running on Minecraft 1.12.2-R0.1-SNAPSHOT");
                }

                // More typical format: specify just major.minor.patch
                if (version.compareTo(new BukkitVersion("1.2.5", false)) >= 0) {
                        getLogger().info("Running on 1.2.5 or above"); // (not a typo)
                }

                // Comparison will stop at a certain point, in this case: minor version
                BukkitVersion ver = new BukkitVersion("1.8.8R1.0-SNAPSHOT", false);
                if (version.compareTo(ver, BukkitVersion.Component.MINOR) < 0) {
                        getLogger().info("Running below Minecraft 1.8");
                }
        }
}
Since:
0.1.0
Author:
Seth Price

  • Field Details

    • beta

      protected boolean beta
      Whether the version is a beta release (e.g. b1.7.3).

    • major

      protected Integer major
      The major version number. Assumed to always be present, and of value 1 for the forseeable future.

    • minor

      protected Integer minor
      The minor version number. Assumed to always be present.

    • patch

      protected Integer patch
      The patch version number. Null if not present in version string.

    • prerelease

      protected Integer prerelease
      The prerelease number of the version. Null if not present in version string.

    • release_candidate

      protected Integer release_candidate
      The release candidate number of the version. Null if not present in version string.

    • revision_major

      protected Integer revision_major
      The major revision number of the version. Assumed to always be present.

    • revision_minor

      protected Integer revision_minor
      The minor revision number of the version.

    • RC_OFFSET

      private static final int RC_OFFSET
      The number to add to release_candidate when returning its value from getPrereleaseOrReleaseCandidate().
      See Also:

    • PRERC_NULL_VALUE

      private static final int PRERC_NULL_VALUE
      The number to return from getPrereleaseOrReleaseCandidate() when both prerelease and release_candidate are null.
      See Also:

    • PATTERN

      private static final Pattern PATTERN
      The regex pattern used to dissect a version string.

      Both vanilla Minecraft versions (such as 1.6.4, 1.12.2-pre2 or 1.18-rc4) and Bukkit API versions (vanilla versions suffixed usually with a revision number and always with a snapshot qualifier, such as 1.2.5-R5.2-SNAPSHOT or 1.14-pre5-SNAPSHOT) will match this pattern.

      For those unfamiliar with regular expressions but still curious what constitutes a valid version string per this pattern, the author recommends experimenting with this pattern on Regex101.

  • Constructor Details

    • BukkitVersion

      public BukkitVersion()
      Creates an instance of BukkitVersion by parsing the value of Bukkit.getBukkitVersion(). May only be used when the Bukkit API is available, such as from within a Bukkit plugin.
      Throws:
      NoSuchMethodError - if Bukkit API cannot be found
      IllegalArgumentException - if Bukkit.getBukkitVersion() does not return a valid Bukkit API version string
      Since:
      0.1.0

    • BukkitVersion

      public BukkitVersion(String version)
      Creates a BukkitVersion object by parsing a Bukkit API version string.
      Parameters:
      version - full Bukkit API version string
      Throws:
      NullPointerException - if version is null
      IllegalArgumentException - if version is not a valid Bukkit API version string
      Since:
      0.1.0

    • BukkitVersion

      public BukkitVersion(String version, boolean strict)
      Creates a BukkitVersion object by parsing a version string, such as the value of Bukkit.getBukkitVersion(), or something simpler, such as 1.19.1-pre3.
      Parameters:
      version - version string
      strict - true to require the string be a valid Bukkit API version string, false to allow vanilla Minecraft version strings
      Throws:
      NullPointerException - if version is null
      IllegalArgumentException - if strict is true and version is not a valid Bukkit API version string
      Since:
      0.1.0

    • BukkitVersion

      public BukkitVersion(Integer major, Integer minor, Integer patch, Integer prerelease, Integer release_candidate, Integer revision_major, Integer revision_minor, boolean beta)
      Creates a BukkitVersion object by inputting the individual components of a Bukkit API version.
      Parameters:
      major - major version number
      minor - minor version number
      patch - patch version number (null if none)
      prerelease - prerelease number (null if none)
      release_candidate - release candidate number (null if none)
      revision_major - revision number major component (null if none)
      revision_minor - revision number minor component (null if none)
      beta - true if version is beta, false otherwise
      Throws:
      NullPointerException - if any of the following parameters are null: major, minor
      IllegalArgumentException - if both prerelease and release_candidate parameters are not null
      Since:
      0.1.0

  • Method Details

    • fromString

      private void fromString(String version, boolean strict)
      Creates a BukkitVersion object by parsing a version string, such as the value of Bukkit.getBukkitVersion(), or something simpler, such as 1.19.1-pre3.
      Parameters:
      version - version string
      strict - true to require the string be a valid Bukkit API version string, false to allow vanilla Minecraft version strings
      Throws:
      NullPointerException - if is null
      IllegalArgumentException - if strict is true and version is not a valid Bukkit API version string
      Since:
      0.1.0

    • isBeta

      public boolean isBeta()
      Gets the beta status.
      Returns:
      true if version is beta, false otherwise
      Since:
      0.3.0

    • getMajor

      public Integer getMajor()
      Gets the major version number.
      Returns:
      major component of the version contained in the object
      Since:
      0.1.0

    • getMinor

      public Integer getMinor()
      Gets the minor version number.
      Returns:
      minor component of the version contained in the object
      Since:
      0.1.0

    • getPatch

      public Integer getPatch()
      Gets the patch number.
      Returns:
      patch number of the version contained in the object, or null if not present
      Since:
      0.1.0

    • getPrerelease

      public Integer getPrerelease()
      Gets the pre-release version number.
      Returns:
      prerelease number of the version contained in the object, or null if not present
      Since:
      0.1.0

    • getReleaseCandidate

      public Integer getReleaseCandidate()
      Gets the release candidate number.
      Returns:
      release candidate number of the version contained in the object, or null if not present
      Since:
      0.1.0

    • getPrereleaseOrReleaseCandidate

      protected Integer getPrereleaseOrReleaseCandidate()
      Gets the release candidate number, or, if not present, the value of Integer.MAX_VALUE.

      This is a workaround that allows easier comparison of pre-releases and release candidates to their corresponding releases and amongst each other.

      Returns:
      pre-release number of the version contained in the object, if present; or, the sum of the release candidate number of the version contained in the object and the constant RC_OFFSET, if release candidate number is present; or, PRERC_NULL_VALUE if none of the aforementioned criteria are met
      Since:
      0.1.0

    • getRevisionMajor

      public Integer getRevisionMajor()
      Gets the major version number of the revision number.
      Returns:
      major component of the revision number of the version contained in the object
      Since:
      0.1.0

    • getRevisionMinor

      public Integer getRevisionMinor()
      Gets the minor version number of the revision number.
      Returns:
      minor component of the revision number of the version contained in the object, or null if not present
      Since:
      0.1.0

    • toVanillaString

      public String toVanillaString()
      Builds a vanilla Minecraft version string.
      Returns:
      Minecraft version string congruent with the version contained within the object
      Since:
      0.1.0

    • toString

      public String toString()
      Builds a Bukkit API version string.
      Overrides:
      toString in class Object
      Returns:
      Bukkit API version string congruent with the version contained within the object
      Since:
      0.1.0

    • compareTo

      public int compareTo(BukkitVersion compare)
      Compares a given Bukkit version to that contained in the object.
      Specified by:
      compareTo in interface Comparable<BukkitVersion>
      Parameters:
      compare - the object to which a comparison will be made
      Returns:
      -1 if the version provided is newer than that contained in the object, 0 if the version provided is the same as that contained in the object, or 1 if the version provided is older than that contained in the object
      Since:
      0.1.0

    • compareTo

      public int compareTo(BukkitVersion compare, BukkitVersion.Component granularity)
      Compares a given Bukkit version to that contained in the object, ignoring any quantifiers past that specified.
      Parameters:
      compare - the object to which a comparison will be made
      granularity - the least significant component of the version to be compared
      Returns:
      ignoring any quantifiers less significant than that specified in the granularity parameter: -1 if the version provided is newer than that contained in the object, 0 if the version provided is the same as that contained in the object, or 1 if the version provided is older than that contained in the object
      Since:
      0.1.0