org.openspaces.core
Interface GigaSpace

All Known Implementing Classes:

DefaultGigaSpace

public interface GigaSpace

Provides a simpler interface of both JavaSpace and GigaSpaces IJSpace extension utilizing GigaSpaces extended and simplified programming model.

Most operations revolve around the use of Objects allowing to use GigaSpaces support for POJOs. JavaSpaces Entries can also be used. Space operations (at the end) are delegated to the relevant operation of IJSpace.

Though this interface has a single implementation it is still important to work against the interface as it allows for simpler testing and mocking.

Transaction management is implicit and works in a declarative manner. Operations do not accept a transaction object, and will automatically use the TransactionProvider in order to acquire the current running transaction. If there is no current running transaction the operation will be executed without a transaction.

IJSpace can be acquired using getSpace() and in conjunction with getTxProvider() allows to work directly with IJSpace for low level API execution or other low level GigaSpaces components requiring direct access to IJSpace.

Operations throw a DataAccessException allowing for simplified development model as it is a runtime exception. The cause of the exception can be acquired from the GigaSpace exception.

Author:

kimchy

See Also:

IJSpace, Query, SQLQuery, TransactionProvider, DefaultGigaSpace, DataAccessException

Method Summary

void	clean() Cleans this space.
void	clear(Object template) Removes the entries that match the specified template and the specified transaction from this space.
int	count(Object template) Count any matching entry from the space.
int	count(Object template, int modifiers) Count any matching entry from the space.
net.jini.core.transaction.Transaction	getCurrentTransaction() Returns the current running transaction.
ExceptionTranslator	getExceptionTranslator() Returns the exception translator associated with this GigaSpace instnace.
int	getModifiersForIsolationLevel() Gets the isolation level from the current running transaction (enabling the usage of Spring declarative isolation level settings).
com.j_spaces.core.IJSpace	getSpace() Returns the IJSpace used by this GigaSpace implementation to delegate different space operations.
TransactionProvider	getTxProvider() Returns the transaction provider allowing to access the current running transaction.
IteratorBuilder	iterator() Returns an iterator builder allowing to configure and create a GSIterator over the Space.
<T> T	read(com.j_spaces.core.client.Query<T> template) Read any matching object from the space, blocking until one exists.
<T> T	read(com.j_spaces.core.client.Query<T> template, long timeout) Read any matching object from the space, blocking until one exists.
<T> T	read(com.j_spaces.core.client.Query<T> template, long timeout, int modifiers) Read any matching object from the space, blocking until one exists.
<T> T	read(T template) Read any matching object from the space, blocking until one exists.
<T> T	read(T template, long timeout) Read any matching object from the space, blocking until one exists.
<T> T	read(T template, long timeout, int modifiers) Read any matching object from the space, blocking until one exists.
<T> T	readIfExists(com.j_spaces.core.client.Query<T> template) Read any matching object from the space, returning null if there currently is none.
<T> T	readIfExists(com.j_spaces.core.client.Query<T> template, long timeout) Read any matching object from the space, returning null if there currently is none.
<T> T	readIfExists(com.j_spaces.core.client.Query<T> template, long timeout, int modifiers) Read any matching object from the space, returning null if there currently is none.
<T> T	readIfExists(T template) Read any matching object from the space, returning null if there currently is none.
<T> T	readIfExists(T template, long timeout) Read any matching object from the space, returning null if there currently is none.
<T> T	readIfExists(T template, long timeout, int modifiers) Read any matching object from the space, returning null if there currently is none.
<T> T[]	readMultiple(com.j_spaces.core.client.Query<T> template, int maxEntries) Read any matching entries from the space.
<T> T[]	readMultiple(com.j_spaces.core.client.Query<T> template, int maxEntries, int modifiers) Read any matching entries from the space.
<T> T[]	readMultiple(T template, int maxEntries) Read any matching entries from the space.
<T> T[]	readMultiple(T template, int maxEntries, int modifiers) Read any matching entries from the space.
Object	snapshot(Object entry) The process of serializing an entry for transmission to a JavaSpaces service will be identical if the same entry is used twice.
<T> T	take(com.j_spaces.core.client.Query<T> template) Take (remove) any matching entry from the space, blocking until one exists.
<T> T	take(com.j_spaces.core.client.Query<T> template, long timeout) Take (remove) any matching entry from the space, blocking until one exists.
<T> T	take(T template) Take (remove) any matching entry from the space, blocking until one exists.
<T> T	take(T template, long timeout) Take (remove) any matching entry from the space, blocking until one exists.
<T> T	takeIfExists(com.j_spaces.core.client.Query<T> template) Take (remove) any matching entry from the space, blocking until one exists.
<T> T	takeIfExists(com.j_spaces.core.client.Query<T> template, long timeout) Take (remove) any matching entry from the space, blocking until one exists.
<T> T	takeIfExists(T template) Take (remove) any matching entry from the space, blocking until one exists.
<T> T	takeIfExists(T template, long timeout) Take (remove) any matching entry from the space, blocking until one exists.
<T> T[]	takeMultiple(com.j_spaces.core.client.Query<T> template, int maxEntries) Takes (removes) all the entries matching the specified template from this space.
<T> T[]	takeMultiple(T template, int maxEntries) Takes (removes) all the entries matching the specified template from this space.
<T> Object[]	updateMultiple(T[] entries, long[] leases)
<T> Object[]	updateMultiple(T[] entries, long[] leases, int updateModifiers) Same as a single update but for a group of entities sharing the same transaction (if any), applied with the same operation modifier (or default Modifiers.NONE).
<T> com.j_spaces.core.LeaseContext<T>	write(T entry) Writes a new object to the space, returning its LeaseContext.
<T> com.j_spaces.core.LeaseContext<T>	write(T entry, long lease) Writes a new object to the space, returning its LeaseContext.
<T> com.j_spaces.core.LeaseContext<T>	write(T entry, long lease, long timeout, int modifiers) Writes a new object to the space, returning its LeaseContext.
<T> com.j_spaces.core.LeaseContext<T>[]	writeMultiple(T[] entries) Writes the specified entries to this space.
<T> com.j_spaces.core.LeaseContext<T>[]	writeMultiple(T[] entries, long lease) Writes the specified entries to this space.

