co.paralleluniverse.galaxy

Interface Store

All Superinterfaces:

Cache

public interface Store
extends Cache

The grid's distributed data-store service. Internally, each data item is owned by one and only one node in the cluster at any one time, though it may be shared by many. In order to write an item, a node gains ownership over it.

Method Summary

Methods

Modifier and Type	Method and Description
void	abort(StoreTransaction txn) Ends a transaction after a failure.
long	alloc(int count, StoreTransaction txn) Allocates one or more new (and empty) items in the store.
ListenableFuture<Long>	allocAsync(int count, StoreTransaction txn) Allocates one or more new (and empty) items in the store.
StoreTransaction	beginTransaction() Creates a new transaction.
void	commit(StoreTransaction txn) Ends a transaction, and makes all updates visible by all other nodes in the cluster.
void	del(long id, StoreTransaction txn) Deletes an item from the store.
ListenableFuture<Void>	delAsync(long id, StoreTransaction txn)
byte[]	get(long id) Retrieves a given data item.
void	get(long id, Persistable object) Retrieves a given data item into a Persistable.
byte[]	get(long id, short nodeHint) Retrieves a given data item, using a hint as to its owner in the cluster. If the item is indeed found on the hinted node, the retrieval performance might be superior.
void	get(long id, short nodeHint, Persistable object) Retrieves a given data item into a Persistable, using a hint as to its owner in the cluster. If the item is indeed found on the hinted node, the retrieval performance might be superior.
ListenableFuture<byte[]>	getAsync(long id) Retrieves a given data item asynchronously.
ListenableFuture<Persistable>	getAsync(long id, Persistable object) Retrieves a given data item into a Persistable asynchronously.
ListenableFuture<byte[]>	getAsync(long id, short nodeHint) Retrieves a given data item asynchronously, using a hint as to its owner in the cluster.
ListenableFuture<Persistable>	getAsync(long id, short nodeHint, Persistable object) Retrieves a given data item asynchronously into a Persistable, using a hint as to its owner in the cluster.
byte[]	getFromOwner(long id, long ownerOf) Retrieves a given data item, using a hint as to its owner in the cluster.
void	getFromOwner(long id, long ownerOf, Persistable object) Retrieves a given data item, using a hint as to its owner in the cluster.
ListenableFuture<byte[]>	getFromOwnerAsync(long id, long ownerOf) Retrieves a given data item asynchronously, using a hint as to its owner in the cluster.
ListenableFuture<Persistable>	getFromOwnerAsync(long id, long ownerOf, Persistable object) Retrieves a given data item asynchronously, using a hint as to its owner in the cluster.
CacheListener	getListener(long id)
int	getMaxItemSize() Returns the maximum size, in bytes, of a data item in the grid.
long	getRoot(String rootName, long id, StoreTransaction txn) Gets or possibly creates a root data item.
long	getRoot(String rootName, StoreTransaction txn) Gets or possibly creates a root data item.
void	gets(long id, Persistable object, StoreTransaction txn) Retrieves a given data item into a Persistable, and pins the shared (cached) instance to this node.
void	gets(long id, short nodeHint, Persistable object, StoreTransaction txn) Retrieves a given data item into a Persistable with a hint as to its owner in the cluster, and pins the shared (cached) instance to this node.
byte[]	gets(long id, short nodeHint, StoreTransaction txn) Retrieves a given data item with a hint as to its owner in the cluster, and pins the shared (cached) instance to this node.
byte[]	gets(long id, StoreTransaction txn) Retrieves a given data item, and pins the shared (cached) instance to this node.
ListenableFuture<Persistable>	getsAsync(long id, Persistable object, StoreTransaction txn) Retrieves a given data asynchronously item into a Persistable, and pins the shared (cached) instance to this node.
ListenableFuture<Persistable>	getsAsync(long id, short nodeHint, Persistable object, StoreTransaction txn) Retrieves a given data asynchronously item into a Persistable with a hint as to its owner in the cluster, and pins the shared (cached) instance to this node.
ListenableFuture<byte[]>	getsAsync(long id, short nodeHint, StoreTransaction txn) Retrieves a given data item asynchronously with a hint as to its owner in the cluster, and pins the shared (cached) instance to this node.
ListenableFuture<byte[]>	getsAsync(long id, StoreTransaction txn) Retrieves a given data item asynchronously, and pins the shared (cached) instance to this node.
void	getsFromOwner(long id, long ownerOf, Persistable object, StoreTransaction txn) Retrieves a given data item with a hint as to its owner in the cluster, and pins the shared (cached) instance to this node.
byte[]	getsFromOwner(long id, long ownerOf, StoreTransaction txn) Retrieves a given data item with a hint as to its owner in the cluster, and pins the shared (cached) instance to this node.
ListenableFuture<Persistable>	getsFromOwnerAsync(long id, long ownerOf, Persistable object, StoreTransaction txn) Retrieves a given data item asynchronously with a hint as to its owner in the cluster, and pins the shared (cached) instance to this node.
ListenableFuture<byte[]>	getsFromOwnerAsync(long id, long ownerOf, StoreTransaction txn) Retrieves a given data item asynchronously with a hint as to its owner in the cluster, and pins the shared (cached) instance to this node.
ItemState	getState(long id) Returns an item's state in the local store.
long	getVersion(long id) CacheLine version
void	getx(long id, Persistable object, StoreTransaction txn) Retrieves a given data item into a Persistable, makes this node its exclusive owner, and pins it.
void	getx(long id, short nodeHint, Persistable object, StoreTransaction txn) Retrieves a given data item with a hint as to its owner in the cluster, makes this node its exclusive owner, and pins it.
byte[]	getx(long id, short nodeHint, StoreTransaction txn) Retrieves a given data item with a hint as to its owner in the cluster, makes this node its exclusive owner, and pins it.
byte[]	getx(long id, StoreTransaction txn) Retrieves a given data item, makes this node its exclusive owner, and pins it.
ListenableFuture<Persistable>	getxAsync(long id, Persistable object, StoreTransaction txn) Retrieves a given data item asynchronously into a Persistable, makes this node its exclusive owner, and pins it.
ListenableFuture<Persistable>	getxAsync(long id, short nodeHint, Persistable object, StoreTransaction txn) Retrieves a given data item asynchronously with a hint as to its owner in the cluster, makes this node its exclusive owner, and pins it.
ListenableFuture<byte[]>	getxAsync(long id, short nodeHint, StoreTransaction txn) Retrieves a given data item asynchronously with a hint as to its owner in the cluster, makes this node its exclusive owner, and pins it.
ListenableFuture<byte[]>	getxAsync(long id, StoreTransaction txn) Retrieves a given data item asynchronously, makes this node its exclusive owner, and pins it.
void	getxFromOwner(long id, long ownerOf, Persistable object, StoreTransaction txn) Retrieves a given data item with a hint as to its owner in the cluster, makes this node its exclusive owner, and pins it.
byte[]	getxFromOwner(long id, long ownerOf, StoreTransaction txn) Retrieves a given data item with a hint as to its owner in the cluster, makes this node its exclusive owner, and pins it.
ListenableFuture<Persistable>	getxFromOwnerAsync(long id, long ownerOf, Persistable object, StoreTransaction txn) Retrieves a given data item asynchronously with a hint as to its owner in the cluster, makes this node its exclusive owner, and pins it.
ListenableFuture<byte[]>	getxFromOwnerAsync(long id, long ownerOf, StoreTransaction txn) Retrieves a given data item asynchronously with a hint as to its owner in the cluster, makes this node its exclusive owner, and pins it.
<T> T	invoke(long id, LineFunction<T> function)
<T> ListenableFuture<T>	invokeAsync(long id, LineFunction<T> function)
boolean	isPinned(long id) Tests whether an item is pinned on this node.
boolean	isRootCreated(long rootId, StoreTransaction txn) Tests whether a root item has been newly created.
void	push(long id, short... toNodes) Makes the given item available in the given nodes' cache.
void	pushx(long id, short toNode) Makes the given item available in the given node's cache, and makes that node the owner of the item.
long	put(byte[] data, StoreTransaction txn) Puts a new item into the store and returns its (newly allocated) ID.
long	put(ByteBuffer data, StoreTransaction txn) Puts a new item into the store and returns its (newly allocated) ID.
long	put(Persistable object, StoreTransaction txn) Puts a new item into the store and returns its (newly allocated) ID.
ListenableFuture<Long>	putAsync(byte[] data, StoreTransaction txn) Puts a new item into the store and returns its (newly allocated) ID.
ListenableFuture<Long>	putAsync(ByteBuffer data, StoreTransaction txn) Puts a new item into the store and returns its (newly allocated) ID.
ListenableFuture<Long>	putAsync(Persistable object, StoreTransaction txn) Puts a new item into the store and returns its (newly allocated) ID.
void	release(long id) Releases a line that's been pinned to this node by one of the gets, getx, put operations.
void	rollback(StoreTransaction txn) Reverts set operations that were performed during the transactions.
void	send(long id, byte[] msg) Sends a message to an item, which will be received by CacheListener.messageReceived on the item's owning node.
void	send(long id, Streamable msg) Sends a message to an item, which will be received by CacheListener.messageReceived on the item's owning node.
ListenableFuture<Void>	sendAsync(long id, byte[] msg) Sends a message to an item, which will be received by CacheListener.messageReceived on the item's owning node.
ListenableFuture<Void>	sendAsync(long id, Streamable msg) Sends a message to an item, which will be received by CacheListener.messageReceived on the item's owning node.
void	set(long id, byte[] data, StoreTransaction txn) Gains ownership of an item and sets its contents.
void	set(long id, ByteBuffer data, StoreTransaction txn) Gains ownership of an item and sets its contents.
void	set(long id, Persistable object, StoreTransaction txn) Gains ownership of an item and sets its contents.
ListenableFuture<Void>	setAsync(long id, byte[] data, StoreTransaction txn) Gains ownership of an item and sets its contents asynchronously.
ListenableFuture<Void>	setAsync(long id, ByteBuffer data, StoreTransaction txn) Gains ownership of an item and sets its contents asynchronously.
ListenableFuture<Void>	setAsync(long id, Persistable object, StoreTransaction txn) Gains ownership of an item and sets its contents asynchronously.
void	setListener(long id, CacheListener listener) Sets a listener listening for local cache events on the given item.
CacheListener	setListenerIfAbsent(long id, CacheListener listener) Sets a listener listening for local cache events on the given item if absent.
boolean	tryPin(long id, ItemState state, StoreTransaction txn) Pins item if it can be done locally.

