com.apple.foundationdb.record.provider.foundationdb

Class FDBRecordVersion

java.lang.Object

com.apple.foundationdb.record.provider.foundationdb.FDBRecordVersion

All Implemented Interfaces:

Comparable<FDBRecordVersion>

@API(value=MAINTAINED)
public class FDBRecordVersion
extends Object
implements Comparable<FDBRecordVersion>

Class representing a specific version within FDB. This is designed to inter-operate with the Versionstamp class used to serialize versions within FoundationDB. The version consists of two parts: a global version and a local version. The global version is a 10 byte version that is usually set by the database, and it should be used to impose an ordering between different transactions. The local version should be set by the user instead, and it should be used to impose an order on different records within a single transaction. Together, this two versions are combined into a 12 byte array that can be used to impose a total order across all records.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	FDBRecordVersion.IncompleteRecordVersionException Exception that can be thrown if one tries to get the global version associated with a version whose global version has not yet been set.

Field Summary

Fields

Modifier and Type	Field and Description
static int	GLOBAL_VERSION_LENGTH Length of the global versions used by FDBRecordVersion.
static FDBRecordVersion	MAX_VERSION Maximum possible complete FDBRecordVersion value.
static FDBRecordVersion	MIN_VERSION Minimum possible complete FDBRecordVersion value.
static int	VERSION_LENGTH Length of the underlying byte array representation of an FDBRecordVersion.

Method Summary

Modifier and Type	Method and Description
int	compareTo(FDBRecordVersion other) Compares two different record versions.
static FDBRecordVersion	complete(byte[] versionBytes) Create a FDBRecordVersion that is complete and has the given serialized bytes.
static FDBRecordVersion	complete(byte[] versionBytes, boolean copy) Create a FDBRecordVersion that is complete and has the given serialized bytes.
static FDBRecordVersion	complete(byte[] globalVersion, int localVersion) Create a FDBRecordVersion that is complete and has the given global and local versions.
boolean	equals(Object o) Whether this FDBRecordVersion mathces the given object.
static FDBRecordVersion	firstInDBVersion(long dbVersion) Return the first FDBRecordVersion that could be written at a given database version or later.
static FDBRecordVersion	firstInGlobalVersion(byte[] globalVersion) Return the first FDBRecordVersion that could be written at the given global version.
static FDBRecordVersion	fromBytes(byte[] versionBytes) Create a FDBRecordVersion from the given serialized bytes.
static FDBRecordVersion	fromBytes(byte[] versionBytes, boolean copy) Create a FDBRecordVersion from the given serialized bytes.
static FDBRecordVersion	fromVersionstamp(Versionstamp versionstamp) Create a FDBRecordVersion from the given Versionstamp instance.
static FDBRecordVersion	fromVersionstamp(Versionstamp versionstamp, boolean copy) Create a FDBRecordVersion from the given Versionstamp instance.
long	getDBVersion() Retrieves the part of the version that corresponds to the database commit version.
byte[]	getGlobalVersion() Retrieves the part of the version that is set by the database.
int	getLocalVersion() Retrieves the part of the version that is set within a single FDBRecordContext.
int	hashCode() Hash code derived from the local and global version hash codes.
static FDBRecordVersion	incomplete(int localVersion) Create a FDBRecordVersion that is incomplete and has the given local version.
boolean	isComplete() Whether this version has all of its relevant data set.
static FDBRecordVersion	lastInDBVersion(long dbVersion) Returns the last FDBRecordVersion that could have been written at the given database version.
static FDBRecordVersion	lastInGlobalVersion(byte[] globalVersion) Return the last FDBRecordVersion that could be written at the given global version.
FDBRecordVersion	next() Returns an incremented version of the current FDBRecordVersion.
FDBRecordVersion	prev() Returns a decremented version of the current FDBRecordVersion.
byte[]	toBytes() Serializes the version information to a byte array.
byte[]	toBytes(boolean copy) Serializes the version information to a byte array.
String	toString() Human-readable representation of this FDBRecordVersion.
Versionstamp	toVersionstamp() Converts this RecordVersion instance to a Versionstamp instance.
Versionstamp	toVersionstamp(boolean copy) Converts this RecordVersion instance to a Versionstamp instance.
FDBRecordVersion	withCommittedVersion(byte[] committedVersion) Complete this version with the version from as successful commit.
int	writeTo(byte[] bytes) Write the serialized version to the beginning of the given byte array.
int	writeTo(byte[] bytes, int offset) Write the serialized version to a specified offset within the given byte array.
ByteBuffer	writeTo(ByteBuffer buffer) Write the serialized version information to the end of a ByteBuffer.

Methods inherited from class java.lang.Object

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

Field Detail

