Class SchemaVersion

java.lang.Object
express.mvp.myra.codec.schema.SchemaVersion
All Implemented Interfaces:
Comparable<SchemaVersion>
public final class SchemaVersion extends Object implements Comparable<SchemaVersion>
Represents a semantic version for myra-codec schemas.

Schema versions use semantic versioning (MAJOR.MINOR.PATCH) with the following compatibility rules:

  • MAJOR: Breaking changes - new field layouts, removed fields, type changes
  • MINOR: Backward-compatible additions - new optional fields, new message types
  • PATCH: Backward-compatible fixes - documentation, cosmetic changes

The wire format encodes version as a single short value using the formula: (major * 256) + minor (patch is not encoded in wire format, only used for schema management).

Wire Format Compatibility:

  • Messages from the same major version are compatible
  • Decoders can process messages with minor version ≤ their schema's minor version
  • Major version mismatches should be rejected

Example: 

SchemaVersion v = SchemaVersion.parse("2.3.1");
short wireVersion = v.toWireFormat();  // Returns (2 * 256) + 3 = 515

// Compatibility check
SchemaVersion decoder = SchemaVersion.parse("2.5.0");
if (v.isCompatibleWith(decoder)) {
    // Safe to decode
}
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    MAX_MAJOR
    Maximum major version that can be encoded in wire format (0-127, since we use 8 bits).
    static final int
    MAX_MINOR
    Maximum minor version that can be encoded in wire format (0-255).

  • Constructor Summary

    Constructors
    Constructor
    Description
    SchemaVersion(int major, int minor)
    Creates a version with major.minor only (patch defaults to 0).
    SchemaVersion(int major, int minor, int patch)
    Creates a new schema version.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    compareTo(SchemaVersion other)
     
    boolean
    equals(Object o)
     
    static SchemaVersion
    fromWireFormat(short wireVersion)
    Creates a SchemaVersion from its wire format representation.
    int
    hashCode()
     
    boolean
    isBreakingChangeFrom(SchemaVersion other)
    Checks if this version is a breaking change from another version.
    boolean
    isCompatibleWith(SchemaVersion decoderVersion)
    Checks if this schema version is compatible with a decoder schema version.
    int
    major()
    Returns the major version number.
    int
    minor()
    Returns the minor version number.
    static SchemaVersion
    parse(String versionString)
    Parses a semantic version string.
    int
    patch()
    Returns the patch version number.
    String
    toShortString()
    Returns a version string without patch for display (e.g., "1.2").
    String
    toString()
     
    short
    toWireFormat()
    Converts this version to the wire format representation.

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • MAX_MAJOR

      public static final int MAX_MAJOR
      Maximum major version that can be encoded in wire format (0-127, since we use 8 bits).
      See Also:

    • MAX_MINOR

      public static final int MAX_MINOR
      Maximum minor version that can be encoded in wire format (0-255).
      See Also:

  • Constructor Details

    • SchemaVersion

      public SchemaVersion(int major, int minor, int patch)
      Creates a new schema version.
      Parameters:
      major - the major version (0-127 for wire format compatibility)
      minor - the minor version (0-255 for wire format compatibility)
      patch - the patch version (not encoded in wire format)
      Throws:
      IllegalArgumentException - if versions are negative or exceed limits

    • SchemaVersion

      public SchemaVersion(int major, int minor)
      Creates a version with major.minor only (patch defaults to 0).
      Parameters:
      major - the major version
      minor - the minor version

  • Method Details

    • parse

      public static SchemaVersion parse(String versionString)
      Parses a semantic version string.
      Parameters:
      versionString - the version string (e.g., "1.0.0", "2.3", "1.0")
      Returns:
      the parsed SchemaVersion
      Throws:
      IllegalArgumentException - if the string is not a valid version

    • fromWireFormat

      public static SchemaVersion fromWireFormat(short wireVersion)
      Creates a SchemaVersion from its wire format representation.
      Parameters:
      wireVersion - the wire format value (major * 256 + minor)
      Returns:
      the SchemaVersion

    • major

      public int major()
      Returns the major version number.
      Returns:
      the major version (0-127)

    • minor

      public int minor()
      Returns the minor version number.
      Returns:
      the minor version (0-255)

    • patch

      public int patch()
      Returns the patch version number.
      Returns:
      the patch version

    • toWireFormat

      public short toWireFormat()
      Converts this version to the wire format representation. The formula is: (major * 256) + minor.
      Returns:
      the wire format value as a short

    • isCompatibleWith

      public boolean isCompatibleWith(SchemaVersion decoderVersion)
      Checks if this schema version is compatible with a decoder schema version.

      Compatibility rules:

      • Major versions must match exactly
      • This version's minor must be ≤ decoder's minor (decoder can handle newer features)
      Parameters:
      decoderVersion - the version of the decoder/consumer schema
      Returns:
      true if this version can be decoded by the decoder

    • isBreakingChangeFrom

      public boolean isBreakingChangeFrom(SchemaVersion other)
      Checks if this version is a breaking change from another version.
      Parameters:
      other - the other version to compare
      Returns:
      true if major versions differ (indicating breaking change)

    • compareTo

      public int compareTo(SchemaVersion other)
      Specified by:
      compareTo in interface Comparable<SchemaVersion>

    • equals

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

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toShortString

      public String toShortString()
      Returns a version string without patch for display (e.g., "1.2").
      Returns:
      the major.minor string