Method Detail

getMaxItemSize

int getMaxItemSize()

Returns the maximum size, in bytes, of a data item in the grid. Attempts to store larger items will result in an exception. This limit is set in the cache spring-bean configuration.

Returns:

The maximum size, in bytes, of a data item in the grid.

beginTransaction

StoreTransaction beginTransaction()

Creates a new transaction.

A transaction can be used by more than one thread.

Returns:

A newly created transaction.

commit

void commit(StoreTransaction txn)
            throws InterruptedException

Ends a transaction, and makes all updates visible by all other nodes in the cluster.

Parameters:

txn - The current transaction, which we wish to complete.

Throws:

InterruptedException

abort

void abort(StoreTransaction txn)
           throws InterruptedException

Ends a transaction after a failure.

This method must be called only after rollback() has been called, or a manual rollback has been done.

Parameters:

txn - The current transaction, which we wish to complete after failure.

Throws:

InterruptedException

rollback

void rollback(StoreTransaction txn)

Reverts set operations that were performed during the transactions.

This method does not complete the transaction. endTransaction() must still be called.

Parameters:

txn - The current transaction.

release

void release(long id)

Releases a line that's been pinned to this node by one of the gets, getx, put operations.

This method must be called to release a line used in one of the gets, getx, put operations, if they were called with a null transaction.

