Versionstamp (FoundationDB Java Client API)

java.lang.Object
- com.apple.foundationdb.tuple.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 and Description

static int LENGTH
Length of a serialized Versionstamp instance when converted into a byte array.

Fields
Modifier and Type	Field and 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 and 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

Class Versionstamp

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

LENGTH

Method Detail

unpackUserVersion

fromBytes

incomplete

incomplete

complete

complete

isComplete

getBytes

getTransactionVersion

getUserVersion

toString

compareTo

equals

hashCode