Class ApiVersion

java.lang.Object
privbot.api.ApiVersion
All Implemented Interfaces:
Comparable<ApiVersion>

@PublicApi public final class ApiVersion extends Object implements Comparable<ApiVersion>
The PrivBot plugin API version, and the rule that decides whether a plugin built against one version may run on another.

CURRENT is the single source of the runtime's API version. The build stamps the same value into the shared-lib jar manifest as "PrivBot-Api-Version", from the privbot.api.version Maven property, through the filtered resource privbot/api/api-version.properties. A plugin records the version it compiled against in its own manifest as "Plugin-Api-Version".

Compatibility (isCompatible(String)): same major, and the plugin's minor is not newer than the runtime's. Patch levels and pre-release qualifiers never matter. A plugin with no "Plugin-Api-Version" is legacy: check(String, String) allows it only on the "first-party" channel. The policy behind the rule is in the SDK docs, Versioning.

Since:
1.0.0
  • Field Details

    • MANIFEST_ATTRIBUTE

      public static final String MANIFEST_ATTRIBUTE
      shared-lib (runtime) jar manifest attribute that carries CURRENT.
      See Also:
    • PLUGIN_MANIFEST_ATTRIBUTE

      public static final String PLUGIN_MANIFEST_ATTRIBUTE
      Plugin jar manifest attribute that carries the API version the plugin compiled against.
      See Also:
    • FIRST_PARTY_CHANNEL

      public static final String FIRST_PARTY_CHANNEL
      The only hub channel on which a legacy plugin (no "Plugin-Api-Version") may load.
      See Also:
    • CURRENT

      public static final String CURRENT
      The API version this runtime provides, for example "1.0.0".

      Deliberately not a compile-time constant: a plugin that reads it gets the version of the PrivBot it runs on, not the one it was compiled against (that one is in its own manifest).

  • Method Details

    • current

      public static ApiVersion current()
      CURRENT, parsed.
    • parse

      public static ApiVersion parse(String text)
      Parses MAJOR[.MINOR[.PATCH]][-qualifier][+build], for example 1.2.0, 1.2 or 1.3.0-SNAPSHOT. Surrounding whitespace is ignored; build metadata is dropped.
      Throws:
      IllegalArgumentException - when text is null, blank or not a version
    • tryParse

      public static Optional<ApiVersion> tryParse(String text)
      parse(java.lang.String), or empty for a null, blank or malformed value.
    • isLegacy

      public static boolean isLegacy(String pluginApiVersion)
      True when a plugin declares no API version (null or blank "Plugin-Api-Version").
    • isCompatible

      public static boolean isCompatible(String pluginApiVersion)
      True when a plugin built against pluginApiVersion may run on this runtime (CURRENT): same major and plugin minor <= runtime minor.

      False for a legacy (blank) or malformed value. Load decisions should use check(String, String), which also applies the legacy rule and explains a refusal.

    • isCompatible

      public static boolean isCompatible(String pluginApiVersion, String runtimeApiVersion)
      isCompatible(String) against an explicit runtime version.
    • canRun

      public boolean canRun(ApiVersion plugin)
      True when this runtime version can run a plugin built against plugin.
    • check

      public static ApiVersion.Verdict check(String pluginApiVersion, String channel)
      The load decision for a plugin on this runtime: compatibility plus the legacy rule (a plugin without an API version loads only from the "first-party" channel).
      Parameters:
      pluginApiVersion - the plugin's "Plugin-Api-Version", or null when absent
      channel - the hub channel the plugin came from (first-party, private, community, local); null counts as not first-party
    • check

      public static ApiVersion.Verdict check(String pluginApiVersion, String channel, String runtimeApiVersion)
      check(String, String) against an explicit runtime version.
    • major

      public int major()
    • minor

      public int minor()
    • patch

      public int patch()
    • qualifier

      public String qualifier()
      Pre-release qualifier such as SNAPSHOT, or null. Ignored by every compatibility rule.
    • compareTo

      public int compareTo(ApiVersion o)
      Specified by:
      compareTo in interface Comparable<ApiVersion>
    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object
    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
    • toString

      public String toString()
      Canonical MAJOR.MINOR.PATCH[-qualifier].
      Overrides:
      toString in class Object