GLOBAL_VERSION_LENGTH

public static final int GLOBAL_VERSION_LENGTH

Length of the global versions used by FDBRecordVersion.

See Also:

Constant Field Values

VERSION_LENGTH

public static final int VERSION_LENGTH

Length of the underlying byte array representation of an FDBRecordVersion.

See Also:

Constant Field Values

MIN_VERSION

public static final FDBRecordVersion MIN_VERSION

Minimum possible complete FDBRecordVersion value.

MAX_VERSION

public static final FDBRecordVersion MAX_VERSION

Maximum possible complete FDBRecordVersion value.

Method Detail

complete

@Nonnull
public static FDBRecordVersion complete(@Nonnull
                                                 byte[] globalVersion,
                                                 int localVersion)

Create a FDBRecordVersion that is complete and has the given global and local versions. It can then be serialized into bytes by combining these bytes in the appropriate way.

Parameters:

globalVersion - the global version associated with this version

localVersion - the local version associated with this version

Returns:

a new complete FDBRecordVersion

complete

@Nonnull
public static FDBRecordVersion complete(@Nonnull
                                                 byte[] versionBytes)

Create a FDBRecordVersion that is complete and has the given serialized bytes. The given bytes should contain both the global version and the local version. Also, bytes will be copied (by default) from the given array when the final object is created. To disable this behavior, consider using the the other version of the complete static initializer that takes a byte array and a boolean.

Parameters:

versionBytes - the byte representation of a version

Returns:

a version object wrapping the given bytes

complete

@Nonnull
public static FDBRecordVersion complete(@Nonnull
                                                 byte[] versionBytes,
                                                 boolean copy)

Create a FDBRecordVersion that is complete and has the given serialized bytes. The given bytes should contain both the global and the local version. If the copy parameter is set to false, then the new object will use the exact same array as is passed in without copying it. This is unsafe if the array is later modified by something else, so it should only be set to false if one knows that that won't happen.

Parameters:

versionBytes - the byte representation of a version

copy - whether to copy the array for the new FDBRecordVersion

Returns:

a version object wrapping the given bytes

incomplete

@Nonnull
public static FDBRecordVersion incomplete(int localVersion)

Create a FDBRecordVersion that is incomplete and has the given local version. After it is serialized, something else will have to make it sure it gets a global version.

Parameters:

localVersion - the local version associated with this version

Returns:

a new incomplete FDBRecordVersion

fromBytes

@Nonnull
public static FDBRecordVersion fromBytes(@Nonnull
                                                  byte[] versionBytes)

Create a FDBRecordVersion from the given serialized bytes. The given bytes should contain both the global and local version. Unlike complete, this does not assume that the array represents a complete version, and it will create an incomplete version if the global version is set to all 0xff bytes. This method will make a copy of the given array when constituting the new object. To disable this behavior, consider using the version of the fromBytes static initializer that takes a byte array and a boolean as parameters.

Parameters:

versionBytes - the byte representation of a version

Returns:

a version object wrapping the given bytes

fromBytes

@Nonnull
public static FDBRecordVersion fromBytes(@Nonnull
                                                  byte[] versionBytes,
                                                  boolean copy)

Create a FDBRecordVersion from the given serialized bytes. The given bytes should contain both the global and local version. Unlike complete, this does not assume that the array represents a complete version, and it will create an incomplete version if the global version is set to all 0xff bytes. If the copy parameter is set to false, the new object will use the exact same array as is passed in without copying it. This is unsafe if the array is later modified by something else, so it should only be set if one knows that that won't happen.

Parameters:

versionBytes - the byte representation of a version

copy - whether to copy the array for the new FDBRecordVersion

Returns:

a version object wrapping the given bytes

fromVersionstamp

@Nonnull
public static FDBRecordVersion fromVersionstamp(@Nonnull
                                                         Versionstamp versionstamp)

Create a FDBRecordVersion from the given Versionstamp instance. The Versionstamp class handles version information one layer closer the FoundationDB cluster, and it contains much the same information as this class, so this allows for conversion from that class to this one. By default, this will copy all of the underlying data rather than reusing the same arrays. If one wishes to override this behavior, one should use the version of the fromVersionstamp static initializer that takes a boolean.

Parameters:

versionstamp - Versionstamp instance to convert

Returns:

a FDBRecordVersion with equivalent information

fromVersionstamp

@Nonnull
public static FDBRecordVersion fromVersionstamp(@Nonnull
                                                         Versionstamp versionstamp,
                                                         boolean copy)

Create a FDBRecordVersion from the given Versionstamp instance. The Versionstamp class handles version information one layer closer the FoundationDB cluster, and it contains much the same information as this class, so this allows for conversion from that class to this one. If the copy parameter is set to false, it will reuse the same underlying array used by the Versionstamp class rather than making its own. This is unsafe if the array is modified later, so it should only be set to false if one knows that that won't happen.