Method Detail

getSpace

com.j_spaces.core.IJSpace getSpace()

Returns the IJSpace used by this GigaSpace implementation to delegate different space operations.

Allows to execute space operations that are not exposed by this interface, as well as using it as a parameter to other low level GigaSpace components.

If a transaction object is required for low level operations (as low level operations do not have declarative transaction ex) the getTxProvider() should be used to acquire the current running transaction.

getTxProvider

TransactionProvider getTxProvider()

Returns the transaction provider allowing to access the current running transaction. Allows to execute low level IJSpace operations that requires explicit transaction object.

getCurrentTransaction

net.jini.core.transaction.Transaction getCurrentTransaction()

Returns the current running transaction. Can be null if no transaction is in progress.

getExceptionTranslator

ExceptionTranslator getExceptionTranslator()

Returns the exception translator associated with this GigaSpace instnace.

getModifiersForIsolationLevel

int getModifiersForIsolationLevel()

Gets the isolation level from the current running transaction (enabling the usage of Spring declarative isolation level settings). If there is no transaction in progress or the transaction isolation is TransactionDefinition.ISOLATION_DEFAULT will use the default isolation level associated with this class.

clean

void clean()
           throws DataAccessException

Cleans this space. The side-effects of cleaning the space are:

• all entries and templates are deleted.
• all storage adapter contexts are closed.
• all engine threads are terminated.
• the engine re-initializes itself.

Throws:

DataAccessException

See Also:

IServerAdmin.clean()

clear

void clear(Object template)
           throws DataAccessException

Removes the entries that match the specified template and the specified transaction from this space.

If the clear operation conducted without transaction (null as value) it will clear all entries that are not under transaction. Therefore entries under transaction would not be removed from the space.

The clear operation supports inheritance, therefore template class matching objects and its sub classes matching objects are part of the candidates population to be removed from the space. You can in fact clean all space objects (that are not under transaction) by calling: gigaSpace.clear(null).

Notice: The clear operation does not remove notify templates i.e. registration for notifications.

Parameters:

template - the template to use for matching

Throws:

DataAccessException

See Also:

IPojoSpace.clear(Object,net.jini.core.transaction.Transaction)

count

int count(Object template)
          throws DataAccessException

Count any matching entry from the space. If a running within a transaction will count all the entries visible under the transaction.

Parameters:

template - The template used for matching. Matching is done against the template with null fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").

Returns:

The number of matching entries

Throws:

DataAccessException

See Also:

IPojoSpace.count(Object,net.jini.core.transaction.Transaction)

count

int count(Object template,
          int modifiers)
          throws DataAccessException

Count any matching entry from the space. If a running within a transaction will count all the entries visible under the transaction.