Parameters:

id -

getRoot

long getRoot(String rootName,
           StoreTransaction txn)
             throws TimeoutException

Gets or possibly creates a root data item. The same item ID will be returned when this method is called on any cluster node with the same root name.

You can test if the root has been newly created by this transaction by calling .

Parameters:

rootName - The root's name.

txn - The current transaction. May not be null.

Returns:

The root item's ID.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

getRoot

long getRoot(String rootName,
           long id,
           StoreTransaction txn)
             throws TimeoutException

Gets or possibly creates a root data item. The same item ID will be returned when this method is called on any cluster node with the same root name.

You can test if the root has been newly created by this transaction by calling .

Parameters:

rootName - The root's name.

id - If the root does not yet exist, it will be created and given this ID.

txn - The current transaction. May not be null.

Returns:

The root item's ID.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

isRootCreated

boolean isRootCreated(long rootId,
                    StoreTransaction txn)

Tests whether a root item has been newly created.

Parameters:

rootId - The root item's ID.

txn - The current transaction.

Returns:

true if the root has been created by the current transaction; false if it existed before current transaction.

setListener

void setListener(long id,
               CacheListener listener)

Sets a listener listening for local cache events on the given item.

Specified by:

setListener in interface Cache

Parameters:

id - The item's ID.

listener - The listener.

setListenerIfAbsent

CacheListener setListenerIfAbsent(long id,
                                CacheListener listener)

Sets a listener listening for local cache events on the given item if absent.

Specified by:

setListenerIfAbsent in interface Cache

Parameters:

id - The item's ID.

listener - The listener.

Returns:

The given listener if it was set or the existing one otherwise.

getListener

CacheListener getListener(long id)

Specified by:

getListener in interface Cache

Parameters:

id - The item's ID.

Returns:

The cacheListener of this line

alloc

long alloc(int count,
         StoreTransaction txn)
           throws TimeoutException

Allocates one or more new (and empty) items in the store.

When allocating a single item, it's better to use put(), but some data structures might require allocating an array of items.

Parameters:

count - The number of items to allocate.

txn - The current transaction. May not be null.

Returns:

The id of the first item in the allocated array. The following count - 1 IDs belong to the following elements of the array.

Throws:

TimeoutException

put

long put(byte[] data,
       StoreTransaction txn)
         throws TimeoutException

Puts a new item into the store and returns its (newly allocated) ID.

Parameters:

data - The item's contents.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

The item's (newly allocated) ID.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

put

long put(ByteBuffer data,
       StoreTransaction txn)
         throws TimeoutException

Puts a new item into the store and returns its (newly allocated) ID.

Parameters:

data - The item's contents.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

The item's (newly allocated) ID.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

put

long put(Persistable object,
       StoreTransaction txn)
         throws TimeoutException

Puts a new item into the store and returns its (newly allocated) ID.

Parameters:

object - The item's contents.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

The item's (newly allocated) ID.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

get

byte[] get(long id)
           throws TimeoutException

Retrieves a given data item.

Parameters:

id - The item's ID.

Returns:

The contents of the item.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

get

void get(long id,
       Persistable object)
         throws TimeoutException

Retrieves a given data item into a Persistable.

Parameters:

id - The item's ID.

object - The object into which the contents of the item will be written. May be null.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

get

byte[] get(long id,
         short nodeHint)
           throws TimeoutException

Retrieves a given data item, using a hint as to its owner in the cluster.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

Parameters:

id - The item's ID.

nodeHint - The ID of the node the data item is probably owned by.

Returns:

The contents of the item.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

get

void get(long id,
       short nodeHint,
       Persistable object)
         throws TimeoutException

Retrieves a given data item into a Persistable, using a hint as to its owner in the cluster.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

Parameters:

id - The item's ID.

nodeHint - The ID of the node the data item is probably owned by.

object - The object into which the contents of the item will be written. May be null.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

getFromOwner

byte[] getFromOwner(long id,
                  long ownerOf)
                    throws TimeoutException

Retrieves a given data item, using a hint as to its owner in the cluster. Unlike the direct hint given in get(long, short), the hinted node here is the owner of a given item.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

Parameters:

id - The item's ID.

ownerOf - The ID of an item whose owner is probably the owner of the requested item as well.

Returns:

The contents of the item.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

getFromOwner

void getFromOwner(long id,
                long ownerOf,
                Persistable object)
                  throws TimeoutException

Retrieves a given data item, using a hint as to its owner in the cluster. Unlike the direct hint given in get(long, short, Persistable), the hinted node here is the owner of a given item.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

Parameters:

id - The item's ID.

ownerOf - The ID of an item whose owner is probably the owner of the requested item as well.

object - The object into which the contents of the item will be written. May be null.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

gets

byte[] gets(long id,
          StoreTransaction txn)
            throws TimeoutException

Retrieves a given data item, and pins the shared (cached) instance to this node. What this means is that while other nodes will be able to read the same item, no node will be able to update it until until we end the transaction or release it.

Parameters:

id - The item's ID.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

The contents of the item.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

gets

void gets(long id,
        Persistable object,
        StoreTransaction txn)
          throws TimeoutException

Retrieves a given data item into a Persistable, and pins the shared (cached) instance to this node. What this means is that while other nodes will be able to read the same item, no node will be able to update it until until we end the transaction or release it.

Parameters:

id - The item's ID.

object - The object into which the contents of the item will be written. May be null.

txn - The current transaction. May be null, in which case you must later call release(id).

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

gets

byte[] gets(long id,
          short nodeHint,
          StoreTransaction txn)
            throws TimeoutException

Retrieves a given data item with a hint as to its owner in the cluster, and pins the shared (cached) instance to this node. What this means is that while other nodes will be able to read the same item, no node will be able to update it until until we end the transaction or release it.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

Parameters:

id - The item's ID.

nodeHint - The ID of the node the data item is probably owned by.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

The contents of the item.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

gets

void gets(long id,
        short nodeHint,
        Persistable object,
        StoreTransaction txn)
          throws TimeoutException

Retrieves a given data item into a Persistable with a hint as to its owner in the cluster, and pins the shared (cached) instance to this node. What this means is that while other nodes will be able to read the same item, no node will be able to update it until until we end the transaction or release it.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

Parameters:

id - The item's ID.

nodeHint - The ID of the node the data item is probably owned by.

txn - The current transaction. May be null, in which case you must later call release(id).

object - The object into which the contents of the item will be written. May be null.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

getsFromOwner

byte[] getsFromOwner(long id,
                   long ownerOf,
                   StoreTransaction txn)
                     throws TimeoutException

Retrieves a given data item with a hint as to its owner in the cluster, and pins the shared (cached) instance to this node. What this means is that while other nodes will be able to update it until until we end the transaction or release it. Unlike the direct hint given in gets(long, short, StoreTransaction), the hinted node here is the owner of a given item.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

Parameters:

id - The item's ID.

ownerOf - The ID of an item whose owner is probably the owner of the requested item as well.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

The contents of the item.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

getsFromOwner

void getsFromOwner(long id,
                 long ownerOf,
                 Persistable object,
                 StoreTransaction txn)
                   throws TimeoutException

Retrieves a given data item with a hint as to its owner in the cluster, and pins the shared (cached) instance to this node. What this means is that while other nodes will be able to read the same item, no node will be able to update it until until we end the transaction or release it.
Unlike the direct hint given in gets(long, short, Persistable, StoreTransaction), the hinted node here is the owner of a given item.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

