- All Implemented Interfaces:
Comparable<TransportVersion>
,VersionId<TransportVersion>
Note: We are currently transitioning to a file-based system to load and maintain transport versions. These file-based transport
versions are named and are referred to as named transport versions. Named transport versions also maintain a linked list of their
own patch versions to simplify transport version compatibility checks. Transport versions that continue to be loaded through
TransportVersions
are referred to as unnamed transport versions. Unnamed transport versions will continue being used
over the wire as we only need the id for compatibility checks even against named transport versions. There are changes
throughout TransportVersion
that are for this transition. For now, continue to use the existing system of adding unnamed
transport versions to TransportVersions
.
Prior to 8.8.0, the release Version
was used everywhere. This class separates the wire protocol version from the release version.
Each transport version constant has an id number, which for versions prior to 8.9.0 is the same as the release version for backwards compatibility. In 8.9.0 this is changed to an incrementing number, disconnected from the release version.
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 transport version, the different unique ids cause a git conflict, ensuring that 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 transport version being used across multiple commits, causing problems when you try to upgrade between those two merged commits.
Version compatibility
The earliest compatible version is hardcoded in theTransportVersion.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 Summary
ConstructorsConstructorDescriptionTransportVersion
(int id) Constructs an unnamed transport version.TransportVersion
(String name, int id, TransportVersion nextPatchVersion) Creates an instance of aTransportVersion
record class. -
Method Summary
Modifier and TypeMethodDescriptionstatic List
<TransportVersion> collectFromInputStreams
(String component, String resourceRoot, Function<String, InputStream> resourceLoader, String upperBoundFileName) static TransportVersion
current()
Reference to the most recent transport version.boolean
Indicates whether some other object is "equal to" this one.static TransportVersion
fromBufferedReader
(String component, String path, boolean nameInFile, boolean isNamed, BufferedReader bufferedReader, Integer upperBound) Constructs a named transport version along with its set of compatible patch versions from x-content.static TransportVersion
fromId
(int id) Finds aTransportVersion
by its id.static TransportVersion
Finds aTransportVersion
by its name.static TransportVersion
fromString
(String str) static List
<TransportVersion> Sorted list of all defined transport versionsint
hashCode()
Returns a hash code value for this object.int
id()
Returns the value of theid
record component.static boolean
isCompatible
(TransportVersion version) Returnstrue
if the specified version is compatible with this running version of Elasticsearch.boolean
isKnown()
boolean
isPatchFrom
(TransportVersion version) Returnstrue
if this version is a patch version at or afterversion
.static TransportVersion
max
(TransportVersion version1, TransportVersion version2) Returns the maximum version ofversion1
andversion2
static TransportVersion
min
(TransportVersion version1, TransportVersion version2) Returns the minimum version ofversion1
andversion2
static TransportVersion
Reference to the minimum transport version that can be used with CCS.static TransportVersion
Reference to the earliest compatible transport version to this version of the codebase.name()
Returns the value of thename
record component.Returns the value of thenextPatchVersion
record component.static TransportVersion
boolean
supports
(TransportVersion version) Supports is used to determine if a named transport version is supported by a caller transport version.Returns a string representing the Elasticsearch release version of this transport version, if applicable for this deployment, otherwise the raw version number.toString()
Returns a string representation of this record class.static void
writeVersion
(TransportVersion version, StreamOutput out) static TransportVersion
zero()
Sentinel value for lowest possible transport version
-
Constructor Details
-
TransportVersion
public TransportVersion(int id) Constructs an unnamed transport version. -
TransportVersion
Creates an instance of aTransportVersion
record class.- Parameters:
name
- the value for thename
record componentid
- the value for theid
record componentnextPatchVersion
- the value for thenextPatchVersion
record component
-
-
Method Details
-
fromBufferedReader
public static TransportVersion fromBufferedReader(String component, String path, boolean nameInFile, boolean isNamed, BufferedReader bufferedReader, Integer upperBound) Constructs a named transport version along with its set of compatible patch versions from x-content. This method takes in the parameterupperBound
which is the highest transport version id that will be loaded by this node. -
collectFromInputStreams
public static List<TransportVersion> collectFromInputStreams(String component, String resourceRoot, Function<String, InputStream> resourceLoader, String upperBoundFileName) -
readVersion
- Throws:
IOException
-
fromId
Finds aTransportVersion
by its id. If a transport version with the specified ID does not exist, this method creates and returns a new instance ofTransportVersion
with the specified ID. The new instance is not registered inTransportVersion.getAllVersions
. -
fromName
Finds aTransportVersion
by its name. The parametername
must be aString
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
- Throws:
IOException
-
min
Returns the minimum version ofversion1
andversion2
-
max
Returns the maximum version ofversion1
andversion2
-
isCompatible
Returnstrue
if the specified version is compatible with this running version of Elasticsearch. -
current
Reference to the most recent transport version. This should be the transport version with the highest id. -
zero
Sentinel value for lowest possible transport version -
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
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
Sorted list of all defined transport versions -
isKnown
public boolean isKnown()- Returns:
- whether this is a known
TransportVersion
, i.e. one declared inTransportVersions
. 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
- Returns:
- the newest known
TransportVersion
which is no older than this instance. ReturnsTransportVersion.VersionsHolder.ZERO
if there are no such versions.
-
fromString
-
isPatchFrom
Returnstrue
if this version is a patch version at or afterversion
.This should not be used normally. It is used for matching patch versions of the same base version, using the standard version number format specified in
TransportVersions
. When a patch version of an existing transport version is created,transportVersion.isPatchFrom(patchVersion)
will match any transport version at or abovepatchVersion
that is also of the same base version.For example,
version.isPatchFrom(8_800_0_04)
will return the following for the givenversion
:8_799_0_00.isPatchFrom(8_800_0_04)
:false
8_799_0_09.isPatchFrom(8_800_0_04)
:false
8_800_0_00.isPatchFrom(8_800_0_04)
:false
8_800_0_03.isPatchFrom(8_800_0_04)
:false
8_800_0_04.isPatchFrom(8_800_0_04)
:true
8_800_0_49.isPatchFrom(8_800_0_04)
:true
8_800_1_00.isPatchFrom(8_800_0_04)
:false
8_801_0_00.isPatchFrom(8_800_0_04)
:false
-
supports
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 ofwireTV.onOrAfter(TV_FEATURE) || wireTV.isPatchFrom(TV_FEATURE_BACKPORT) || ...
for unnamed transport versions withwireTV.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
Returns a string representing the Elasticsearch release version of this transport version, if applicable for this deployment, otherwise the raw version number. -
equals
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 withObjects::equals(Object,Object)
; primitive components are compared with '=='. -
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. -
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. -
name
Returns the value of thename
record component.- Returns:
- the value of the
name
record component
-
id
public int id()Returns the value of theid
record component.- Specified by:
id
in interfaceVersionId<TransportVersion>
- Returns:
- the value of the
id
record component
-
nextPatchVersion
Returns the value of thenextPatchVersion
record component.- Returns:
- the value of the
nextPatchVersion
record component
-