Allows to specify modifiers using ReadModifiers which allows to programmatically control the isolation level this count operation will be performed under.

Parameters:

template - The template used for matching. Matching is done against the template with null fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").

modifiers - one or a union of ReadModifiers.

Returns:

The number of matching entries

Throws:

DataAccessException

snapshot

Object snapshot(Object entry)
                throws DataAccessException

The process of serializing an entry for transmission to a JavaSpaces service will be identical if the same entry is used twice. This is most likely to be an issue with templates that are used repeatedly to search for entries with read or take. The client-side implementations of read and take cannot reasonably avoid this duplicated effort, since they have no efficient way of checking whether the same template is being used without intervening modification. The snapshot method gives the JavaSpaces service implementor a way to reduce the impact of repeated use of the same entry. Invoking snapshot with an Entry will return another Entry object that contains a snapshot of the original entry. Using the returned snapshot entry is equivalent to using the unmodified original entry in all operations on the same JavaSpaces service. Modifications to the original entry will not affect the snapshot. You can snapshot a null template; snapshot may or may not return null given a null template. The entry returned from snapshot will be guaranteed equivalent to the original unmodified object only when used with the space. Using the snapshot with any other JavaSpaces service will generate an IllegalArgumentException unless the other space can use it because of knowledge about the JavaSpaces service that generated the snapshot. The snapshot will be a different object from the original, may or may not have the same hash code, and equals may or may not return true when invoked with the original object, even if the original object is unmodified. A snapshot is guaranteed to work only within the virtual machine in which it was generated. If a snapshot is passed to another virtual machine (for example, in a parameter of an RMI call), using it--even with the same JavaSpaces service--may generate an IllegalArgumentException.

Parameters:

entry - The entry to snapshot

Returns:

The snapshot

Throws:

DataAccessException

See Also:

IPojoSpace.snapshot(Object)

read

<T> T read(T template)
       throws DataAccessException

Read any matching object from the space, blocking until one exists. Return null if the timeout expires.

Note, the timeout is the default timeout this interface is configured with (using its factory) and defaults to JavaSpace.NO_WAIT.

Parameters:

template - The template used for matching. Matching is done against template with null fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").

Returns:

A copy of the object read from the space.

Throws:

DataAccessException

See Also:

IPojoSpace.read(Object,net.jini.core.transaction.Transaction,long)

read

<T> T read(T template,
           long timeout)
       throws DataAccessException

Read any matching object from the space, blocking until one exists. Return null if the timeout expires.

Parameters:

template - The template used for matching. Matching is done against template with null fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").

timeout - How long the client is willing to wait for a transactionally proper matching object. A timeout of JavaSpace.NO_WAIT means to wait no time at all; this is equivalent to a wait of zero.

Returns:

A copy of the object read from the space.

Throws:

DataAccessException

See Also:

IPojoSpace.read(Object,net.jini.core.transaction.Transaction,long)

read

<T> T read(T template,
           long timeout,
           int modifiers)
       throws DataAccessException

Read any matching object from the space, blocking until one exists. Return null if the timeout expires.

Overloads read(Object,long) by adding a modifiers parameter. Equivalent when called with the default modifier - ReadModifiers.REPEATABLE_READ. Modifiers are used to define the behavior of a read operation.

Parameters:

template - The template used for matching. Matching is done against template with null fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").

timeout - How long the client is willing to wait for a transactionally proper matching object. A timeout of JavaSpace.NO_WAIT means to wait no time at all; this is equivalent to a wait of zero.

modifiers - one or a union of ReadModifiers.

Returns:

A copy of the object read from the space.

Throws:

DataAccessException

See Also:

IPojoSpace.read(Object,net.jini.core.transaction.Transaction,long,int)

read

<T> T read(com.j_spaces.core.client.Query<T> template)
       throws DataAccessException

Read any matching object from the space, blocking until one exists. Return null if the timeout expires.

Note, the timeout is the default timeout this interface is configured with (using its factory) and defaults to JavaSpace.NO_WAIT.

Parameters:

template - A query to be executed against the space. Most common one is SQLQuery.

Returns:

A copy of the object read from the space.

Throws:

DataAccessException

See Also:

IPojoSpace.read(Object,net.jini.core.transaction.Transaction,long)

read

<T> T read(com.j_spaces.core.client.Query<T> template,
           long timeout)
       throws DataAccessException

Read any matching object from the space, blocking until one exists. Return null if the timeout expires.

Parameters:

template - A query to be executed against the space. Most common one is SQLQuery.

timeout - How long the client is willing to wait for a transactionally proper matching object. A timeout of JavaSpace.NO_WAIT means to wait no time at all; this is equivalent to a wait of zero.

Returns:

A copy of the object read from the space.

Throws:

DataAccessException

See Also:

IPojoSpace.read(Object,net.jini.core.transaction.Transaction,long)

read

<T> T read(com.j_spaces.core.client.Query<T> template,
           long timeout,
           int modifiers)
       throws DataAccessException

Read any matching object from the space, blocking until one exists. Return null if the timeout expires.

Overloads read(Object,long) by adding a modifiers parameter. Equivalent when called with the default modifier - ReadModifiers.REPEATABLE_READ. Modifiers are used to define the behavior of a read operation.

Parameters:

template - A query to be executed against the space. Most common one is SQLQuery.

timeout - How long the client is willing to wait for a transactionally proper matching object. A timeout of JavaSpace.NO_WAIT means to wait no time at all; this is equivalent to a wait of zero.

modifiers - one or a union of ReadModifiers.

Returns:

A copy of the object read from the space.

Throws:

DataAccessException

See Also:

IPojoSpace.read(Object,net.jini.core.transaction.Transaction,long,int)

readIfExists

<T> T readIfExists(T template)
               throws DataAccessException

Read any matching object from the space, returning null if there currently is none. Matching and timeouts are done as in read, except that blocking in this call is done only if necessary to wait for transactional state to settle.

Note, the timeout is the default timeout this interface is configured with (using its factory) and defaults to JavaSpace.NO_WAIT.

Parameters:

template - The template used for matching. Matching is done against the template with null fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").

Returns:

A copy of the object read from the space.

Throws:

DataAccessException

See Also:

IPojoSpace.readIfExists(Object,net.jini.core.transaction.Transaction,long)

readIfExists

<T> T readIfExists(T template,
                   long timeout)
               throws DataAccessException

Read any matching object from the space, returning null if there currently is none. Matching and timeouts are done as in read, except that blocking in this call is done only if necessary to wait for transactional state to settle.

Parameters:

template - The template used for matching. Matching is done against template with null fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").

timeout - How long the client is willing to wait for a transactionally proper matching object. A timeout of JavaSpace.NO_WAIT means to wait no time at all; this is equivalent to a wait of zero.

Returns:

A copy of the object read from the space.

Throws:

DataAccessException

See Also:

IPojoSpace.readIfExists(Object,net.jini.core.transaction.Transaction,long)

readIfExists

<T> T readIfExists(T template,
                   long timeout,
                   int modifiers)
               throws DataAccessException

Read any matching object from the space, returning null if there currently is none. Matching and timeouts are done as in read, except that blocking in this call is done only if necessary to wait for transactional state to settle.

Overloads read(Object,long) by adding a modifiers parameter. Equivalent when called with the default modifier - ReadModifiers.REPEATABLE_READ. Modifiers are used to define the behavior of a read operation.

Parameters:

template - The template used for matching. Matching is done against template with null fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").

timeout - How long the client is willing to wait for a transactionally proper matching object. A timeout of JavaSpace.NO_WAIT means to wait no time at all; this is equivalent to a wait of zero.

modifiers - one or a union of ReadModifiers.

Returns:

A copy of the object read from the space.

Throws:

DataAccessException

See Also:

IJSpace.readIfExists(net.jini.core.entry.Entry,net.jini.core.transaction.Transaction,long,int)

readIfExists

<T> T readIfExists(com.j_spaces.core.client.Query<T> template)
               throws DataAccessException

Read any matching object from the space, returning null if there currently is none. Matching and timeouts are done as in read, except that blocking in this call is done only if necessary to wait for transactional state to settle.

Note, the timeout is the default timeout this interface is configured with (using its factory) and defaults to JavaSpace.NO_WAIT.

Parameters:

template - A query to be executed against the space. Most common one is SQLQuery.

Returns:

A copy of the object read from the space.

Throws:

DataAccessException

See Also:

IPojoSpace.readIfExists(Object,net.jini.core.transaction.Transaction,long)

readIfExists

<T> T readIfExists(com.j_spaces.core.client.Query<T> template,
                   long timeout)
               throws DataAccessException

Read any matching object from the space, returning null if there currently is none. Matching and timeouts are done as in read, except that blocking in this call is done only if necessary to wait for transactional state to settle.

Parameters:

template - A query to be executed against the space. Most common one is SQLQuery.

