Module org.elasticsearch.server
Package org.elasticsearch

Record Class TransportVersion

java.lang.Object
java.lang.Record
org.elasticsearch.TransportVersion
All Implemented Interfaces:
Comparable<TransportVersion>, VersionId<TransportVersion>
public record TransportVersion(String name, int id, TransportVersion nextPatchVersion) extends Record implements VersionId<TransportVersion>
Represents the version of the wire protocol used to communicate between a pair of ES nodes.

Defining transport versions

Transport versions can be defined anywhere, including in plugins/modules. Defining a new transport version is done via the fromName(String) method, for example: 
     private static final TransportVersion MY_NEW_TRANSPORT_VERSION = TransportVersion.fromName("my-new-transport-version");
Names must be logically unique. The same name must not be used to represent two transport versions with differing behavior. However, the same name may be used to define the same constant at multiple use-sites. Alternatively, a single constant can be shared across multiple use sites.

Version compatibility

The earliest compatible version is hardcoded in the TransportVersion.VersionsHolder.MINIMUM_COMPATIBLE field. Previously, this was dynamically calculated from the major/minor versions of Version, but TransportVersion does not have separate major/minor version numbers. So the minimum compatible version is hard-coded as the transport version used by the highest minor release of the previous major version. TransportVersion.VersionsHolder.MINIMUM_COMPATIBLE should be updated appropriately whenever a major release happens.

The earliest CCS compatible version is hardcoded at TransportVersion.VersionsHolder.MINIMUM_CCS_VERSION, as the transport version used by the previous minor release. This should be updated appropriately whenever a minor release happens.

Scope of usefulness of TransportVersion

TransportVersion is a property of the transport connection between a pair of nodes, and should not be used as an indication of the version of any single node. The TransportVersion of a connection is negotiated between the nodes via some logic that is not totally trivial, and may change in future. Any other places that might make decisions based on this version effectively have to reproduce this negotiation logic, which would be fragile. If you need to make decisions based on the version of a single node, do so using a different version value. If you need to know whether the cluster as a whole speaks a new enough TransportVersion to understand a newly-added feature, use ClusterState.getMinTransportVersion().

  • Constructor Details

    • TransportVersion

      public TransportVersion(int id)
      Constructs an unnamed transport version.

    • TransportVersion

      public TransportVersion(String name, int id, TransportVersion nextPatchVersion)
      Creates an instance of a TransportVersion record class.
      Parameters:
      name - the value for the name record component
      id - the value for the id record component
      nextPatchVersion - the value for the nextPatchVersion record component

  • Method Details

    • after

      @Deprecated(forRemoval=true) public boolean after(TransportVersion version)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Specified by:
      after in interface VersionId<TransportVersion>

    • onOrAfter

      @Deprecated(forRemoval=true) public boolean onOrAfter(TransportVersion version)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Specified by:
      onOrAfter in interface VersionId<TransportVersion>

    • between

      @Deprecated(forRemoval=true) public boolean between(TransportVersion lowerInclusive, TransportVersion upperExclusive)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Specified by:
      between in interface VersionId<TransportVersion>

    • collectFromResources

      public static List<TransportVersion> collectFromResources(String component, String resourceRoot, Function<String,InputStream> resourceLoader, String upperBoundFileName)

    • readVersion

      public static TransportVersion readVersion(StreamInput in) throws IOException
      Throws:
      IOException

    • fromId

      public static TransportVersion fromId(int id)
      Finds a TransportVersion by its id. If a transport version with the specified ID does not exist, this method creates and returns a new instance of TransportVersion with the specified ID. The new instance is not registered in TransportVersion.getAllVersions.

    • fromName

      public static TransportVersion fromName(String name)
      Finds a TransportVersion by its name. The parameter name must be a String direct value or validation checks will fail. TransportVersion.fromName("direct_value").

      This will only return the latest known referable transport version for a given name and not its patch versions. Patch versions are constructed as a linked list internally and may be found by cycling through them in a loop using nextPatchVersion().

    • writeVersion

      public static void writeVersion(TransportVersion version, StreamOutput out) throws IOException
      Throws:
      IOException

    • min

      public static TransportVersion min(TransportVersion version1, TransportVersion version2)
      Returns the minimum version of version1 and version2

    • max

      public static TransportVersion max(TransportVersion version1, TransportVersion version2)
      Returns the maximum version of version1 and version2

    • isCompatible

      public static boolean isCompatible(TransportVersion version)
      Returns true if the specified version is compatible with this running version of Elasticsearch.

    • current

      public static TransportVersion current()
      Reference to the most recent transport version. This should be the transport version with the highest id.

    • zero

      public static TransportVersion zero()
      Sentinel value for lowest possible transport version

    • minimumCompatible

      public static TransportVersion minimumCompatible()
      Reference to the earliest compatible transport version to this version of the codebase. This should be the transport version used by the highest minor version of the previous major.

    • minimumCCSVersion

      public static TransportVersion minimumCCSVersion()
      Reference to the minimum transport version that can be used with CCS. This should be the transport version used by the previous minor release.

    • getAllVersions

      public static List<TransportVersion> getAllVersions()
      Sorted list of all defined transport versions

    • isKnown

      public boolean isKnown()
      Returns:
      whether this is a known TransportVersion, i.e. one declared via fromName(String). Other versions may exist in the wild (they're sent over the wire by numeric ID) but we don't know how to communicate using such versions.

    • bestKnownVersion

      public TransportVersion bestKnownVersion()
      Returns:
      the newest known TransportVersion which is no older than this instance. Returns TransportVersion.VersionsHolder.ZERO if there are no such versions.

    • fromString

      public static TransportVersion fromString(String str)

    • isPatchFrom

      public boolean isPatchFrom(TransportVersion version)
      Returns true if this version is a patch version at or after version.

    • supports

      public boolean supports(TransportVersion version)
      Supports is used to determine if a named transport version is supported by a caller transport version. This will check both the latest id and all of its patch ids for compatibility. This replaces the pattern of wireTV.onOrAfter(TV_FEATURE) || wireTV.isPatchFrom(TV_FEATURE_BACKPORT) || ... for unnamed transport versions with wireTV.supports(TV_FEATURE) for named transport versions (since referable versions know about their own patch versions).

      The recommended use of this method is to declare a static final TransportVersion as part of the file that it's used in. This constant is then used in conjunction with this method to check transport version compatability.

      An example: public class ExampleClass { ... TransportVersion TV_FEATURE = TransportVersion.fromName("tv_feature"); ... public static ExampleClass readFrom(InputStream in) { ... if (in.getTransportVersion().supports(TV_FEATURE) { // read newer values } ... } ... public void writeTo(OutputStream out) { ... if (out.getTransportVersion().supports(TV_FEATURE) { // write newer values } ... } ... }

    • toReleaseVersion

      public String toReleaseVersion()
      Returns a string representing the Elasticsearch release version of this transport version, if applicable for this deployment, otherwise the raw version number.

    • equals

      public 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 '=='.
      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.

    • hashCode

      public 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

    • 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

    • name

      public String name()
      Returns the value of the name record component.
      Returns:
      the value of the name record component

    • id

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

    • nextPatchVersion

      public TransportVersion nextPatchVersion()
      Returns the value of the nextPatchVersion record component.
      Returns:
      the value of the nextPatchVersion record component