Parameters:

versionstamp - Versionstamp instance to convert

copy - whether to copy the underlying array for the new FDBRecordVersion

Returns:

a FDBRecordVersion with equivalent information

firstInDBVersion

@Nonnull
public static FDBRecordVersion firstInDBVersion(long dbVersion)

Return the first FDBRecordVersion that could be written at a given database version or later. The database version referred to here is the eight byte unsigned version that FoundationDB uses to track changes and maintain consistency.

Parameters:

dbVersion - the database version to base this FDBRecordVersion on

Returns:

the first version possibly written at this database version or newer

firstInGlobalVersion

public static FDBRecordVersion firstInGlobalVersion(@Nonnull
                                                    byte[] globalVersion)

Return the first FDBRecordVersion that could be written at the given global version.

Parameters:

globalVersion - the global version of the new version

Returns:

the first version possibly written at the given global version or newer

lastInDBVersion

public static FDBRecordVersion lastInDBVersion(long dbVersion)

Returns the last FDBRecordVersion that could have been written at the given database version. The database version referred to here is the eight byte unsigned version that FoundationDB uses to track changes and maintain consistency.

Parameters:

dbVersion - the database version to base this FDBRecordVersion on

Returns:

the last version possibly written at this database version or older

lastInGlobalVersion

public static FDBRecordVersion lastInGlobalVersion(@Nonnull
                                                   byte[] globalVersion)

Return the last FDBRecordVersion that could be written at the given global version.

Parameters:

globalVersion - the global version of the new version

Returns:

the last version possibly written at the given global version or older

toVersionstamp

@Nonnull
public Versionstamp toVersionstamp()

Converts this RecordVersion instance to a Versionstamp instance. That type is safe to serialize within Tuples. By default, it will copy the underlying data arrays when making the new object. If one wishes to disable this behavior, one should consider using the version of toVersionstamp that takes a boolean as an argument.

Returns:

Versionstamp representation of this version

toVersionstamp

@Nonnull
public Versionstamp toVersionstamp(boolean copy)

Converts this RecordVersion instance to a Versionstamp instance. That type is safe to serialize within Tuples. If the copy parameter is set to false, then the new Versionstamp will use the same underlying data arrays as this RecordVersion instance. This is only safe if that array is never modified by something else, so it should only be set if one knows that that won't happen.

Parameters:

copy - whether to copy the underlying data arrays for the new instance

Returns:

Versionstamp representation of this version

toBytes

@Nonnull
public byte[] toBytes()

Serializes the version information to a byte array. This array should be used to represent the version within the database. In the case that the version is incomplete, the values within the byte array will not be meaningful except that the last two bytes will represent the local version. By default, this will return a copy of the serialized array from the one used internally by the object, but if one wishes to disable this, consider using the version of toBytes that takes a boolean as a parameter.

Returns:

byte representation of this version

toBytes

@Nonnull
public byte[] toBytes(boolean copy)

Serializes the version information to a byte array. This array should be used to represent the version within the database. In the case that the version is incomplete, the values within the byte array will not be meaningful except that the last two bytes will represent the local version. If the copy parameter is set to false, then the array that is returned will be the exact same array as the one that is used internally by this object, so it is only safe to set copy to false if the array is not modified by anything that uses this call.

Parameters:

copy - whether to copy the underlying data array

Returns:

byte representation of this version

writeTo

@Nonnull
public ByteBuffer writeTo(@Nonnull
                                   ByteBuffer buffer)

Write the serialized version information to the end of a ByteBuffer. It will then return the passed in ByteBuffer so that the user can chain updates to it (like many of the mutation methods of a ByteBuffer itself). This method does not itself validate that buffer has sufficient space to store a serialized version but relies on ByteBuffer to throw an error in that case.

Parameters:

buffer - the byte buffer to append this version to

Returns:

the same byte buffer

See Also:

toBytes()

writeTo

public int writeTo(@Nonnull
                   byte[] bytes)

Write the serialized version to the beginning of the given byte array. This will throw a RecordCoreArgumentException if there is insufficient space in the array to write this version.

Parameters:

bytes - the byte array in which to write this version

Returns:

the first position within bytes after this serialized version

Throws:

RecordCoreArgumentException - if there is insufficient space within bytes

See Also:

toBytes(), writeTo(byte[], int)

writeTo

public int writeTo(@Nonnull
                   byte[] bytes,
                   int offset)

Write the serialized version to a specified offset within the given byte array. This will throw a RecordCoreArgumentException if there is insufficient space in the array to write this version.