timeout - How long the client is willing to wait for a transactionally proper matching object. A timeout of JavaSpace.NO_WAIT means to wait no time at all; this is equivalent to a wait of zero.

Returns:

A copy of the object read from the space.

Throws:

DataAccessException

See Also:

IPojoSpace.readIfExists(Object,net.jini.core.transaction.Transaction,long)

readIfExists

<T> T readIfExists(com.j_spaces.core.client.Query<T> template,
                   long timeout,
                   int modifiers)
               throws DataAccessException

Read any matching object from the space, returning null if there currently is none. Matching and timeouts are done as in read, except that blocking in this call is done only if necessary to wait for transactional state to settle.

Overloads read(Object,long) by adding a modifiers parameter. Equivalent when called with the default modifier - ReadModifiers.REPEATABLE_READ. Modifiers are used to define the behavior of a read operation.

Parameters:

template - A query to be executed against the space. Most common one is SQLQuery.

timeout - How long the client is willing to wait for a transactionally proper matching object. A timeout of JavaSpace.NO_WAIT means to wait no time at all; this is equivalent to a wait of zero.

modifiers - one or a union of ReadModifiers.

Returns:

A copy of the object read from the space.

Throws:

DataAccessException

See Also:

IJSpace.readIfExists(net.jini.core.entry.Entry,net.jini.core.transaction.Transaction,long,int)

readMultiple

<T> T[] readMultiple(T template,
                     int maxEntries)
                 throws DataAccessException

Read any matching entries from the space. Matching is done as in read without timeout (JavaSpace.NO_WAIT). Returns an array with matches bound by maxEntries. Returns an empty array if no match was found.

Parameters:

template - The template used for matching. Matching is done against the template with null fields being. wildcards ("match anything") other fields being values ("match exactly on the serialized form"). The template can also be one of the different Query classes

maxEntries - A limit on the number of entries to be returned. Use Integer.MAX_VALUE for the uppermost limit.

Returns:

A copy of the entries read from the space.

Throws:

DataAccessException

See Also:

IPojoSpace.readMultiple(Object,net.jini.core.transaction.Transaction,int)

readMultiple

<T> T[] readMultiple(com.j_spaces.core.client.Query<T> template,
                     int maxEntries)
                 throws DataAccessException

Read any matching entries from the space. Matching is done as in read without timeout (JavaSpace.NO_WAIT). Returns an array with matches bound by maxEntries. Returns an empty array if no match was found.

Parameters:

template - The template used for matching. Matching is done against the template with null fields being. wildcards ("match anything") other fields being values ("match exactly on the serialized form"). The template can also be one of the different Query classes

maxEntries - A limit on the number of entries to be returned. Use Integer.MAX_VALUE for the uppermost limit.

Returns:

A copy of the entries read from the space.

Throws:

DataAccessException

See Also:

IPojoSpace.readMultiple(Object,net.jini.core.transaction.Transaction,int)

readMultiple

<T> T[] readMultiple(T template,
                     int maxEntries,
                     int modifiers)
                 throws DataAccessException

Read any matching entries from the space. Matching is done as in read without timeout (JavaSpace.NO_WAIT). Returns an array with matches bound by maxEntries. Returns an empty array if no match was found.

Overloads readMultiple(Object,int) by adding a modifiers parameter. Equivalent when called with the default modifier - ReadModifiers.REPEATABLE_READ. Modifiers are used to define the behavior of a read operation.

Parameters:

template - The template used for matching. Matching is done against the template with null fields being. wildcards ("match anything") other fields being values ("match exactly on the serialized form"). The template can also be one of the different Query classes

maxEntries - A limit on the number of entries to be returned. Use Integer.MAX_VALUE for the uppermost limit.

modifiers - One or a union of ReadModifiers.

Returns:

A copy of the entries read from the space.

Throws:

DataAccessException

See Also:

IPojoSpace.readMultiple(Object,net.jini.core.transaction.Transaction,int)

readMultiple

<T> T[] readMultiple(com.j_spaces.core.client.Query<T> template,
                     int maxEntries,
                     int modifiers)
                 throws DataAccessException

Read any matching entries from the space. Matching is done as in read without timeout (JavaSpace.NO_WAIT). Returns an array with matches bound by maxEntries. Returns an empty array if no match was found.

Overloads readMultiple(Object,int) by adding a modifiers parameter. Equivalent when called with the default modifier - ReadModifiers.REPEATABLE_READ. Modifiers are used to define the behavior of a read operation.

