io.goshawkdb.client

Class GoshawkObjRef

java.lang.Object

io.goshawkdb.client.GoshawkObjRef

public class GoshawkObjRef
extends java.lang.Object

This class represents references (or pointers) to Objects within GoshawkDB. GoshawkDB Objects can only be read or modified from within a transaction. References include Capabilitys which control whether an Object can be read, written, both, or neither. Multiple references to the same Object can have different capabilities. A client gains capabilities on an Object by being able to read other Objects that have references to an Object. An Object will accept any action (read, write etc) which has been discovered. GoshawkObjRefs are linked to Connections: if you're using multiple Connections, it is not permitted to use the same GoshawkObjRef in both connections; you can either navigate to the same object in both connections or once that is done in each connection, you can use getObject to get a new GoshawkObjRef to the same object in the other connection. Within the same Connection, and within nested transactions, GoshawkObjRefs may be freely reused.

Field Summary

Fields

Modifier and Type	Field and Description
VarUUId	id The unique identifier of the object to which this reference refers.

Method Summary

Modifier and Type	Method and Description
Capability	getObjCapability() Gets the Capability on the underlying Object.
Capability	getRefCapability() Gets the Capability from this reference.
GoshawkObjRef[]	getReferences() Get the objects pointed to from the current object.
java.nio.ByteBuffer	getValue() Returns the current value of this object.
TxnId	getVersion() Get the current version of the object.
GoshawkObjRef	grantCapability(Capability capability) Create a new GoshawkObjRef to the same database object but with different capabilities.
boolean	referencesSameAs(GoshawkObjRef that) Test to see if two GoshawkObjRefs refer (point) to the same underlying Object.
void	set(java.nio.ByteBuffer value, GoshawkObjRef... references) Sets the value and references of the current object.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

id

public final VarUUId id

The unique identifier of the object to which this reference refers.

Method Detail

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

grantCapability

public GoshawkObjRef grantCapability(Capability capability)

Create a new GoshawkObjRef to the same database object but with different capabilities. This will always succeed, but the transaction may be rejected if you attempt to grant capabilities you have not received. From a ReadWrite capability, you can grant anything. From a Read capability you can grant only a Read or None. From a Write capability you can grant only a Write or None. From a None capability you can only grant a None.

Parameters:

capability - The capability to provide in the new reference

Returns:

The new reference.

getRefCapability

public Capability getRefCapability()

Gets the Capability from this reference. This may be different from the capabilities discovered on the Object.

Returns:

The Capability from the reference.

getObjCapability

public Capability getObjCapability()

Gets the Capability on the underlying Object. This is the union of all capabilities that have been discovered in references that point to the same underlying Object.

Returns:

The Capability on the underlying Object.

referencesSameAs

public boolean referencesSameAs(GoshawkObjRef that)

Test to see if two GoshawkObjRefs refer (point) to the same underlying Object. This method does not do any comparison on the Capability within the references (which is why it's not called equals).

Parameters:

that - The other GoshawkObjRef

Returns:

true iff both this and that point to the same underlying GoshawkDB Object.

getValue

public java.nio.ByteBuffer getValue()

Returns the current value of this object.

Returns:

The current value. The returned buffer is a copy of the underlying buffer, so modifying it is perfectly safe. If you do modify it, you will need to call one of the set methods for your modifications to take any effect. This method will error if you do not have the Read Capability for this object.

getReferences

public GoshawkObjRef[] getReferences()

Get the objects pointed to from the current object.

Returns:

the array of GoshawkObjRef to which the current object refers. As with getValue, the array is a copy of the underlying array, so you are safe to modify it, but you will need to call one of the set methods for your modifications to take any effect. This method will error if you do not have the Read Capability for this object.

getVersion

public TxnId getVersion()

Get the current version of the object. This method will error if you do not have the Read Capability for this object.

Returns:

the TxnId of the last transaction that wrote to this object. This will return null if the object has been created by the current transaction.

set

public void set(java.nio.ByteBuffer value,
                GoshawkObjRef... references)

Sets the value and references of the current object. If the value contains any references to other objects, they must be explicitly declared as references otherwise on retrieval you will not be able to navigate to them. Note that the order of references is stable. A null value sets the value to a zero-length ByteBuffer. This method will error if you do not have the Write Capability for this object.

Parameters:

value - The value to set the object to. The buffer will be cloned and the contents copied. Therefore any changes you make to this param after calling this method will be ignored (you will need to call the set method again). The copying will not alter any position, limit, capacity or marks of the value ByteBuffer. The value is taken to be from position 0 to the current limit of the buffer.

references - The new list of objects to which the current object refers. Again, the array of references is copied.