Parameters:

id - The item's ID.

ownerOf - The ID of an item whose owner is probably the owner of the requested item as well.

object - The object into which the contents of the item will be written. May be null.

txn - The current transaction. May be null, in which case you must later call release(id).

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

getx

byte[] getx(long id,
          StoreTransaction txn)
            throws TimeoutException

Retrieves a given data item, makes this node its exclusive owner, and pins it. What this means is that no other node will be able to read or update the same item until until we end the transaction or release it. it.

Parameters:

id - The item's ID.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

The contents of the item.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

getx

void getx(long id,
        Persistable object,
        StoreTransaction txn)
          throws TimeoutException

Retrieves a given data item into a Persistable, makes this node its exclusive owner, and pins it. What this means is that no other node will be able to read or update the same item until until we end the transaction or release it.

Parameters:

id - The item's ID.

object - The object into which the contents of the item will be written. May be null.

txn - The current transaction. May be null, in which case you must later call release(id).

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

getx

byte[] getx(long id,
          short nodeHint,
          StoreTransaction txn)
            throws TimeoutException

Retrieves a given data item with a hint as to its owner in the cluster, makes this node its exclusive owner, and pins it. What this means is that no other node will be able to read or update the same item until until we end the transaction or release it.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

Parameters:

id - The item's ID.

nodeHint - The ID of the node the data item is probably owned by.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

The contents of the item.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

getx

void getx(long id,
        short nodeHint,
        Persistable object,
        StoreTransaction txn)
          throws TimeoutException

Retrieves a given data item with a hint as to its owner in the cluster, makes this node its exclusive owner, and pins it. What this means is that no other node will be able to read or update the same item until we end the transaction or release it.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

Parameters:

id - The item's ID.

nodeHint - The ID of the node the data item is probably owned by.

object - The object into which the contents of the item will be written. May be null.

txn - The current transaction. May be null, in which case you must later call release(id).

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

getxFromOwner

byte[] getxFromOwner(long id,
                   long ownerOf,
                   StoreTransaction txn)
                     throws TimeoutException

Retrieves a given data item with a hint as to its owner in the cluster, makes this node its exclusive owner, and pins it. What this means is that no other node will be able to read or update the same item until we end the transaction or release it. Unlike the direct hint given in getx(long, short, StoreTransaction), the hinted node here is the owner of a given item.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

Parameters:

id - The item's ID.

ownerOf - The ID of an item whose owner is probably the owner of the requested item as well.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

The contents of the item.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

getxFromOwner

void getxFromOwner(long id,
                 long ownerOf,
                 Persistable object,
                 StoreTransaction txn)
                   throws TimeoutException

Retrieves a given data item with a hint as to its owner in the cluster, makes this node its exclusive owner, and pins it. What this means is that no other node will be able to read or update the same item until we end the transaction or release it. Unlike the direct hint given in getx(long, short, Persistable, StoreTransaction), the hinted node here is the owner of a given item.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

Parameters:

id - The item's ID.

ownerOf - The ID of an item whose owner is probably the owner of the requested item as well.

object - The object into which the contents of the item will be written. May be null.

txn - The current transaction. May be null, in which case you must later call release(id).

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

set

void set(long id,
       byte[] data,
       StoreTransaction txn)
         throws TimeoutException

Gains ownership of an item and sets its contents. Upon return from this method, the item will be pinned if and only if it had been pinned when the method was called.

Parameters:

id - The item's ID.

data - The contents to write into the item.

txn - The current transaction. May be null.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

set

void set(long id,
       ByteBuffer data,
       StoreTransaction txn)
         throws TimeoutException

Gains ownership of an item and sets its contents. Upon return from this method, the item will be pinned if and only if it had been pinned when the method was called.

Parameters:

id - The item's ID.

data - The contents to write into the item.

txn - The current transaction. May be null.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

set

void set(long id,
       Persistable object,
       StoreTransaction txn)
         throws TimeoutException

Gains ownership of an item and sets its contents. Upon return from this method, the item will be pinned if and only if it had been pinned when the method was called.

Parameters:

id - The item's ID.

object - The contents to write into the item.

txn - The current transaction. May be null.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

del

void del(long id,
       StoreTransaction txn)
         throws TimeoutException

Deletes an item from the store.

Parameters:

id -

txn - The current transaction. May be null.

Throws:

TimeoutException

invoke

<T> T invoke(long id,
           LineFunction<T> function)
         throws TimeoutException

Throws:

TimeoutException

allocAsync

ListenableFuture<Long> allocAsync(int count,
                                StoreTransaction txn)

Allocates one or more new (and empty) items in the store.

When allocating a single item, it's better to use put(), but some data structures might require allocating an array of items.

Parameters:

count - The number of items to allocate.

txn - The current transaction. May not be null.

Returns:

The id of the first item in the allocated array. The following count - 1 IDs belong to the following elements of the array.

putAsync

