Package org.opends.server.replication.common

Class CSN

java.lang.Object
org.opends.server.replication.common.CSN
All Implemented Interfaces:
Serializable, Comparable<CSN>
public final class CSN extends Object implements Serializable, Comparable<CSN>
Class used to represent Change Sequence Numbers.
See Also:
  • Inspiration for this class comes from LDAPChangeSequenceNumber

    A CSN has the same internal representation regardless of the version used to encode it. The version is used to ensure compatibility with older servers.

    The CSN external representation depends on the version:

    • Version 1: fixed length, historical: 
      00{rest of the 8 bytes timestamp}{numeric replicaId on two bytes}{seqnum}
    • Version 2: variable length, used from DJ 6.5.0 onwards: 
      01{replicaId length}{timestamp}{seqnum}{string replicaId}
    • Version 3: used in Leader-based replication: 
      02{replicaId length}{streamTimeStamp}{single 0xFF byte}{timestamp}{seqnum}{string replicaId}
    {replicaId length} is encoded on a single byte; each timestamp in V2 and V3 is encoded on 6 bytes, {streamTimeStamp} is encoded on 6 bytes; {seqnum} is always encoded on 4 bytes. The single 0xFF byte in version 3 is used to separate the stream timestamp from the timestamp for debugging purposes.

    The replication stream timestamp, corresponding to the time a stream is created, is an invariant in comparing CSNs, since the CSN timestamp is in itself an absolute time reference, hence the stream timestamp is not used in comparisons nor equality checks.

  • Serialized Form

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    CSN.CsnVersion
    The version of a CSN to ask for a particular representation.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    BYTE_ENCODING_V1_LENGTH
    The number of bytes used by the byte string representation of a change number v1.
    static final long
    MAX_STREAM_SEQ_NUM
    The maximum stream sequence number.
    static final CSN
    MAX_VALUE
    The maximum possible value for a CSN; used for comparisons and initialization, the stream id does not count.
    static final long
    MIN_STREAM_SEQ_NUM
    The minimum stream sequence number.
    static final CSN
    MIN_VALUE
    The minimum possible value for a CSN; used for comparisons and initialization, the stream id does not count.
    static final long
    NO_STREAM
    The has no meaning for this CSN.
    static final long
    NO_STREAM_SEQ_NUM
    The stream sequence number to use when no stream sequence number is needed.
    static final int
    REPLICA_NAME_POSITION_V2
    The position of the replica name in a string representation of a CSN V1 and V2.
    static final int
    REPLICA_NAME_POSITION_V3
    The position of the replica name in a string representation of a CSN V3.
    static final int
    STREAM_SEQNUM_POSITION_V3
    The position of the stream sequence number in a string representation of a CSN V3.
    static final int
    STRING_ENCODING_V1_LENGTH
    The number of characters used by the string representation of a change number v1.

  • Method Summary

    Modifier and Type
    Method
    Description
    static int
    compare(CSN csn1, CSN csn2)
    Compares this CSN with the provided CSN for order and returns a negative number if csn1 is older than csn2, zero if they have the same age, or a positive number if csn1 is newer than csn2.
    int
    compareTo(CSN csn)
    Compares this CSN with the provided CSN for order and returns a negative number if this CSN is older than csn, zero if they have the same age, or a positive number if this CSN is newer than csn.
    boolean
    equals(Object obj)
     
    ReplicaId
    getReplicaId()
    Returns the replica ID.
    int
    getSeqnum()
    Returns the sequence number.
    long
    getStreamSeqNum()
    Returns the stream sequence number.
    long
    getStreamTimeStamp()
    Returns the stream timestamp associated to this CSN in milliseconds.
    long
    getTime()
    Returns the timestamp associated to this CSN in milliseconds.
    long
    getTimeSec()
    Returns the timestamp associated to this CSN in seconds.
    CSN.CsnVersion
    getVersion()
    Returns the CSN version.
    int
    hashCode()
     
    boolean
    isNewerThan(CSN csn)
    Returns true if this CSN is newer than the provided CSN.
    boolean
    isNewerThanOrEqualTo(CSN csn)
    Returns true if this CSN is newer than or equal to the provided CSN.
    boolean
    isOlderThan(CSN csn)
    Returns true if this CSN is older than the provided CSN.
    boolean
    isOlderThanOrEqualTo(CSN csn)
    Returns true if this CSN is older than or equal to the provided CSN.
    boolean
    isOldestCsn(ReplicaId replicaId)
    Returns if this is the oldest possible CSN for a replica.
    static boolean
    isValid(String str)
    Returns true if the provided string can be parsed as a CSN.
    static CSN
    newCsn(long streamTimeStamp, long timeStamp, int seqNum, long streamSeqNum, ReplicaId replicaId)
    Create a new CSN.
    static CSN
    newCsn(long streamTimeStamp, long timeStamp, int seqNum, ReplicaId replicaId)
    Create a new CSN.
    static CSN
    newCsnV1(long timeStamp, int seqNum, int replicaId)
    Create a new CSN.
    static CSN
    newCsnV2(long timeStamp, int seqNum, ReplicaId replicaId)
    Create a new CSN.
    static CSN
    newestCsn(long timeStamp)
    Returns the newest possible CSN for the given time.
    static CSN
    newestCsn(ReplicaId replicaId)
    Returns the newest possible CSN for a replica.
    static CSN
    oldestCsn(long timeStamp)
    Returns the oldest possible CSN for the given time.
    static CSN
    oldestCsn(ReplicaId replicaId)
    Returns the oldest possible CSN for a replica.
    static void
    skipCsn(ByteStringReader reader)
    Advances reading the provided reader to the end of the CSN representation, by skipping over it.
    ByteString
    toByteString()
    Encodes this CSN as a byte string.
    void
    toByteString(ByteStringBuilder builder, CSN.CsnVersion version)
    Encodes this CSN into the provided byte string builder according to the given CSN version.
    ByteString
    toByteString(CSN.CsnVersion version)
    Encodes this CSN as a byte string according to the given CSN version.
    Instant
    toInstant()
    Returns the Instant representing the CSN time.
    JsonValue
    toJson()
    Returns the json representation of this CSN.
    String
    toString()
    Convert the CSN to a printable String.
    String
    toString(CSN.CsnVersion version)
    Convert the CSN to a printable String according to the given CSN version.
    String
    toStringUI()
    Convert the CSN to a printable String with a user friendly format.
    static CSN
    valueOf(String str)
    Parses the provided toString() representation of a CSN.
    static CSN
    valueOf(ByteString bs)
    Decodes the provided toByteString(CsnVersion) representation of a CSN.
    static CSN
    valueOf(ByteStringReader reader)
    Decodes the provided toByteString(CsnVersion) representation of a CSN, possibly embedded in a larger sequence.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • BYTE_ENCODING_V1_LENGTH

      public static final int BYTE_ENCODING_V1_LENGTH
      The number of bytes used by the byte string representation of a change number v1.
      See Also:

    • STRING_ENCODING_V1_LENGTH

      public static final int STRING_ENCODING_V1_LENGTH
      The number of characters used by the string representation of a change number v1.
      See Also:

    • REPLICA_NAME_POSITION_V2

      public static final int REPLICA_NAME_POSITION_V2
      The position of the replica name in a string representation of a CSN V1 and V2.
      See Also:

    • STREAM_SEQNUM_POSITION_V3

      public static final int STREAM_SEQNUM_POSITION_V3
      The position of the stream sequence number in a string representation of a CSN V3.
      See Also:

    • REPLICA_NAME_POSITION_V3

      public static final int REPLICA_NAME_POSITION_V3
      The position of the replica name in a string representation of a CSN V3.
      See Also:

    • NO_STREAM

      public static final long NO_STREAM
      The has no meaning for this CSN.
      See Also:

    • NO_STREAM_SEQ_NUM

      public static final long NO_STREAM_SEQ_NUM
      The stream sequence number to use when no stream sequence number is needed.
      See Also:

    • MIN_STREAM_SEQ_NUM

      public static final long MIN_STREAM_SEQ_NUM
      The minimum stream sequence number.
      See Also:

    • MAX_STREAM_SEQ_NUM

      public static final long MAX_STREAM_SEQ_NUM
      The maximum stream sequence number.
      See Also:

    • MIN_VALUE

      public static final CSN MIN_VALUE
      The minimum possible value for a CSN; used for comparisons and initialization, the stream id does not count.

    • MAX_VALUE

      public static final CSN MAX_VALUE
      The maximum possible value for a CSN; used for comparisons and initialization, the stream id does not count.

  • Method Details

    • isValid

      public static boolean isValid(String str)
      Returns true if the provided string can be parsed as a CSN.
      Parameters:
      str - the CSN
      Returns:
      true if the provided string can be parsed as a CSN

    • valueOf

      public static CSN valueOf(String str)
      Parses the provided toString() representation of a CSN.
      Parameters:
      str - The string to be parsed.
      Returns:
      The parsed CSN.
      See Also:

    • valueOf

      public static CSN valueOf(ByteString bs)
      Decodes the provided toByteString(CsnVersion) representation of a CSN.
      Parameters:
      bs - The byte string to be parsed.
      Returns:
      The decoded CSN.
      See Also:

    • valueOf

      public static CSN valueOf(ByteStringReader reader)
      Decodes the provided toByteString(CsnVersion) representation of a CSN, possibly embedded in a larger sequence.
      Parameters:
      reader - The reader of the byte string to be parsed.
      Returns:
      The decoded CSN.

    • skipCsn

      public static void skipCsn(ByteStringReader reader)
      Advances reading the provided reader to the end of the CSN representation, by skipping over it.
      Parameters:
      reader - The reader to advance

    • newCsnV1

      public static CSN newCsnV1(long timeStamp, int seqNum, int replicaId)
      Create a new CSN.
      Parameters:
      timeStamp - timeStamp for the CSN
      seqNum - sequence number
      replicaId - identity of replica
      Returns:
      a new CSN

    • newCsnV2

      public static CSN newCsnV2(long timeStamp, int seqNum, ReplicaId replicaId)
      Create a new CSN.
      Parameters:
      timeStamp - timeStamp for the CSN
      seqNum - sequence number
      replicaId - identity of replica
      Returns:
      a new CSN

    • newCsn

      public static CSN newCsn(long streamTimeStamp, long timeStamp, int seqNum, ReplicaId replicaId)
      Create a new CSN.
      Parameters:
      streamTimeStamp - the stream timestamp
      timeStamp - the timestamp for the CSN
      seqNum - sequence number
      replicaId - identity of replica
      Returns:
      a new CSN

    • newCsn

      public static CSN newCsn(long streamTimeStamp, long timeStamp, int seqNum, long streamSeqNum, ReplicaId replicaId)
      Create a new CSN.
      Parameters:
      streamTimeStamp - the stream timestamp
      timeStamp - the timestamp for the CSN
      seqNum - sequence number
      streamSeqNum - stream sequence number
      replicaId - identity of replica
      Returns:
      a new CSN

    • getVersion

      public CSN.CsnVersion getVersion()
      Returns the CSN version.
      Returns:
      the CSN version

    • getTime

      public long getTime()
      Returns the timestamp associated to this CSN in milliseconds.
      Returns:
      the timestamp associated to this CSN in milliseconds

    • getTimeSec

      public long getTimeSec()
      Returns the timestamp associated to this CSN in seconds.
      Returns:
      the timestamp associated to this CSN in seconds

    • getStreamTimeStamp

      public long getStreamTimeStamp()
      Returns the stream timestamp associated to this CSN in milliseconds.
      Returns:
      the stream timestamp associated to this CSN in milliseconds

    • getSeqnum

      public int getSeqnum()
      Returns the sequence number.
      Returns:
      the sequence number

    • getStreamSeqNum

      public long getStreamSeqNum()
      Returns the stream sequence number.
      Returns:
      the stream sequence number

    • getReplicaId

      public ReplicaId getReplicaId()
      Returns the replica ID.
      Returns:
      the replica ID

    • equals

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

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toByteString

      public ByteString toByteString()
      Encodes this CSN as a byte string.

      The returned representation is according to the most recent CSN version. Use toByteString(CsnVersion) to get a representation compatible with earlier protocol versions.

      Returns:
      The encoded representation of this CSN.
      See Also:

    • toByteString

      public ByteString toByteString(CSN.CsnVersion version)
      Encodes this CSN as a byte string according to the given CSN version.
      Parameters:
      version - The required representation version
      Returns:
      The encoded representation of this CSN.

    • toByteString

      public void toByteString(ByteStringBuilder builder, CSN.CsnVersion version)
      Encodes this CSN into the provided byte string builder according to the given CSN version.
      Parameters:
      builder - The byte string builder.
      version - The required representation version
      See Also:

    • toString

      public String toString()
      Convert the CSN to a printable String.

      The returned representation is according to the most recent CSN version. Use toString(CsnVersion) to get a representation compatible with earlier protocol versions.

      Overrides:
      toString in class Object
      Returns:
      the string

    • toString

      public String toString(CSN.CsnVersion version)
      Convert the CSN to a printable String according to the given CSN version.
      Parameters:
      version - The required representation version
      Returns:
      the string

    • toStringUI

      public String toStringUI()
      Convert the CSN to a printable String with a user friendly format.
      Returns:
      the string

    • compare

      public static int compare(CSN csn1, CSN csn2)
      Compares this CSN with the provided CSN for order and returns a negative number if csn1 is older than csn2, zero if they have the same age, or a positive number if csn1 is newer than csn2.
      Parameters:
      csn1 - The first CSN to be compared, which may be null.
      csn2 - The second CSN to be compared, which may be null.
      Returns:
      A negative number if csn1 is older than csn2, zero if they have the same age, or a positive number if csn1 is newer than csn2.

    • isOlderThan

      public boolean isOlderThan(CSN csn)
      Returns true if this CSN is older than the provided CSN.
      Parameters:
      csn - The CSN to be compared
      Returns:
      true if this CSN is older than the provided CSN

    • isOlderThanOrEqualTo

      public boolean isOlderThanOrEqualTo(CSN csn)
      Returns true if this CSN is older than or equal to the provided CSN.
      Parameters:
      csn - The CSN to be compared
      Returns:
      true if this CSN is older than or equal to the provided CSN

    • isNewerThanOrEqualTo

      public boolean isNewerThanOrEqualTo(CSN csn)
      Returns true if this CSN is newer than or equal to the provided CSN.
      Parameters:
      csn - The CSN to be compared
      Returns:
      true if this CSN is newer than or equal to the provided CSN

    • isNewerThan

      public boolean isNewerThan(CSN csn)
      Returns true if this CSN is newer than the provided CSN.
      Parameters:
      csn - The CSN to be compared
      Returns:
      true if this CSN is newer than the provided CSN

    • compareTo

      public int compareTo(CSN csn)
      Compares this CSN with the provided CSN for order and returns a negative number if this CSN is older than csn, zero if they have the same age, or a positive number if this CSN is newer than csn.
      Specified by:
      compareTo in interface Comparable<CSN>
      Parameters:
      csn - The CSN to be compared.
      Returns:
      A negative number if this CSN is older than csn, zero if they have the same age, or a positive number if this CSN is newer than csn.

    • toInstant

      public Instant toInstant()
      Returns the Instant representing the CSN time.
      Returns:
      the Instant representing the CSN time

    • oldestCsn

      public static CSN oldestCsn(long timeStamp)
      Returns the oldest possible CSN for the given time.
      Parameters:
      timeStamp - the time of the CSN
      Returns:
      the oldest possible CSN for the given time

    • oldestCsn

      public static CSN oldestCsn(ReplicaId replicaId)
      Returns the oldest possible CSN for a replica.
      Parameters:
      replicaId - the replica
      Returns:
      the oldest possible CSN for a replica

    • isOldestCsn

      public boolean isOldestCsn(ReplicaId replicaId)
      Returns if this is the oldest possible CSN for a replica.
      Parameters:
      replicaId - the replica
      Returns:
      if this is the oldest possible CSN for a replica

    • newestCsn

      public static CSN newestCsn(long timeStamp)
      Returns the newest possible CSN for the given time.
      Parameters:
      timeStamp - the time of the CSN
      Returns:
      the newest possible CSN for the given time

    • newestCsn

      public static CSN newestCsn(ReplicaId replicaId)
      Returns the newest possible CSN for a replica.
      Parameters:
      replicaId - the replica
      Returns:
      the newest possible CSN for a replica

    • toJson

      public JsonValue toJson()
      Returns the json representation of this CSN.
      Returns:
      the json representation of this CSN