Parameters:

template - The template used for matching. Matching is done against the template with null fields being. wildcards ("match anything") other fields being values ("match exactly on the serialized form"). The template can also be one of the different Query classes

maxEntries - A limit on the number of entries to be returned. Use Integer.MAX_VALUE for the uppermost limit.

modifiers - One or a union of ReadModifiers.

Returns:

A copy of the entries read from the space.

Throws:

DataAccessException

See Also:

IPojoSpace.readMultiple(Object,net.jini.core.transaction.Transaction,int)

take

<T> T take(T template)
       throws DataAccessException

Take (remove) any matching entry from the space, blocking until one exists. Return null if the timeout expires.

Note, the timeout is the default timeout this interface is configured with (using its factory) and defaults to JavaSpace.NO_WAIT.

Parameters:

template - The template used for matching. Matching is done against the template with null fields being wildcards ( "match anything") other fields being values ("match exactly on the serialized form").

Returns:

A removed entry from the space

Throws:

DataAccessException

take

<T> T take(T template,
           long timeout)
       throws DataAccessException

Take (remove) any matching entry from the space, blocking until one exists. Return null if the timeout expires.

Parameters:

template - The template used for matching. Matching is done against the template with null fields being wildcards ( "match anything") other fields being values ("match exactly on the serialized form").

timeout - How long the client is willing to wait for a transactionally proper matching entry. A timeout of JavaSpace.NO_WAIT means to wait no time at all; this is equivalent to a wait of zero.

Returns:

A removed entry from the space

Throws:

DataAccessException

take

<T> T take(com.j_spaces.core.client.Query<T> template)
       throws DataAccessException

Take (remove) any matching entry from the space, blocking until one exists. Return null if the timeout expires.

Note, the timeout is the default timeout this interface is configured with (using its factory) and defaults to JavaSpace.NO_WAIT.

Parameters:

template - A query to be executed against the space. Most common one is SQLQuery.

Returns:

A removed entry from the space

Throws:

DataAccessException

take

<T> T take(com.j_spaces.core.client.Query<T> template,
           long timeout)
       throws DataAccessException

Take (remove) any matching entry from the space, blocking until one exists. Return null if the timeout expires.

Parameters:

template - A query to be executed against the space. Most common one is SQLQuery.

timeout - How long the client is willing to wait for a transactionally proper matching entry. A timeout of JavaSpace.NO_WAIT means to wait no time at all; this is equivalent to a wait of zero.

Returns:

A removed entry from the space

Throws:

DataAccessException

takeIfExists

<T> T takeIfExists(T template)
               throws DataAccessException

Take (remove) any matching entry from the space, blocking until one exists. Return null if the timeout expires. Matching and timeouts are done as in take, except that blocking in this call is done only if necessary to wait for transactional state to settle.

Note, the timeout is the default timeout this interface is configured with (using its factory) and defaults to JavaSpace.NO_WAIT.

Parameters:

template - The template used for matching. Matching is done against the template with null fields being wildcards ( "match anything") other fields being values ("match exactly on the serialized form").

Returns:

A removed entry from the space

Throws:

DataAccessException

takeIfExists

<T> T takeIfExists(T template,
                   long timeout)
               throws DataAccessException

Take (remove) any matching entry from the space, blocking until one exists. Return null if the timeout expires. Matching and timeouts are done as in take, except that blocking in this call is done only if necessary to wait for transactional state to settle.

Parameters:

template - The template used for matching. Matching is done against the template with null fields being wildcards ( "match anything") other fields being values ("match exactly on the serialized form").

timeout - How long the client is willing to wait for a transactionally proper matching entry. A timeout of JavaSpace.NO_WAIT means to wait no time at all; this is equivalent to a wait of zero.

Returns:

A removed entry from the space

Throws:

DataAccessException

takeIfExists

<T> T takeIfExists(com.j_spaces.core.client.Query<T> template)
               throws DataAccessException

Take (remove) any matching entry from the space, blocking until one exists. Return null if the timeout expires. Matching and timeouts are done as in take, except that blocking in this call is done only if necessary to wait for transactional state to settle.

Note, the timeout is the default timeout this interface is configured with (using its factory) and defaults to JavaSpace.NO_WAIT.

Parameters:

template - A query to be executed against the space. Most common one is SQLQuery.

Returns:

A removed entry from the space

Throws:

DataAccessException

See Also:

IPojoSpace.takeIfExists(Object,net.jini.core.transaction.Transaction,long)

