Record Class MlConfigVersion

java.lang.Object
java.lang.Record
org.elasticsearch.xpack.core.ml.MlConfigVersion
All Implemented Interfaces:
Comparable<MlConfigVersion>, VersionId<MlConfigVersion>, org.elasticsearch.xcontent.ToXContent, org.elasticsearch.xcontent.ToXContentFragment

public record MlConfigVersion(int id) extends Record implements VersionId<MlConfigVersion>, org.elasticsearch.xcontent.ToXContentFragment
The version number associated with various ML features. This class is needed in addition to TransportVersion because transport version cannot be persisted in stored documents or cluster state metadata. Hence, this class is designed to be persisted in human-readable format, and indicate the age of that state or config. In addition, we want the written form of MlConfigVersion version numbers to be parseable by the Version class so that in mixed version clusters during upgrades the old nodes won't throw exceptions when parsing these new versions.

Prior to 8.10.0, the release Version was used everywhere. This class separates the ML config format version from the running node version.

Each ML config version constant has an id number, which for versions prior to 8.10.0 is the same as the release version for backwards compatibility. In 8.10.0 this is changed to an incrementing number, disconnected from the release version, starting at 10000099. This format is chosen for best compatibility with old node versions. *

Each version constant has a unique id string. This is not actually used in the binary protocol, but is there to ensure each protocol version is only added to the source file once. This string needs to be unique (normally a UUID, but can be any other unique nonempty string). If two concurrent PRs add the same ML config version, the different unique ids cause a git conflict, ensuring the second PR to be merged must be updated with the next free version first. Without the unique id string, git will happily merge the two versions together, resulting in the same ML config version being used across multiple commits, causing problems when you try to upgrade between those two merged commits.

Version compatibility

The earliest version is hardcoded in the FIRST_ML_VERSION field. This cannot be dynamically calculated from the major/minor versions of Version, because MlConfigVersion does not have separate major/minor version numbers. So the minimum version is simply hard-coded as the earliest version where ML existed (5.4.0).

Adding a new version

A new ML config version should be added every time a change is made to the serialization format of one or more ML config or state classes. Each ML config version should only be used in a single merged commit (apart from BwC versions copied from Version).

To add a new ML config version, add a new constant at the bottom of the list that is one million greater than the current highest version, ensure it has a unique id, and update the CURRENT constant to point to the new version.

Reverting a ML config version

If you revert a commit with a ML config version change, you must ensure there is a new ML config version representing the reverted change. Do not let the ML config version go backwards, it must always be incremented.
  • Field Details

  • Constructor Details

    • MlConfigVersion

      public MlConfigVersion(int id)
      Creates an instance of a MlConfigVersion record class.
      Parameters:
      id - the value for the id record component
  • Method Details

    • getAllVersionIds

      public static NavigableMap<Integer,MlConfigVersion> getAllVersionIds(Class<?> cls)
      Obtain a selection of (nearly) all registered versions. This method should only ever be used internally - to initialize VERSION_IDS, and in unit tests. It should never be called directly in production code.
    • readVersion

      public static MlConfigVersion readVersion(StreamInput in) throws IOException
      Throws:
      IOException
    • fromId

      public static MlConfigVersion fromId(int id)
    • fromNode

      public static MlConfigVersion fromNode(DiscoveryNode node)
    • writeVersion

      public static void writeVersion(MlConfigVersion version, StreamOutput out) throws IOException
      Throws:
      IOException
    • min

      public static MlConfigVersion min(MlConfigVersion version1, MlConfigVersion version2)
      Returns the minimum version of version1 and version2 Legacy, semantic style representations are treated as being before all new, single number representations
    • max

      public static MlConfigVersion max(MlConfigVersion version1, MlConfigVersion version2)
      Returns the maximum version of version1 and version2 New, single number representations are treated as being after all legacy, semantic style representations.
    • getMinMlConfigVersion

      public static MlConfigVersion getMinMlConfigVersion(DiscoveryNodes nodes)
    • getMaxMlConfigVersion

      public static MlConfigVersion getMaxMlConfigVersion(DiscoveryNodes nodes)
    • getMinMaxMlConfigVersion

      public static org.elasticsearch.core.Tuple<MlConfigVersion,MlConfigVersion> getMinMaxMlConfigVersion(DiscoveryNodes nodes)
    • getMlConfigVersionForNode

      public static MlConfigVersion getMlConfigVersionForNode(DiscoveryNode node)
    • fromString

      public static MlConfigVersion fromString(String str)
    • toString

      public 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 class Record
      Returns:
      a string representation of this object
    • toXContent

      public org.elasticsearch.xcontent.XContentBuilder toXContent(org.elasticsearch.xcontent.XContentBuilder builder, org.elasticsearch.xcontent.ToXContent.Params params) throws IOException
      Specified by:
      toXContent in interface org.elasticsearch.xcontent.ToXContent
      Throws:
      IOException
    • 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. All components in this record class are compared with '=='.
      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.
    • id

      public int id()
      Returns the value of the id record component.
      Specified by:
      id in interface VersionId<MlConfigVersion>
      Returns:
      the value of the id record component