Class FDBRecordVersion
- java.lang.Object
-
- com.apple.foundationdb.record.provider.foundationdb.FDBRecordVersion
-
- All Implemented Interfaces:
Comparable<FDBRecordVersion>
@API(MAINTAINED) public class FDBRecordVersion extends Object implements Comparable<FDBRecordVersion>
Class representing a specific version within FDB. This is designed to inter-operate with theVersionstamp
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 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 Description static int
GLOBAL_VERSION_LENGTH
Length of the global versions used byFDBRecordVersion
.static FDBRecordVersion
MAX_VERSION
Maximum possible completeFDBRecordVersion
value.static FDBRecordVersion
MIN_VERSION
Minimum possible completeFDBRecordVersion
value.static int
VERSION_LENGTH
Length of the underlying byte array representation of anFDBRecordVersion
.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description int
compareTo(FDBRecordVersion other)
Compares two different record versions.static FDBRecordVersion
complete(byte[] versionBytes)
Create aFDBRecordVersion
that is complete and has the given serialized bytes.static FDBRecordVersion
complete(byte[] versionBytes, boolean copy)
Create aFDBRecordVersion
that is complete and has the given serialized bytes.static FDBRecordVersion
complete(byte[] globalVersion, int localVersion)
Create aFDBRecordVersion
that is complete and has the given global and local versions.boolean
equals(Object o)
Whether thisFDBRecordVersion
mathces the given object.static FDBRecordVersion
firstInDBVersion(long dbVersion)
Return the firstFDBRecordVersion
that could be written at a given database version or later.static FDBRecordVersion
firstInGlobalVersion(byte[] globalVersion)
Return the firstFDBRecordVersion
that could be written at the given global version.static FDBRecordVersion
fromBytes(byte[] versionBytes)
Create aFDBRecordVersion
from the given serialized bytes.static FDBRecordVersion
fromBytes(byte[] versionBytes, boolean copy)
Create aFDBRecordVersion
from the given serialized bytes.static FDBRecordVersion
fromVersionstamp(Versionstamp versionstamp)
Create aFDBRecordVersion
from the givenVersionstamp
instance.static FDBRecordVersion
fromVersionstamp(Versionstamp versionstamp, boolean copy)
Create aFDBRecordVersion
from the givenVersionstamp
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 singleFDBRecordContext
.int
hashCode()
Hash code derived from the local and global version hash codes.static FDBRecordVersion
incomplete(int localVersion)
Create aFDBRecordVersion
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 lastFDBRecordVersion
that could have been written at the given database version.static FDBRecordVersion
lastInGlobalVersion(byte[] globalVersion)
Return the lastFDBRecordVersion
that could be written at the given global version.FDBRecordVersion
next()
Returns an incremented version of the currentFDBRecordVersion
.FDBRecordVersion
prev()
Returns a decremented version of the currentFDBRecordVersion
.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 thisFDBRecordVersion
.Versionstamp
toVersionstamp()
Converts thisRecordVersion
instance to aVersionstamp
instance.Versionstamp
toVersionstamp(boolean copy)
Converts thisRecordVersion
instance to aVersionstamp
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 aByteBuffer
.
-
-
-
Field Detail
-
GLOBAL_VERSION_LENGTH
public static final int GLOBAL_VERSION_LENGTH
Length of the global versions used byFDBRecordVersion
.- See Also:
- Constant Field Values
-
VERSION_LENGTH
public static final int VERSION_LENGTH
Length of the underlying byte array representation of anFDBRecordVersion
.- See Also:
- Constant Field Values
-
MIN_VERSION
public static final FDBRecordVersion MIN_VERSION
Minimum possible completeFDBRecordVersion
value.
-
MAX_VERSION
public static final FDBRecordVersion MAX_VERSION
Maximum possible completeFDBRecordVersion
value.
-
-
Method Detail
-
complete
@Nonnull public static FDBRecordVersion complete(@Nonnull byte[] globalVersion, int localVersion)
Create aFDBRecordVersion
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 versionlocalVersion
- the local version associated with this version- Returns:
- a new complete
FDBRecordVersion
-
complete
@Nonnull public static FDBRecordVersion complete(@Nonnull byte[] versionBytes)
Create aFDBRecordVersion
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 thecomplete
static initializer that takes abyte
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 aFDBRecordVersion
that is complete and has the given serialized bytes. The given bytes should contain both the global and the local version. If thecopy
parameter is set tofalse
, 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 tofalse
if one knows that that won't happen.- Parameters:
versionBytes
- the byte representation of a versioncopy
- whether to copy the array for the newFDBRecordVersion
- Returns:
- a version object wrapping the given bytes
-
incomplete
@Nonnull public static FDBRecordVersion incomplete(int localVersion)
Create aFDBRecordVersion
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 aFDBRecordVersion
from the given serialized bytes. The given bytes should contain both the global and local version. Unlikecomplete
, 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 all0xff
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 thefromBytes
static initializer that takes abyte
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 aFDBRecordVersion
from the given serialized bytes. The given bytes should contain both the global and local version. Unlikecomplete
, 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 all0xff
bytes. If thecopy
parameter is set tofalse
, 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 versioncopy
- whether to copy the array for the newFDBRecordVersion
- Returns:
- a version object wrapping the given bytes
-
fromVersionstamp
@Nonnull public static FDBRecordVersion fromVersionstamp(@Nonnull Versionstamp versionstamp)
Create aFDBRecordVersion
from the givenVersionstamp
instance. TheVersionstamp
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 thefromVersionstamp
static initializer that takes aboolean
.- Parameters:
versionstamp
-Versionstamp
instance to convert- Returns:
- a
FDBRecordVersion
with equivalent information
-
fromVersionstamp
@Nonnull public static FDBRecordVersion fromVersionstamp(@Nonnull Versionstamp versionstamp, boolean copy)
Create aFDBRecordVersion
from the givenVersionstamp
instance. TheVersionstamp
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 thecopy
parameter is set tofalse
, it will reuse the same underlying array used by theVersionstamp
class rather than making its own. This is unsafe if the array is modified later, so it should only be set tofalse
if one knows that that won't happen.- Parameters:
versionstamp
-Versionstamp
instance to convertcopy
- whether to copy the underlying array for the newFDBRecordVersion
- Returns:
- a
FDBRecordVersion
with equivalent information
-
firstInDBVersion
@Nonnull public static FDBRecordVersion firstInDBVersion(long dbVersion)
Return the firstFDBRecordVersion
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 thisFDBRecordVersion
on- Returns:
- the first version possibly written at this database version or newer
-
firstInGlobalVersion
public static FDBRecordVersion firstInGlobalVersion(@Nonnull byte[] globalVersion)
Return the firstFDBRecordVersion
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 lastFDBRecordVersion
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 thisFDBRecordVersion
on- Returns:
- the last version possibly written at this database version or older
-
lastInGlobalVersion
public static FDBRecordVersion lastInGlobalVersion(@Nonnull byte[] globalVersion)
Return the lastFDBRecordVersion
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 thisRecordVersion
instance to aVersionstamp
instance. That type is safe to serialize withinTuple
s. 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 oftoVersionstamp
that takes a boolean as an argument.- Returns:
Versionstamp
representation of this version
-
toVersionstamp
@Nonnull public Versionstamp toVersionstamp(boolean copy)
Converts thisRecordVersion
instance to aVersionstamp
instance. That type is safe to serialize withinTuple
s. If thecopy
parameter is set tofalse
, then the newVersionstamp
will use the same underlying data arrays as thisRecordVersion
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 oftoBytes
that takes aboolean
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 thecopy
parameter is set tofalse
, 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 setcopy
tofalse
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 aByteBuffer
. It will then return the passed inByteBuffer
so that the user can chain updates to it (like many of the mutation methods of aByteBuffer
itself). This method does not itself validate thatbuffer
has sufficient space to store a serialized version but relies onByteBuffer
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 aRecordCoreArgumentException
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 withinbytes
- 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 aRecordCoreArgumentException
if there is insufficient space in the array to write this version.- Parameters:
bytes
- the byte array in which to write this versionoffset
- 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 withinbytes
- See Also:
toBytes()
-
isComplete
public boolean isComplete()
Whether this version has all of its relevant data set. In particular, this should be set totrue
if everything about the version is already known. It should be set tofalse
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 singleFDBRecordContext
. 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 lengthGLOBAL_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 thisFDBRecordVersion
is incomplete, then this will throw anFDBRecordVersion.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 anFDBRecordVersion
(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 thisFDBRecordVersion
is incomplete, then this will throw anFDBRecordVersion.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 currentFDBRecordVersion
. In particular, this returns the first possible version that is strictly greater than this instance. This can throw anIllegalStateException
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 currentFDBRecordVersion
. In particular, this returns the first possible version that is strictly less than this instance. This can throw anIllegalStateException
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 ofFDBRecordContext.getVersionStamp()
- Returns:
- a new record version with a complete version
-
equals
public boolean equals(Object o)
Whether thisFDBRecordVersion
mathces the given object. It will compare equally with anotherFDBRecordVersion
that has the same local and global version and will compare as not equal otherwise.
-
compareTo
public int compareTo(@Nonnull FDBRecordVersion other)
Compares two different record versions. The basic contract is that when a series ofRecordVersion
s 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 interfaceComparable<FDBRecordVersion>
- Parameters:
other
- the otherRecordVersion
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.
-
-