takeIfExists

<T> T takeIfExists(com.j_spaces.core.client.Query<T> template,
                   long timeout)
               throws DataAccessException

Take (remove) any matching entry from the space, blocking until one exists. Return null if the timeout expires. Matching and timeouts are done as in take, except that blocking in this call is done only if necessary to wait for transactional state to settle.

Parameters:

template - A query to be executed against the space. Most common one is SQLQuery.

timeout - How long the client is willing to wait for a transactionally proper matching entry. A timeout of JavaSpace.NO_WAIT means to wait no time at all; this is equivalent to a wait of zero.

Returns:

A removed entry from the space

Throws:

DataAccessException

See Also:

IPojoSpace.takeIfExists(Object,net.jini.core.transaction.Transaction,long)

takeMultiple

<T> T[] takeMultiple(T template,
                     int maxEntries)
                 throws DataAccessException

Takes (removes) all the entries matching the specified template from this space.

Parameters:

template - The template used for matching. Matching is done against the template with null fields being. wildcards ("match anything") other fields being values ("match exactly on the serialized form"). The template can also be one of the different Query classes

maxEntries - A limit on the number of entries to be returned. Use Integer.MAX_VALUE for the uppermost limit.

Returns:

Removed matched entries from the space

Throws:

DataAccessException

See Also:

IPojoSpace.takeMultiple(Object,net.jini.core.transaction.Transaction,int)

takeMultiple

<T> T[] takeMultiple(com.j_spaces.core.client.Query<T> template,
                     int maxEntries)
                 throws DataAccessException

Takes (removes) all the entries matching the specified template from this space.

Parameters:

template - The template used for matching. Matching is done against the template with null fields being. wildcards ("match anything") other fields being values ("match exactly on the serialized form"). The template can also be one of the different Query classes

maxEntries - A limit on the number of entries to be returned. Use Integer.MAX_VALUE for the uppermost limit.

Returns:

Removed matched entries from the space

Throws:

DataAccessException

See Also:

IPojoSpace.takeMultiple(Object,net.jini.core.transaction.Transaction,int)

write

<T> com.j_spaces.core.LeaseContext<T> write(T entry)
                                        throws DataAccessException

Writes a new object to the space, returning its LeaseContext.