ListenableFuture<Long> putAsync(byte[] data,
                              StoreTransaction txn)

Puts a new item into the store and returns its (newly allocated) ID.

Parameters:

data - The item's contents.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

The item's (newly allocated) ID.

putAsync

ListenableFuture<Long> putAsync(ByteBuffer data,
                              StoreTransaction txn)

Puts a new item into the store and returns its (newly allocated) ID.

Parameters:

data - The item's contents.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

The item's (newly allocated) ID.

putAsync

ListenableFuture<Long> putAsync(Persistable object,
                              StoreTransaction txn)

Puts a new item into the store and returns its (newly allocated) ID.

Parameters:

object - The item's contents.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

The item's (newly allocated) ID.

getAsync

ListenableFuture<byte[]> getAsync(long id)

Retrieves a given data item asynchronously.

The asynchronous version of get(long).

Parameters:

id - The item's ID.

Returns:

A future that will return the contents of the item.

getAsync

ListenableFuture<Persistable> getAsync(long id,
                                     Persistable object)

Retrieves a given data item into a Persistable asynchronously.

The asynchronous version of get(long, Persistable).

Parameters:

id - The item's ID.

object - The object into which the contents of the item will be written when the operation completes (after the future has been waited for).

Returns:

A future that will return the passed object.

getAsync

ListenableFuture<byte[]> getAsync(long id,
                                short nodeHint)

Retrieves a given data item asynchronously, using a hint as to its owner in the cluster.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

The asynchronous version of get(long, short).

Parameters:

id - The item's ID.

nodeHint - The ID of the node the data item is probably owned by.

Returns:

A future that will return the contents of the item.

getAsync

ListenableFuture<Persistable> getAsync(long id,
                                     short nodeHint,
                                     Persistable object)

Retrieves a given data item asynchronously into a Persistable, using a hint as to its owner in the cluster.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

The asynchronous version of get(long, short, Persistable).

Parameters:

id - The item's ID.

nodeHint - The ID of the node the data item is probably owned by.

object - The object into which the contents of the item will be written.

Returns:

A future that will return the passed object.

getFromOwnerAsync

ListenableFuture<byte[]> getFromOwnerAsync(long id,
                                         long ownerOf)

Retrieves a given data item asynchronously, using a hint as to its owner in the cluster. Unlike the direct hint given in get(long, short), the hinted node here is the owner of a given item.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

The asynchronous version of getFromOwner(long, long)

Parameters:

id - The item's ID.

ownerOf - The ID of an item whose owner is probably the owner of the requested item as well.

Returns:

A future that will return the contents of the item.

getFromOwnerAsync

ListenableFuture<Persistable> getFromOwnerAsync(long id,
                                              long ownerOf,
                                              Persistable object)

Retrieves a given data item asynchronously, using a hint as to its owner in the cluster. Unlike the direct hint given in get(long, short, Persistable), the hinted node here is the owner of a given item.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

The asynchronous version of getFromOwner(long, long, Persistable)

Parameters:

id - The item's ID.

ownerOf - The ID of an item whose owner is probably the owner of the requested item as well.

object - The object into which the contents of the item will be written. May be null.

Returns:

A future that will return the passed object.

getsAsync

ListenableFuture<byte[]> getsAsync(long id,
                                 StoreTransaction txn)

Retrieves a given data item asynchronously, and pins the shared (cached) instance to this node. What this means is that while other nodes will be able to read the same item, no node will be able to update it until until we end the transaction or release it.

The asynchronous version of gets(long, StoreTransaction)

Parameters:

id - The item's ID.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

A future that will return contents of the item.

getsAsync

ListenableFuture<Persistable> getsAsync(long id,
                                      Persistable object,
                                      StoreTransaction txn)

Retrieves a given data asynchronously item into a Persistable, and pins the shared (cached) instance to this node. What this means is that while other nodes will be able to read the same item, no node will be able to update it until until we end the transaction or release it.

The asynchronous version of gets(long, Persistable, StoreTransaction)

Parameters:

id - The item's ID.

object - The object into which the contents of the item will be written. May be null.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

A future that will return the passed object.

getsAsync

ListenableFuture<byte[]> getsAsync(long id,
                                 short nodeHint,
                                 StoreTransaction txn)

Retrieves a given data item asynchronously with a hint as to its owner in the cluster, and pins the shared (cached) instance to this node. What this means is that while other nodes will be able to read the same item, no node will be able to update it until until we end the transaction or release it.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

The asynchronous version of gets(long, short, StoreTransaction)

Parameters:

id - The item's ID.

nodeHint - The ID of the node the data item is probably owned by.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

A future that will return contents of the item.

getsAsync

ListenableFuture<Persistable> getsAsync(long id,
                                      short nodeHint,
                                      Persistable object,
                                      StoreTransaction txn)

