Class Versionstamp

  • All Implemented Interfaces:
    java.lang.Comparable<Versionstamp>

    public class Versionstamp
    extends java.lang.Object
    implements java.lang.Comparable<Versionstamp>
    Used to represent values written by versionstamp operations with a Tuple. This wraps a single array which should contain twelve bytes. The first ten bytes are the "transaction" version, and they are usually assigned by the database in such a way that all transactions receive a different version that is consistent with a serialization order of the transactions within the database. (One can use the Transaction.getVersionstamp() method to retrieve this version from a Transaction.) This also implies that the transaction version of newly committed transactions will be monotonically increasing over time. The final two bytes are the "user" version and should be set by the client. This allows the user to use this class to impose a total order of items across multiple transactions in the database in a consistent and conflict-free way. The user can elect to ignore this parameter by instantiating the class with the paramaterless incomplete() and one-parameter complete static initializers. If they do so, then versions are written with a default (constant) user version.

    All Versionstamps can exist in one of two states: "incomplete" and "complete". An "incomplete" Versionstamp is a Versionstamp that has not been initialized with a meaningful transaction version. For example, this might be used with a Versionstamp that one wants to fill in with the current transaction's version information. A "complete" Versionstamp, in contradistinction, is one that has been assigned a meaningful transaction version. This is usually the case if one is reading back a Versionstamp from the database.

    Example usage might be to do something like the following:

     
      CompletableFuture<byte[]> trVersionFuture = db.run((Transaction tr) -> {
           // The incomplete Versionstamp will be overwritten with tr's version information when committed.
           Tuple t = Tuple.from("prefix", Versionstamp.incomplete());
           tr.mutate(MutationType.SET_VERSIONSTAMPED_KEY, t.packWithVersionstamp(), new byte[0]);
           return tr.getVersionstamp();
       });
    
       byte[] trVersion = trVersionFuture.get();
    
       Versionstamp v = db.run((Transaction tr) -> {
           Subspace subspace = new Subspace(Tuple.from("prefix"));
           byte[] serialized = tr.getRange(subspace.range(), 1).iterator().next().getKey();
           Tuple t = subspace.unpack(serialized);
           return t.getVersionstamp(0);
       });
    
       assert v.equals(Versionstamp.complete(trVersion));
     
     

    Here, an incomplete Versionstamp is packed and written to the database with the SET_VERSIONSTAMPED_KEY MutationType. After committing, we then attempt to read back the same key that we just wrote. Then we verify the invariant that the deserialized Versionstamp is the same as a complete Versionstamp instance created from the first transaction's version information.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int LENGTH
      Length of a serialized Versionstamp instance when converted into a byte array.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int compareTo​(Versionstamp other)
      Compares two Versionstamp instances in a manner consistent with their key order when serialized in the database as keys.
      static Versionstamp complete​(byte[] trVersion)
      Creates a complete Versionstamp instance with the given transaction and default user versions.
      static Versionstamp complete​(byte[] trVersion, int userVersion)
      Creates a complete Versionstamp instance with the given transaction and user versions.
      boolean equals​(java.lang.Object o)
      Check another object for equality.
      static Versionstamp fromBytes​(byte[] versionBytes)
      Creates a Versionstamp instance based on the given byte array representation.
      byte[] getBytes()
      Retrieve a byte-array representation of this Versionstamp.
      byte[] getTransactionVersion()
      Retrieve the portion of this Versionstamp that is set by the database.
      int getUserVersion()
      Retrieve the portion of this Versionstamp that is set by the user.
      int hashCode()
      Hash code for this Versionstamp.
      static Versionstamp incomplete()
      Creates an incomplete Versionstamp instance with the default user version.
      static Versionstamp incomplete​(int userVersion)
      Creates an incomplete Versionstamp instance with the given user version.
      boolean isComplete()
      Whether this Versionstamp's transaction version is meaningful.
      java.lang.String toString()
      Generate a human-readable representation of this Versionstamp.
      static int unpackUserVersion​(byte[] bytes, int pos)
      From a byte array, unpack the user version starting at the given position.
      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • LENGTH

        public static final int LENGTH
        Length of a serialized Versionstamp instance when converted into a byte array.
        See Also:
        Constant Field Values
    • Method Detail

      • unpackUserVersion

        public static int unpackUserVersion​(byte[] bytes,
                                            int pos)
        From a byte array, unpack the user version starting at the given position. This assumes that the bytes are stored in big-endian order as an unsigned short, which is the way the user version is serialized in packed Versionstamps.
        Parameters:
        bytes - byte array including user version
        pos - starting position of user version
        Returns:
        the unpacked user version included in the array
      • fromBytes

        public static Versionstamp fromBytes​(byte[] versionBytes)
        Creates a Versionstamp instance based on the given byte array representation. This follows the same format as that used by the main constructor, but the completeness of the Versionstamp is instead automatically determined by comparing its transaction version with the value used to indicate an unset transaction version.
        Parameters:
        versionBytes - byte array representation of Versionstamp
        Returns:
        equivalent instantiated Versionstamp object
      • incomplete

        public static Versionstamp incomplete​(int userVersion)
        Creates an incomplete Versionstamp instance with the given user version. The provided user version must fit within an unsigned short. When converted into a byte array, the bytes for the transaction version will be filled in with dummy bytes to be later filled in at transaction commit time.
        Parameters:
        userVersion - intra-transaction portion of version (set by user code)
        Returns:
        an incomplete Versionstamp with the given user version
      • incomplete

        public static Versionstamp incomplete()
        Creates an incomplete Versionstamp instance with the default user version. When converted into a byte array, the bytes for the transaction version will be filled in with dummy bytes to be later filled in at transaction commit time. If multiple keys are created using the returned Versionstamp within the same transaction, then all of those keys will have the same version, but it will provide an ordering between different transactions if that is all that is required.
        Returns:
        an incomplete Versionstamp with the default user version
      • complete

        public static Versionstamp complete​(byte[] trVersion,
                                            int userVersion)
        Creates a complete Versionstamp instance with the given transaction and user versions. The provided transaction version must have exactly 10 bytes, and the user version must fit within an unsigned short.
        Parameters:
        trVersion - inter-transaction portion of version (set by the database)
        userVersion - intra-transaction portion of version (set by user code)
        Returns:
        a complete Versionstamp assembled from the given parts
      • complete

        public static Versionstamp complete​(byte[] trVersion)
        Creates a complete Versionstamp instance with the given transaction and default user versions. The provided transaction version must have exactly 10 bytes.
        Parameters:
        trVersion - inter-transaction portion of version (set by the database)
        Returns:
        a complete Versionstamp assembled from the given transaction version and the default user version
      • isComplete

        public boolean isComplete()
        Whether this Versionstamp's transaction version is meaningful. The database will assign each transaction a different transaction version. A Versionstamp is considered to be "complete" if its transaction version is one of those database-assigned versions rather than just dummy bytes. If one uses this class with our SET_VERSIONSTAMPED_KEY mutation, then the appropriate bytes will be filled in within the database during a successful commit.
        Returns:
        whether the transaction version has been set
      • getBytes

        public byte[] getBytes()
        Retrieve a byte-array representation of this Versionstamp. This representation can then be serialized and added to the database. If this Versionstamp is not complete, the first 10 bytes (representing the transaction version) will not be meaningful and one should probably use with the SET_VERSIONSTAMPED_KEY mutation. Warning: For performance reasons, this method does not create a copy of its underlying data array. As a result, it is dangerous to modify the return value of this function.
        Returns:
        byte representation of this Versionstamp
      • getTransactionVersion

        public byte[] getTransactionVersion()
        Retrieve the portion of this Versionstamp that is set by the database. These 10 bytes are what provide an ordering between different commits.
        Returns:
        transaction version of this Versionstamp
      • getUserVersion

        public int getUserVersion()
        Retrieve the portion of this Versionstamp that is set by the user. This integer is what provides an ordering within a single commit.
        Returns:
        user version of this Versionstamp
      • toString

        public java.lang.String toString()
        Generate a human-readable representation of this Versionstamp. It contains information as to whether this Versionstamp is incomplete or not, what its transaction version is (if the Versionstamp is complete), and what its user version is.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a human-readable representation of this Versionstamp
      • compareTo

        public int compareTo​(Versionstamp other)
        Compares two Versionstamp instances in a manner consistent with their key order when serialized in the database as keys. The rules for comparison are:
        • All complete Versionstamps sort before incomplete Versionstamps
        • Two complete Versionstamps will sort based on unsigned lexicographic comparison of their byte representations.
        • Two incomplete Versionstamps will sort based on their user versions.
        Specified by:
        compareTo in interface java.lang.Comparable<Versionstamp>
        Parameters:
        other - Versionstamp instance to compare against
        Returns:
        -1 if this Versionstamp is smaller than other, 1 if it is bigger, and 0 if it is equal
      • equals

        public boolean equals​(java.lang.Object o)
        Check another object for equality. This will return true if and only if the o parameter is of type Versionstamp and has the same completion status and byte representation.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - object to compare for equality
        Returns:
        whether the passed object is an equivalent Versionstamp
      • hashCode

        public int hashCode()
        Hash code for this Versionstamp. It is based off of the hash code for the underlying data array.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        hash-table compliant hash code for this instance