Record Class SemanticVersion

java.lang.Object
java.lang.Record
xyz.apollosoftware.bibliothiki.versioning.schemes.semver.SemanticVersion
Record Components:
major - The major version component (for breaking API changes).
minor - The minor version component (for backwards-compatible functionality).
patch - The patch version component (for backwards-compatible bug fixes).
preRelease - The list of pre-release identifiers (see SemanticVersion.PreReleaseIdentifier).
buildMetadata - The list of build metadata identifiers (see SemanticVersion.BuildIdentifier).
All Implemented Interfaces:
Comparable<SemanticVersion>, Version<SemanticVersion>
public record SemanticVersion(int major, int minor, int patch, List<SemanticVersion.PreReleaseIdentifier> preRelease, List<SemanticVersion.BuildIdentifier> buildMetadata) extends Record implements Version<SemanticVersion>
A Semantic Versioning (SemVer) version.

This is an immutable representation of a SemVer string.

Implementation Note:

This class has a natural ordering that is inconsistent with equals. Semantic Versioning (SemVer) does not consider build metadata when determining precedence, however it is included naturally for equals(Object) to maintain principle of least surprise.

Therefore, if you wish to compare Semantic Versions for equality per the SemVer specification, you should use compareTo(SemanticVersion)

  • Constructor Details

    • SemanticVersion

      public SemanticVersion(int major, int minor, int patch, List<SemanticVersion.PreReleaseIdentifier> preRelease, List<SemanticVersion.BuildIdentifier> buildMetadata)
      Constructor for semantic version representations.

      If preRelease or buildMetadata are null, they are replaced with empty lists. They are also both frozen to ensure they are immutable.

      Parameters:
      major - The major version component (for breaking API changes).
      minor - The minor version component (for backwards-compatible functionality).
      patch - The patch version component (for backwards-compatible bug fixes).
      preRelease - The list of pre-release identifiers (see SemanticVersion.PreReleaseIdentifier).
      buildMetadata - The list of build metadata identifiers (see SemanticVersion.BuildIdentifier).

  • Method Details

    • builder

      public static @NonNull SemanticVersion.Builder builder()
      Construct a new SemanticVersion.Builder for SemanticVersion representations.
      Returns:
      The new builder instance.

    • asBuilder

      public @NonNull SemanticVersion.Builder asBuilder()
      Construct a SemanticVersion.Builder that has the current version's values set as initial values.
      Returns:
      The new builder instance.

    • isPreRelease

      public boolean isPreRelease()
      Whether the version is a pre-release version.

      This is true when there are one, or more, pre-release components in the version string.

      Returns:
      True if, and only if, this is a pre-release version.

    • hasBuildMetadata

      public boolean hasBuildMetadata()
      Whether the version has build metadata.

      This is true when there are one, or more, build metadata components in the version string.

      Returns:
      True if, and only if, this version string has build metadata.

    • preRelease

      public @NonNull List<SemanticVersion.PreReleaseIdentifier> preRelease()
      The list of pre-release identifiers (see SemanticVersion.PreReleaseIdentifier).

      The constructor for SemanticVersion ensures this is non-null (non pre-release versions have an empty list, instead).

      Returns:
      The list of SemanticVersion.PreReleaseIdentifiers.

    • buildMetadata

      public @NonNull List<SemanticVersion.BuildIdentifier> buildMetadata()
      The list of build metadata identifiers (see SemanticVersion.BuildIdentifier).

      The constructor for SemanticVersion ensures this is non-null (versions with no build metadata have an empty list, instead).

      Returns:
      The list of SemanticVersion.BuildIdentifiers.

    • compareTo

      public int compareTo(@NonNull SemanticVersion other)
      Description copied from interface: Version
      Compares this version with the specified version.

      The comparison adheres to the Comparable specification and semantics.

      Specified by:
      compareTo in interface Comparable<SemanticVersion>
      Specified by:
      compareTo in interface Version<SemanticVersion>
      Parameters:
      other - the object to be compared.
      Returns:
      a negative integer if this version is less than the other version, zero if the versions are equal or a positive integer if this version is greater than the other version.

    • withIncremented

      public @NonNull SemanticVersion withIncremented(@NonNull SemanticVersion.IncrementType incrementType)
      Increments the version by performing an increment of the specified SemanticVersion.IncrementType.

      This method increments the version to the next non-prerelease version. To increment a pre-release version, use withIncrementedPreRelease(String) or withIncrementedPreRelease(String, int).

      Parameters:
      incrementType - The type of increment to perform.
      Returns:
      A new SemanticVersion, derived from the current one by performing the specified increment.
      See Also:

    • withIncrementedPreRelease

      public @NonNull SemanticVersion withIncrementedPreRelease(@NonNull String name)
      Increments the specified pre-release version.

      The behavior is identical to withIncrementedPreRelease(String, int) except the initialValue is defined as one for convenience.

      Parameters:
      name - The name of the pre-release version track.
      Returns:
      The incremented version.
      See Also:

    • withIncrementedPreRelease

      public @NonNull SemanticVersion withIncrementedPreRelease(@NonNull String name, int initialValue)
      Increments the specified pre-release version.

      Unlike most other functions in the versioning library, this method is fairly opinionated and describes a specific (but interoperable) approach to versioning with pre-release versions. If you need more specific behavior, it may be preferable to implement your own increment method using the SemanticVersion API.

      If a pre-release version component is present in the string that matches the given name and there is a numeric component immediately following it, the numeric component is incremented. Otherwise, to avoid modifying unintended parts of the version string, the name and initialValue are instead appended to the new version string. If there are multiple occurrences, the first one is matched and incremented.

      To avoid errors, the name must not be a numeric identifier when parsed as a pre-release identifier. If it is, a VersioningException is thrown.

      Parameters:
      name - The name of the pre-release version track (must not be numeric).
      initialValue - The initial value to use (if the pre-release track is not present in the version string). The initial version must be positive.
      Returns:
      The incremented version.
      Throws:
      VersioningException - If the specified name is numeric or if the initial value is negative.
      See Also:

    • toString

      public @NonNull String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in interface Version<SemanticVersion>
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with the compare method from their corresponding wrapper classes.
      Specified by:
      equals in interface Version<SemanticVersion>
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.
      See Also:

    • major

      public int major()
      Returns the value of the major record component.
      Returns:
      the value of the major record component

    • minor

      public int minor()
      Returns the value of the minor record component.
      Returns:
      the value of the minor record component

    • patch

      public int patch()
      Returns the value of the patch record component.
      Returns:
      the value of the patch record component