Retrieves a given data asynchronously item into a Persistable with a hint as to its owner in the cluster, and pins the shared (cached) instance to this node. What this means is that while other nodes will be able to read the same item, no node will be able to update it until until we end the transaction or release it.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

The asynchronous version of gets(long, short, Persistable, StoreTransaction)

Parameters:

id - The item's ID.

nodeHint - The ID of the node the data item is probably owned by.

txn - The current transaction. May be null, in which case you must later call release(id).

object - The object into which the contents of the item will be written.

Returns:

A future that will return the passed object.

getsFromOwnerAsync

ListenableFuture<byte[]> getsFromOwnerAsync(long id,
                                          long ownerOf,
                                          StoreTransaction txn)

Retrieves a given data item asynchronously with a hint as to its owner in the cluster, and pins the shared (cached) instance to this node. What this means is that while other nodes will be able to update it until until we end the transaction or release it. Unlike the direct hint given in gets(long, short, StoreTransaction), the hinted node here is the owner of a given item.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

The asynchronous version of getsFromOwner(long, long, StoreTransaction)

Parameters:

id - The item's ID.

ownerOf - The ID of an item whose owner is probably the owner of the requested item as well.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

A future that will return contents of the item.

getsFromOwnerAsync

ListenableFuture<Persistable> getsFromOwnerAsync(long id,
                                               long ownerOf,
                                               Persistable object,
                                               StoreTransaction txn)

Retrieves a given data item asynchronously with a hint as to its owner in the cluster, and pins the shared (cached) instance to this node. What this means is that while other nodes will be able to read the same item, no node will be able to update it until until we end the transaction or release it.
Unlike the direct hint given in gets(long, short, Persistable, StoreTransaction), the hinted node here is the owner of a given item.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

The asynchronous version of getsFromOwner(long, long, Persistable, StoreTransaction)

Parameters:

id - The item's ID.

ownerOf - The ID of an item whose owner is probably the owner of the requested item as well.

object - The object into which the contents of the item will be written. May be null.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

A future that will return the passed object.

getxAsync

ListenableFuture<byte[]> getxAsync(long id,
                                 StoreTransaction txn)

Retrieves a given data item asynchronously, makes this node its exclusive owner, and pins it. What this means is that no other node will be able to read or update the same item until until we end the transaction or release it. it.

The asynchronous version of getx(long, StoreTransaction)

Parameters:

id - The item's ID.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

A future that will return contents of the item.

getxAsync

ListenableFuture<Persistable> getxAsync(long id,
                                      Persistable object,
                                      StoreTransaction txn)

Retrieves a given data item asynchronously into a Persistable, makes this node its exclusive owner, and pins it. What this means is that no other node will be able to read or update the same item until until we end the transaction or release it.

The asynchronous version of getx(long, Persistable, StoreTransaction)

Parameters:

id - The item's ID.

object - The object into which the contents of the item will be written. May be null.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

A future that will return the passed object.

getxAsync

ListenableFuture<byte[]> getxAsync(long id,
                                 short nodeHint,
                                 StoreTransaction txn)

Retrieves a given data item asynchronously with a hint as to its owner in the cluster, makes this node its exclusive owner, and pins it. What this means is that no other node will be able to read or update the same item until until we end the transaction or release it.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

The asynchronous version of getx(long, short, StoreTransaction)

Parameters:

id - The item's ID.

nodeHint - The ID of the node the data item is probably owned by.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

A future that will return contents of the item.

getxAsync

ListenableFuture<Persistable> getxAsync(long id,
                                      short nodeHint,
                                      Persistable object,
                                      StoreTransaction txn)

Retrieves a given data item asynchronously with a hint as to its owner in the cluster, makes this node its exclusive owner, and pins it. What this means is that no other node will be able to read or update the same item until we end the transaction or release it.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

The asynchronous version of getx(long, short, Persistable, StoreTransaction)

Parameters:

id - The item's ID.

nodeHint - The ID of the node the data item is probably owned by.

object - The object into which the contents of the item will be written. May be null.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

A future that will return the passed object.

getxFromOwnerAsync

ListenableFuture<byte[]> getxFromOwnerAsync(long id,
                                          long ownerOf,
                                          StoreTransaction txn)

Retrieves a given data item asynchronously with a hint as to its owner in the cluster, makes this node its exclusive owner, and pins it. What this means is that no other node will be able to read or update the same item until we end the transaction or release it. Unlike the direct hint given in getx(long, short, StoreTransaction), the hinted node here is the owner of a given item.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

The asynchronous version of getxFromOwner(long, long, StoreTransaction)

Parameters:

id - The item's ID.

ownerOf - The ID of an item whose owner is probably the owner of the requested item as well.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

A future that will return contents of the item.

getxFromOwnerAsync

ListenableFuture<Persistable> getxFromOwnerAsync(long id,
                                               long ownerOf,
                                               Persistable object,
                                               StoreTransaction txn)