By default uses the UpdateModifiers.UPDATE_OR_WRITE modifier (see write(Object,long,long,int). In order to force the operation to perform "write" only (a bit more performant), the UpdateModifiers.WRITE_ONLY modifier can be used resulting in an EntryAlreadyInSpaceException if the entry already exists in the space (it must have an id for this exception to be raised).

If the object has a primary key that isn't auto - generated, and the modifiers value is one of UpdateModifiers.UPDATE_OR_WRITE, UpdateModifiers.UPDATE_ONLY or UpdateModifiers.PARTIAL_UPDATE, it will call to the update method, returning a LeaseContext holder. This lease is unknown to the grantor, unless an actual 'write' was performed.

The entry will be written using the default lease this interface is configured with (using the its factory). In order to explicitly define the lease, please use write(Object,long).

Parameters:

entry - The entry to write to the space

Returns:

A usable Lease on a successful write, or null if performed with the proxy configured with NoWriteLease flag.

when UpdateModifiers.UPDATE_OR_WRITE modifier is applied, LeaseContext.getObject() returns null on a successful write or the previous value - on successful update. UpdateOperationTimeoutException is thrown if timeout occurred while trying to update the object.

Throws:

DataAccessException

See Also:

IPojoSpace.write(Object,net.jini.core.transaction.Transaction,long)

write

<T> com.j_spaces.core.LeaseContext<T> write(T entry,
                                            long lease)
                                        throws DataAccessException

Writes a new object to the space, returning its LeaseContext.

By default uses the UpdateModifiers.UPDATE_OR_WRITE modifier (see write(Object,long,long,int). In order to force the operation to perform "write" only (a bit more performant), the UpdateModifiers.WRITE_ONLY modifier can be used resulting in an EntryAlreadyInSpaceException if the entry already exists in the space (it must have an id for this exception to be raised).

If the object has a primary key that isn't auto - generated, and the modifiers value is one of UpdateModifiers.UPDATE_OR_WRITE, UpdateModifiers.UPDATE_ONLY or UpdateModifiers.PARTIAL_UPDATE, it will call to the update method, returning a LeaseContext holder. This lease is unknown to the grantor, unless an actual 'write' was performed.

Parameters:

entry - The entry to write to the space

lease - The lease the entry will be written with, in milliseconds.

Returns:

A usable Lease on a successful write, or null if performed with the proxy configured with NoWriteLease flag.

when UpdateModifiers.UPDATE_OR_WRITE modifier is applied, LeaseContext.getObject() returns null on a successful write or the previous value - on successful update. UpdateOperationTimeoutException is thrown if timeout occurred while trying to update the object.

Throws:

DataAccessException

See Also:

IPojoSpace.write(Object,net.jini.core.transaction.Transaction,long)

write

<T> com.j_spaces.core.LeaseContext<T> write(T entry,
                                            long lease,
                                            long timeout,
                                            int modifiers)
                                        throws DataAccessException

Writes a new object to the space, returning its LeaseContext.

By default uses the UpdateModifiers.UPDATE_OR_WRITE modifier (see write(Object,long,long,int). In order to force the operation to perform "write" only (a bit more performant), the UpdateModifiers.WRITE_ONLY modifier can be used resulting in an EntryAlreadyInSpaceException if the entry already exists in the space (it must have an id for this exception to be raised).

If the object has a primary key that isn't auto - generated, and the modifiers value is one of UpdateModifiers.UPDATE_OR_WRITE, UpdateModifiers.UPDATE_ONLY or UpdateModifiers.PARTIAL_UPDATE, it will call to the update method, returning a LeaseContext holder. This lease is unknown to the grantor, unless an actual 'write' was performed.

Parameters:

entry - The entry to write to the space

lease - The lease the entry will be written with, in milliseconds.

Returns:

A usable Lease on a successful write, or null if performed with the proxy configured with NoWriteLease flag.

when UpdateModifiers.UPDATE_OR_WRITE modifier is applied, LeaseContext.getObject() returns null on a successful write or the previous value - on successful update. UpdateOperationTimeoutException is thrown if timeout occurred while trying to update the object.

Throws:

DataAccessException

See Also:

IPojoSpace.write(Object,net.jini.core.transaction.Transaction,long)

writeMultiple

<T> com.j_spaces.core.LeaseContext<T>[] writeMultiple(T[] entries)
                                                  throws DataAccessException

Writes the specified entries to this space.

The entry will be written using the default lease this interface is configured with (using the its factory). In order to explicitly define the lease, please use writeMultiple(Object[],long).

Parameters:

entries - The entries to write to the space.

Returns:

Leases for the written entries

Throws:

DataAccessException

See Also:

IPojoSpace.writeMultiple(Object[],net.jini.core.transaction.Transaction,long)

writeMultiple

<T> com.j_spaces.core.LeaseContext<T>[] writeMultiple(T[] entries,
                                                      long lease)
                                                  throws DataAccessException

Writes the specified entries to this space.

Parameters:

entries - The entries to write to the space.

lease - The lease the entry will be written with, in milliseconds.

Returns:

Leases for the written entries

Throws:

DataAccessException

See Also:

IPojoSpace.writeMultiple(Object[],net.jini.core.transaction.Transaction,long)

updateMultiple

<T> Object[] updateMultiple(T[] entries,
                            long[] leases)
                        throws DataAccessException

Throws:

DataAccessException

updateMultiple

<T> Object[] updateMultiple(T[] entries,
                            long[] leases,
                            int updateModifiers)
                        throws DataAccessException

Same as a single update but for a group of entities sharing the same transaction (if any), applied with the same operation modifier (or default Modifiers.NONE). The semantics of a single update and a batch update are similar - the return value for each corresponds to it's cell in the returned array. see 'returns' for possible return values.

Parameters:

entries - the array of objects containing the new values, each entry must contain its UID.

leases - The lease time of the updated objects, 0 means retain the original lease.

updateModifiers - operation modifiers, values from UpdateModifiers.

Returns:

array of objects which correspond to the input entries array. An object can be either one of:

• an Entry, if the update was successful
• null - if timeout occurred after waiting for a transactional proper matching entry
• an Exception object, in case of an exception
  • EntryNotInSpaceException - in case the entry does not exist
  • SpaceOptimisticLockingFailureException - in case updating with non-latest version
• when UpdateModifiers.UPDATE_OR_WRITE modifier is applied,
  • null - if write was successful,
  • previous value - on successful update, or
  • an Exception Object, including OperationTimeoutException - thrown if timeout occurred.

Throws:

DataAccessException

iterator

IteratorBuilder iterator()

Returns an iterator builder allowing to configure and create a GSIterator over the Space.