Parameters:

bytes - the byte array in which to write this version

offset - the beginning offset at which to write this version

Returns:

the first position within bytes after this serialized version

Throws:

RecordCoreArgumentException - if there is insufficient space within bytes

See Also:

toBytes()

isComplete

public boolean isComplete()

Whether this version has all of its relevant data set. In particular, this should be set to true if everything about the version is already known. It should be set to false if something is not yet known. It is the part of the version that might be "incomplete" that should be set by some global monotonic order enforcer to impose a global ordering on all record versions.

Returns:

whether this record version is complete

getLocalVersion

public int getLocalVersion()

Retrieves the part of the version that is set within a single FDBRecordContext. This is used to differentiate between records that might be mutated in the same context and requires keeping local state to set the order. Even if a record version is incomplete, it should still return something for this method.

Returns:

the local version

getGlobalVersion

@Nonnull
public byte[] getGlobalVersion()

Retrieves the part of the version that is set by the database. This will be a byte array of length GLOBAL_VERSION_LENGTH. The first eight bytes correspond to the database's version, i.e., the eight byte version used by the database's MVCC system. The last two bytes correspond to an order imposed by the database to create an order between transactions that are committed at the same version. If this FDBRecordVersion is incomplete, then this will throw an FDBRecordVersion.IncompleteRecordVersionException.

Returns:

the part of the version set by the order enforcer

Throws:

FDBRecordVersion.IncompleteRecordVersionException - if the global version is unset

See Also:

FDBRecordContext.getCommittedVersion(), FDBRecordContext.getVersionStamp()

getDBVersion

public long getDBVersion()

Retrieves the part of the version that corresponds to the database commit version. This consists of the first eight bytes of the version viewed as a big-endian integer. This is the version used by the database's MVCC system, which means that a transaction should only be able see an FDBRecordVersion (assuming the version was generated by the transaction's database) if the value returned by this function is less than or equal to the transaction's read version. If this FDBRecordVersion is incomplete, then this will throw an FDBRecordVersion.IncompleteRecordVersionException.

Returns:

the part of the version corresponding to the database version

Throws:

FDBRecordVersion.IncompleteRecordVersionException - if the global version is unset

See Also:

FDBRecordContext.getCommittedVersion(), FDBRecordContext.getReadVersionAsync()

next

@Nonnull
public FDBRecordVersion next()

Returns an incremented version of the current FDBRecordVersion. In particular, this returns the first possible version that is strictly greater than this instance. This can throw an IllegalStateException if one tries to increment the maximum version. This function also has no side-effects.

Returns:

the next highest FDBRecordVersion instance

prev

@Nonnull
public FDBRecordVersion prev()

Returns a decremented version of the current FDBRecordVersion. In particular, this returns the first possible version that is strictly less than this instance. This can throw an IllegalStateException if one tries to decrement the minimum version. This function also has no side-effects.

Returns:

the previous FDBRecordVersion instance

withCommittedVersion

@Nonnull
public FDBRecordVersion withCommittedVersion(@Nullable
                                                      byte[] committedVersion)

Complete this version with the version from as successful commit.

Parameters:

committedVersion - the result of FDBRecordContext.getVersionStamp()

Returns:

a new record version with a complete version

equals

public boolean equals(Object o)

Whether this FDBRecordVersion mathces the given object. It will compare equally with another FDBRecordVersion that has the same local and global version and will compare as not equal otherwise.

Overrides:

equals in class Object

Parameters:

o - the object to check for equality

Returns:

true if the object is equal to this version and false otherwise

compareTo

public int compareTo(@Nonnull
                     FDBRecordVersion other)

Compares two different record versions. The basic contract is that when a series of RecordVersions are placed in sorted order, the older records should sort before newer records. In particular, the total ordering is as follows:

• All complete versions sort before incomplete versions.
• For two complete versions, the one with the lexicographically smaller global version sorts earlier. If they have the same global version, then the one with the smaller local version sorts earlier.
• For two incomplete versions, the one with the smaller local version sorts earlier.

Specified by:

compareTo in interface Comparable<FDBRecordVersion>

Parameters:

other - the other RecordVersion object to compare to

Returns:

-1 if this instance is older, 0 if they are the same, or 1 if this instance is newer

hashCode

public int hashCode()

Hash code derived from the local and global version hash codes. It is the bitwise exclusive-or of the the hash codes of the local and global version components.

Overrides:

hashCode in class Object

Returns:

hash code for this version

toString

@Nonnull
public String toString()

Human-readable representation of this FDBRecordVersion. It will include both the local and global version information. It will return a global version of 10 consecutive bytes with value 0xff.

Overrides:

toString in class Object

Returns:

human-readable representation of the record version