Retrieves a given data item asynchronously with a hint as to its owner in the cluster, makes this node its exclusive owner, and pins it. What this means is that no other node will be able to read or update the same item until we end the transaction or release it. Unlike the direct hint given in getx(long, short, Persistable, StoreTransaction), the hinted node here is the owner of a given item.
If the item is indeed found on the hinted node, the retrieval performance might be superior. If not, the method will still work, but performance may be worse.

The asynchronous version of getxFromOwner(long, long, Persistable, StoreTransaction)

Parameters:

id - The item's ID.

ownerOf - The ID of an item whose owner is probably the owner of the requested item as well.

object - The object into which the contents of the item will be written. May be null.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

A future that will return the passed object.

setAsync

ListenableFuture<Void> setAsync(long id,
                              byte[] data,
                              StoreTransaction txn)

Gains ownership of an item and sets its contents asynchronously. The asynchronous version of set(long, byte[], StoreTransaction). Upon completion of the future returned by this method, the item will be pinned if and only if it had been pinned when the method was called.

Parameters:

id - The item's ID.

data - The contents to write into the item.

txn - The current transaction. May be null.

Returns:

A Void future (that always returns null) that waits for the completion of this operation.

setAsync

ListenableFuture<Void> setAsync(long id,
                              ByteBuffer data,
                              StoreTransaction txn)

Gains ownership of an item and sets its contents asynchronously. The asynchronous version of set(long, ByteBuffer, StoreTransaction). Upon completion of the future returned by this method, the item will be pinned if and only if it had been pinned when the method was called.

Parameters:

id - The item's ID.

data - The contents to write into the item.

txn - The current transaction. May be null.

Returns:

A Void future (that always returns null) that waits for the completion of this operation.

setAsync

ListenableFuture<Void> setAsync(long id,
                              Persistable object,
                              StoreTransaction txn)

Gains ownership of an item and sets its contents asynchronously. The asynchronous version of set(long, Persistable, StoreTransaction). Upon completion of the future returned by this method, the item will be pinned if and only if it had been pinned when the method was called.

Parameters:

id - The item's ID.

object - The contents to write into the item.

txn - The current transaction. May be null.

Returns:

A Void future (that always returns null) that waits for the completion of this operation.

invokeAsync

<T> ListenableFuture<T> invokeAsync(long id,
                                  LineFunction<T> function)

delAsync

ListenableFuture<Void> delAsync(long id,
                              StoreTransaction txn)

push

void push(long id,
        short... toNodes)

Makes the given item available in the given nodes' cache.
While this method is never necessary for the correct operation of the grid, in some special circumstances it might improve performance if we know that the given nodes will soon be interested in reading the item (e.g. as a result of a message we're about to send them).

Parameters:

id - The ID of item to push.

toNodes - The nodes to which the item is to be pushed.

pushx

void pushx(long id,
         short toNode)

Makes the given item available in the given node's cache, and makes that node the owner of the item.
While this method is never necessary for the correct operation of the grid, in some special circumstances it might improve performance if we know that the given node will soon be interested in reading or updating the item (e.g. as a result of a message we're about to send it).

Parameters:

id - The ID of item to push.

toNode - The node to which the item is to be pushed.

isPinned

boolean isPinned(long id)

Tests whether an item is pinned on this node.

Parameters:

id - The item's ID.

Returns:

true if the item is pinned; false otherwise.

tryPin

boolean tryPin(long id,
             ItemState state,
             StoreTransaction txn)
               throws IllegalStateException

Pins item if it can be done locally.

Parameters:

id - The item's ID.

state - can be X for writePin or S for readPin.

txn - The current transaction. May be null, in which case you must later call release(id).

Returns:

true if succeeded.

Throws:

IllegalStateException - if state is not X or S

getState

ItemState getState(long id)

Returns an item's state in the local store.

Parameters:

id - The item's ID.

Returns:

The item's state.

getVersion

long getVersion(long id)

CacheLine version

Parameters:

id - The item's ID.

send

void send(long id,
        Streamable msg)
          throws TimeoutException

Sends a message to an item, which will be received by CacheListener.messageReceived on the item's owning node.

Parameters:

id - The item's ID.

msg - The message.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

send

void send(long id,
        byte[] msg)
          throws TimeoutException

Sends a message to an item, which will be received by CacheListener.messageReceived on the item's owning node.

Parameters:

id - The item's ID.

msg - The message.

Throws:

TimeoutException - This exception is thrown if the operation has times-out.

sendAsync

ListenableFuture<Void> sendAsync(long id,
                               Streamable msg)

Sends a message to an item, which will be received by CacheListener.messageReceived on the item's owning node.

Parameters:

id - The item's ID.

msg - The message.

sendAsync

ListenableFuture<Void> sendAsync(long id,
                               byte[] msg)

Sends a message to an item, which will be received by CacheListener.messageReceived on the item's owning node.

Parameters:

id - The item's ID.

msg - The message.