com.gigaspaces.client
Interface IPojoSpace

All Known Subinterfaces:

IJSpace

public interface IPojoSpace

This interface represents the application view of a GigaSpace instance. It is implemented by all the Space Proxies (Embedded, Remote, Cluster and LocalCache).

When client receives a proxy to the space from the Lookup Service (see SpaceFinder, this proxy implements this interface, and therefore may be casted to this interface if specific GigaSpaces methods (such as count(Object, Transaction)) are required. The POJO UID generation and usage scenarios:
Scenario A: Adding a POJO to the Space using methods: write(), writeMultiple() Space UID for POJO can be created in three different ways:
1. The POJO object that has no key property declared. In that case, the ExternalEntry is created with empty UID. The space gets the ExternalEntry which was created and inserts it into the space. The space then generates UID for that ExternalEntry instance and writes it into the space.
2. The POJO has property which declared as a key - The converter takes the value of that property and calls the method getUID( Object name) in ClientUIDHandler class. That method returns a UID which is generated using the property value. The UID is set to the ExternalEntry object.

3. The POJO has property which declared as a key and marked as auto generate - The property must be from type java.lang.String. The ExternalEntry is created with an empty UID. The space gets the ExternalEntry which was created and inserts it into the space. The space then generates UID for that ExternalEntry instance and writes it into the space. The generated UID then been set into the POJO instance using �set� property method.

Scenario B: Fetching a POJO from the space using methods read(), readMultiple(), readIfExists(), take(), takeMultiple(), takeIfExists() etc:

1. When the POJO has no key property declared, it then will be returned without any UID. It means that only read() and write() operations can be executed on the POJO and NOT an update().

2. When the POJO has a key property declared, it then will be returned with the source value of the property but without the generated UID. The POJO can not approach the UID which was generated by the space. 3. The POJO has a property which declared as a key and auto generate - The space returns the POJO with the generated UID into the property.

Since:

6.1

Author:

Guy Korland

See Also:

IJSpaceContainer, SpaceFinder

Method Summary

void	clear(Object template, net.jini.core.transaction.Transaction transaction) Removes the objects that match the specified template and the specified transaction from this space.
int	count(Object template, net.jini.core.transaction.Transaction transaction) Count any matching object from the space, visible under the specified transaction.
int	count(Object template, net.jini.core.transaction.Transaction transaction, int modifiers) Count (according to the modifiers) any matching object from the space, visible under the specified transaction.
IProxyAdmin	getProxyAdmin() Returns a proxy admin.
IServerAdmin	getServerAdmin() Return a server admin.
Object	read(Object template, net.jini.core.transaction.Transaction transaction, long timeout) Read any matching object from the space, blocking until one exists.
Object	read(Object template, net.jini.core.transaction.Transaction transaction, long timeout, int modifiers) Read (according to the modifiers) any matching object from the space, blocking until one exists.
Object	readIfExists(Object template, net.jini.core.transaction.Transaction transaction, long timeout) Read any matching object from the space, returning null if there currently is none.
Object	readIfExists(Object template, net.jini.core.transaction.Transaction transaction, long timeout, int modifiers) Read (according to the modifiers) any matching object from the space, returning null if there currently is none.
Object[]	readMultiple(Object template, net.jini.core.transaction.Transaction transaction, int limit) Read any matching objects from the space.
Object[]	readMultiple(Object template, net.jini.core.transaction.Transaction transaction, int limit, int modifiers) Read (according to the modifiers) any matching objects from the space.
Object	snapshot(Object object) The process of serializing an entry for transmission to a JavaSpaces service will be identical if the same entry is used twice.
Object	take(Object template, net.jini.core.transaction.Transaction transaction, long timeout) Take any matching entry from the space, blocking until one exists.
Object	takeIfExists(Object template, net.jini.core.transaction.Transaction transaction, long timeout) Take any matching object from the space, returning null if there currently is none.
Object[]	takeMultiple(Object template, net.jini.core.transaction.Transaction transaction, int limit) Takes all the entries matching the specified template from this space.
Object[]	takeMultiple(Object template, net.jini.core.transaction.Transaction txn, int limit, int modifiers) Takes all the entries matching the specified template from this space.
Object	update(Object updatedEntry, net.jini.core.transaction.Transaction transaction, long lease, long timeout) Equivalent to calling update(Object, Transaction, long, long, int) with modifiers (if any) set by IProxyAdmin.setUpdateModifiers(int).
Object	update(Object updatedEntry, net.jini.core.transaction.Transaction transaction, long lease, long timeout, int updateModifiers) An update operation against a space entity which it's UID is known, blocking if locked under another transaction.
Object[]	updateMultiple(Object[] entries, net.jini.core.transaction.Transaction transaction, long[] leases) Equivalent to calling updateMultiple(Object[], Transaction, long[], int) with modifiers (if any) set by IProxyAdmin.setUpdateModifiers(int).
Object[]	updateMultiple(Object[] objects, net.jini.core.transaction.Transaction transaction, 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 com.j_spaces.core.client.UpdateModifiers#NONE).
LeaseContext	write(Object object, net.jini.core.transaction.Transaction transaction, long lease) Equivalent to calling write(Object, Transaction, long, long, int) with the UpdateModifiers.UPDATE_OR_WRITE.
LeaseContext	write(Object object, net.jini.core.transaction.Transaction transaction, long lease, long timeout, int modifiers) Writes a new object to the space, returning its Lease.
LeaseContext[]	writeMultiple(Object[] objects, net.jini.core.transaction.Transaction transaction, long lease) Equivalent to calling #writeMultiple(Object[], Transaction, long, int) with modifier {@link com.j_spaces.core.client.UpdateModifiers#WRITE_ONLY}.
LeaseContext[]	writeMultiple(Object[] objects, net.jini.core.transaction.Transaction transaction, long lease, int updateModifiers) Same as a single write but for a group of entities sharing the same transaction (if any), applied with the same specified operation modifier.

Method Detail

count

int count(Object template,
          net.jini.core.transaction.Transaction transaction)
          throws net.jini.core.entry.UnusableEntryException,
                 net.jini.core.transaction.TransactionException,
                 RemoteException

Count any matching object from the space, visible under the specified transaction.

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").

transaction - The transaction (if any) under which to work.

Returns:

The number of matching objects.

Throws:

net.jini.core.entry.UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason

net.jini.core.transaction.TransactionException - if a transaction error occurs

RemoteException - if a communication error occurs

count

int count(Object template,
          net.jini.core.transaction.Transaction transaction,
          int modifiers)
          throws net.jini.core.entry.UnusableEntryException,
                 net.jini.core.transaction.TransactionException,
                 RemoteException

Count (according to the modifiers) any matching object from the space, visible under the specified transaction.

Overloads count(Object, Transaction) 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").

transaction - The transaction (if any) under which to work.

modifiers - one or a union of ReadModifiers.

Returns:

The number of matching objects.

Throws:

net.jini.core.entry.UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason

net.jini.core.transaction.TransactionException - if a transaction error occurs

RemoteException - if a communication error occurs

read

Object read(Object template,
            net.jini.core.transaction.Transaction transaction,
            long timeout)
            throws net.jini.core.entry.UnusableEntryException,
                   net.jini.core.transaction.TransactionException,
                   InterruptedException,
                   RemoteException

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

Overloads JavaSpace.read(Entry, Transaction, long) by replacing the Entry template with Object, to support Plain Old Java Object templates. Equivalent when called with an Entry cast to Object.

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").

transaction - The transaction (if any) under which to work.

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:

net.jini.core.entry.UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason

net.jini.core.transaction.TransactionException - if a transaction error occurs

InterruptedException - if the thread in which the read occurs is interrupted

RemoteException - if a communication error occurs

See Also:

JavaSpace.read(Entry, Transaction, long)

read

Object read(Object template,
            net.jini.core.transaction.Transaction transaction,
            long timeout,
            int modifiers)
            throws net.jini.core.entry.UnusableEntryException,
                   net.jini.core.transaction.TransactionException,
                   InterruptedException,
                   RemoteException

Read (according to the modifiers) any matching object from the space, blocking until one exists. Return null if the timeout expires.

Overloads read(Object, Transaction, 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").

transaction - The transaction (if any) under which to work.

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:

net.jini.core.entry.UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason

net.jini.core.transaction.TransactionException - if a transaction error occurs

InterruptedException - if the thread in which the read occurs is interrupted

RemoteException - if a communication error occurs

Since:

6.0

See Also:

read(Object, Transaction, long)

readIfExists

Object readIfExists(Object template,
                    net.jini.core.transaction.Transaction transaction,
                    long timeout)
                    throws net.jini.core.entry.UnusableEntryException,
                           net.jini.core.transaction.TransactionException,
                           InterruptedException,
                           RemoteException

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 JavaSpace.readIfExists(Entry, Transaction, long) by replacing the Entry template with Object, to support Plain Old Java Object templates. Equivalent when called with an Entry cast to Object.

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").

transaction - The transaction (if any) under which to work.

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:

net.jini.core.entry.UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason

net.jini.core.transaction.TransactionException - if a transaction error occurs

InterruptedException - if the thread in which the read occurs is interrupted

RemoteException - if a communication error occurs

See Also:

JavaSpace.readIfExists(Entry, Transaction, long), IJSpace.read(Entry, Transaction, long, int)

readIfExists

Object readIfExists(Object template,
                    net.jini.core.transaction.Transaction transaction,
                    long timeout,
                    int modifiers)
                    throws net.jini.core.entry.UnusableEntryException,
                           net.jini.core.transaction.TransactionException,
                           InterruptedException,
                           RemoteException

Read (according to the modifiers) 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 readIfExists(Object, Transaction, 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").

transaction - The transaction (if any) under which to work.

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:

net.jini.core.entry.UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason

net.jini.core.transaction.TransactionException - if a transaction error occurs

InterruptedException - if the thread in which the read occurs is interrupted

RemoteException - if a communication error occurs

Since:

6.0

See Also:

readIfExists(Object, Transaction, long), read(Object, Transaction, long, int)

readMultiple

Object[] readMultiple(Object template,
                      net.jini.core.transaction.Transaction transaction,
                      int limit)
                      throws net.jini.core.transaction.TransactionException,
                             net.jini.core.entry.UnusableEntryException,
                             RemoteException

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

Overloads #readMultiple(Entry, Transaction, int) by replacing the Entry template with Object, to support Plain Old Java Object templates. Equivalent when called with an Entry[] cast to Object[].

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").

transaction - The transaction (if any) under which to work.

limit - a limit on the number of objects to be returned. Use Integer.MAX_VALUE for the uppermost limit.

Returns:

a copy of the objects read from the space.

Throws:

net.jini.core.entry.UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason

net.jini.core.transaction.TransactionException - if a transaction error occurs

RemoteException - if a communication error occurs

See Also:

IJSpace.readMultiple(Entry, Transaction, int)

readMultiple

Object[] readMultiple(Object template,
                      net.jini.core.transaction.Transaction transaction,
                      int limit,
                      int modifiers)
                      throws net.jini.core.transaction.TransactionException,
                             net.jini.core.entry.UnusableEntryException,
                             RemoteException

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

Overloads readMultiple(Object, Transaction, 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 template with null fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").

transaction - The transaction (if any) under which to work.

limit - a limit on the number of objects to be returned. Use Integer.MAX_VALUE for the uppermost limit.

modifiers - one or a union of ReadModifiers.

Returns:

a copy of the objects read from the space.

Throws:

net.jini.core.entry.UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason

net.jini.core.transaction.TransactionException - if a transaction error occurs

RemoteException - if a communication error occurs

Since:

6.0

See Also:

readMultiple(Object, Transaction, int)

update

Object update(Object updatedEntry,
              net.jini.core.transaction.Transaction transaction,
              long lease,
              long timeout)
              throws net.jini.core.transaction.TransactionException,
                     net.jini.core.entry.UnusableEntryException,
                     RemoteException,
                     InterruptedException

Equivalent to calling update(Object, Transaction, long, long, int) with modifiers (if any) set by IProxyAdmin.setUpdateModifiers(int).

Parameters:

updatedEntry - the new value of the entry, must contain the UID.

transaction - The transaction under which to perform the operation.

lease - The lease time of the updated entry, 0 means retain the original lease

timeout - "IfExists" timeout

Returns:

returns the same as update(Object, Transaction, long, long, int) according to the set UpdateModifier. (see IProxyAdmin.setUpdateModifiers(int)

Throws:

net.jini.core.transaction.TransactionException - if a transaction error occurs

net.jini.core.entry.UnusableEntryException - if any serialized field of the entry being read cannot be deserialized for any reason

RemoteException - if a communication error occurs

InterruptedException - if the thread in which the read occurs is interrupted

IllegalArgumentException - if the lease time requested is not Lease.ANY and is negative

See Also:

update(Object, Transaction, long, long, int), UpdateModifiers, IProxyAdmin.setUpdateModifiers(int)

update

Object update(Object updatedEntry,
              net.jini.core.transaction.Transaction transaction,
              long lease,
              long timeout,
              int updateModifiers)
              throws net.jini.core.transaction.TransactionException,
                     net.jini.core.entry.UnusableEntryException,
                     RemoteException,
                     InterruptedException

An update operation against a space entity which it's UID is known, blocking if locked under another transaction. UID must be supplied either by implementing IMetaDataEntry or having one of the UID access methods:

      public void __setEntryUID(String inUid)
      public String __getEntryUID()
 

An update can be performed, with any of the modifiers listed in UpdateModifiers,

• UpdateModifiers.UPDATE_ONLY - pure update operation,
• UpdateModifiers.UPDATE_OR_WRITE - writes if absent or updates existing,
• UpdateModifiers.PARTIAL_UPDATE - updates only non-null fields
.

Transactions:
An update lock guarantees that you are the sole holder of a space entity. An update lock blocks all other requests for a read, take or update on this particular entity. An update will be blocked until timeout expires, returning a null result or until the lock has been released and acquired by this call.

Optimistic Locking:
With optimistic locking set, an update operation has a chance of failing (throwing EntryVersionConflictException) if it was performed on an obsolete copy. To enable Optimistic Locking with update, set IProxyAdmin.setOptimisticLocking(boolean).

Sample code:

 IJSpace aSpace = (IJSpace)SpaceFinder.find("jini://lookup-host/container-name/space-name");
 Message msg = new Message("Hello");
 Lease lease = aSpace.write(msg, null, Lease.FOREVER);
 LeaseProxy lp = (LeaseProxy)lease;
 String uid = lp.getUID();
 Message upde = new Message("Hello World");
 upde.__setEntryUID(uid);
 Object result = aSpace.update(upde, null, Lease.FOREVER, 60000, com.j_spaces.core.client.UpdateModifiers.UPDATE_OR_WRITE);
 

Parameters:

updatedEntry - The new value of the entity, where matching is done by UID.

transaction - The transaction (if any) under which to work.

lease - The requested lease time of the updated entity, in milliseconds; 0 means retain the original lease.

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

updateModifiers - operation modifiers, values from UpdateModifiers

Returns:

• previous value on successful update.
• null - if timeout occurred after waiting for a transactional proper matching entry.
• when UpdateModifiers.UPDATE_OR_WRITE modifier is applied,
  • null - if write was successful,
  • previous value - on successful update, or
  • OperationTimeoutException - thrown if timeout occurred.

Throws:

EntryNotInSpaceException - if an entry with such a UID doesn't exits in the space

OperationTimeoutException - if timeout expires (when used with UpdateModifiers.UPDATE_OR_WRITE modifier)

net.jini.core.transaction.TransactionException - if a transaction error occurs

net.jini.core.entry.UnusableEntryException - if any serialized field of the entry being read cannot be deserialized for any reason or EntryNotInSpaceException is throw when the UId is not exists in the space

RemoteException - if a communication error occurs

InterruptedException - if the thread in which the read occurs is interrupted

IllegalArgumentException - if the lease time requested is not Lease.ANY and is negative

See Also:

UpdateModifiers, IMetaDataEntry

updateMultiple

Object[] updateMultiple(Object[] entries,
                        net.jini.core.transaction.Transaction transaction,
                        long[] leases)
                        throws net.jini.core.entry.UnusableEntryException,
                               net.jini.core.transaction.TransactionException,
                               RemoteException

Equivalent to calling updateMultiple(Object[], Transaction, long[], int) with modifiers (if any) set by IProxyAdmin.setUpdateModifiers(int).

Parameters:

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

transaction - The transaction under which to perform the operation.

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

Returns:

returns the same as updateMultiple(Object[], Transaction, long[], int) according to the set UpdateModifiers. (see IProxyAdmin.setUpdateModifiers(int)

Throws:

net.jini.core.transaction.TransactionException - if a transaction error occurs

net.jini.core.entry.UnusableEntryException - if any serialized field of the entry being read cannot be deserialized for any reason

RemoteException - if a communication error occurs

snapshot

Object snapshot(Object object)
                throws RemoteException

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 Object will return another 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:

object - the object to take a snapshot of.

Returns:

a snapshot of the entry.

Throws:

RemoteException - - if a communication error occurs

takeMultiple

Object[] takeMultiple(Object template,
                      net.jini.core.transaction.Transaction transaction,
                      int limit)
                      throws net.jini.core.transaction.TransactionException,
                             net.jini.core.entry.UnusableEntryException,
                             RemoteException

Takes all the entries matching the specified template from this space.

 IJSpace aSpace = (IJSpace)SpaceFinder.find("jini://lookup-host/container-name/space-name");
 Object multiTmpl = new Message();
 Object[] results = aSpace.takeMultiple( multiTmpl, null, Integer.MAX_VALUE );
 for (int i=0; i<results.length; i++)
 {
        System.out.println("Taken-Multiple: "+((Message)results[i]).content);
 }
 

Parameters:

template - the template to use for matching.

transaction - the transaction under which to perform the operation.

limit - a limit on the number of entries to be taken. Use Integer.MAX_VALUE for the maximum value.

Returns:

an array of entries that match the template, or empty array in case if no suitable entry was found.

Throws:

net.jini.core.transaction.TransactionException - if a transaction error occurs

net.jini.core.entry.UnusableEntryException - if any serialized field of the entry being read cannot be deserialized for any reason

RemoteException - if a communication error occurs

takeMultiple

Object[] takeMultiple(Object template,
                      net.jini.core.transaction.Transaction txn,
                      int limit,
                      int modifiers)
                      throws net.jini.core.transaction.TransactionException,
                             net.jini.core.entry.UnusableEntryException,
                             RemoteException

Takes all the entries matching the specified template from this space.

 IJSpace aSpace = (IJSpace)SpaceFinder.find("jini://lookup-host/container-name/space-name");
 Object multiTmpl = new Message();
 Object[] results = aSpace.takeMultiple( multiTmpl, null, Integer.MAX_VALUE );
 for (int i=0; i<results.length; i++)
 {
        System.out.println("Taken-Multiple: "+((Message)results[i]).content);
 }
 

Parameters:

template - the template to use for matching.

txn - the transaction under which to perform the operation.

limit - a limit on the number of entries to be taken. Use Integer.MAX_VALUE for the maximum value.

modifiers - one of [ReadModifiers.THROW_PARTIAL_FAILURE, ReadModifiers.REPEATABLE_READ]

Returns:

an array of entries that match the template, or empty array in case if no suitable entry was found.

Throws:

net.jini.core.transaction.TransactionException - if a transaction error occurs

net.jini.core.entry.UnusableEntryException - if any serialized field of the entry being read cannot be deserialized for any reason

RemoteException - if a communication error occurs

take

Object take(Object template,
            net.jini.core.transaction.Transaction transaction,
            long timeout)
            throws net.jini.core.entry.UnusableEntryException,
                   net.jini.core.transaction.TransactionException,
                   InterruptedException,
                   RemoteException

Take 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 template with null fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").

transaction - 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 entry. A timeout of NO_WAIT means to wait no time at all; this is equivalent to a wait of zero.

Returns:

object from the space

Throws:

net.jini.core.entry.UnusableEntryException - - if any serialized field of the entry being read cannot be deserialized for any reason TransactionException - if a transaction error occurs InterruptedException - if the thread in which the read occurs is interrupted RemoteException - if a communication error occurs IllegalArgumentException - if a negative timeout value is used

net.jini.core.transaction.TransactionException

InterruptedException

RemoteException

takeIfExists

Object takeIfExists(Object template,
                    net.jini.core.transaction.Transaction transaction,
                    long timeout)
                    throws net.jini.core.entry.UnusableEntryException,
                           net.jini.core.transaction.TransactionException,
                           InterruptedException,
                           RemoteException

Take any matching object from the space, returning null if there currently is none. 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.

Overloads JavaSpace.takeIfExists(Entry, Transaction, long) by replacing the Entry template with Object, to support Plain Old Java Object templates. Equivalent when called with an Entry cast to Object.

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").

transaction - The transaction (if any) under which to work.

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:

net.jini.core.entry.UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason

net.jini.core.transaction.TransactionException - if a transaction error occurs

InterruptedException - if the thread in which the read occurs is interrupted

RemoteException - if a communication error occurs

See Also:

JavaSpace.takeIfExists(Entry, Transaction, long), take(Object, Transaction, long)

clear

void clear(Object template,
           net.jini.core.transaction.Transaction transaction)
           throws RemoteException,
                  net.jini.core.transaction.TransactionException,
                  net.jini.core.entry.UnusableEntryException

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

 IJSpace aSpace = (IJSpace)SpaceFinder.find("jini://lookup-host/container-name/space-name");
 Object multiTmpl = new Message();
 aSpace.clear(multiTmpl, null);
 
 If the clear operation conducted without transaction (null as value)
 it will clear all entries that are not under transaction.
 Therefor 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 that will be
 from the space.
 You can in fact clean all space objects (that are not under transaction) by calling:
 space.clear( null, null).

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

Parameters:

template - the template to use for matching.

transaction - the transaction under which to perform the operation.

Throws:

net.jini.core.transaction.TransactionException - if a transaction error occurs

net.jini.core.entry.UnusableEntryException - if any serialized field of the entry being read cannot be de serialized for any reason

RemoteException - if a communication error occurs

See Also:

IServerAdmin.clean()

writeMultiple

LeaseContext[] writeMultiple(Object[] objects,
                             net.jini.core.transaction.Transaction transaction,
                             long lease,
                             int updateModifiers)
                             throws net.jini.core.transaction.TransactionException,
                                    RemoteException

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

 IJSpace aSpace = (IJSpace)SpaceFinder.find("jini://lookup-host/container-name/space-name");
 Object[] objects = new Object[100];
 for (int i=0; i<objects.length; i++)
 {
      objects[i] = new Message("Hello World -"+i);
 }
 aSpace.writeMultiple( objects, null, Lease.FOREVER, UpdateModifiers.UPDATE_OR_WRITE );
 

Parameters:

objects - the objects to write.

transaction - the transaction object, if any, under which to perform the write

lease - the requested lease time, in milliseconds

updateModifiers - operation modifiers, values from UpdateModifiers

Returns:

array in which each cell is corresponding to the written entry at the same index in the entries array, each cell is a usable Lease on a successful write, or null if performed with NoWriteLease attribute.

when UpdateModifiers.UPDATE_OR_WRITE modifier is applied,

• LeaseContext.getObject() returns:
  • null - on a successful write
  • previous value - on successful update
• or, OperationTimeoutException - thrown if timeout occurred

Throws:

net.jini.core.transaction.TransactionException - if a transaction error occurs

RemoteException - is never thrown for backward only

IllegalArgumentException - if the lease time requested is not Lease.ANY and is negative, the entries array is empty or null.

InterruptedException - if the thread in which the write occurs is interrupted

WriteMultiplePartialFailureException - that point out which entries failed and what is the cause, relevant in case of partial failure (can contains runtime and typed exceptions)

writeMultiple

LeaseContext[] writeMultiple(Object[] objects,
                             net.jini.core.transaction.Transaction transaction,
                             long lease)
                             throws net.jini.core.transaction.TransactionException,
                                    RemoteException

Equivalent to calling #writeMultiple(Object[], Transaction, long, int) with modifier {@link com.j_spaces.core.client.UpdateModifiers#WRITE_ONLY}.

Parameters:

objects - the objects to write.

transaction - the transaction object, if any, under which to perform the write

lease - the requested lease time, in milliseconds

Returns:

the leases for the written entries. A usable Lease on a successful write, or null if performed with NoWriteLease attribute.

Throws:

net.jini.core.transaction.TransactionException - if a transaction error occurs

RemoteException - is never thrown for backward only

IllegalArgumentException - if the lease time requested is not Lease.ANY and is negative, the entries array is empty or null.

InterruptedException - if the thread in which the write occurs is interrupted

WriteMultiplePartialFailureException - that point out which entries failed and what is the cause, relevant in case of partial failure (can contains runtime and typed exceptions)

write

LeaseContext write(Object object,
                   net.jini.core.transaction.Transaction transaction,
                   long lease)
                   throws net.jini.core.transaction.TransactionException,
                          RemoteException

Equivalent to calling write(Object, Transaction, long, long, int) with the UpdateModifiers.UPDATE_OR_WRITE.

Parameters:

object - the object to write

transaction - the transaction object, if any, under which to perform the write

lease - the requested lease time, in milliseconds

Returns:

A usable Lease on a successful write, or null if performed with NoWriteLease attribute.

when UpdateModifiers.UPDATE_OR_WRITE modifier is applied,

• LeaseContext.getObject() returns:
  • null - on a successful write
  • previous value - on successful update
• or, OperationTimeoutException - thrown if timeout occurred

Throws:

EntryAlreadyInSpaceException - if an entry with the same UID already exists in space (Modifiers.WRITE)

EntryNotInSpaceException - if an entry with such a UID doesn't exits in the space (Modifiers.UPDATE)

net.jini.core.transaction.TransactionException - if a transaction error occurs

RemoteException - if a communication error occurs

write

LeaseContext write(Object object,
                   net.jini.core.transaction.Transaction transaction,
                   long lease,
                   long timeout,
                   int modifiers)
                   throws net.jini.core.transaction.TransactionException,
                          RemoteException

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

Applying the UpdateModifiers.UPDATE_OR_WRITE modifier, is equivalent to calling update(Object, Transaction, long, long, int), but otherwise returning a Lease on a successful write.

If the object has a primary key,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 granter, unless an actual 'write' was performed.

The operation can also be forced to perform write operation using the UpdateModifiers.WRITE_ONLY resulting in an EntryAlreadyInSpaceException exception if the object already exists in the space.

Parameters:

transaction - the transaction object, if any, under which to perform the write

object - the object to write

lease - the requested lease time, in milliseconds

timeout -

modifiers -

Returns:

A usable Lease on a successful write, or null if performed with NoWriteLease attribute.

when UpdateModifiers.UPDATE_OR_WRITE modifier is applied,

• LeaseContext.getObject() returns:
  • null - on a successful write
  • previous value - on successful update
• or, OperationTimeoutException - thrown if timeout occurred

Throws:

EntryAlreadyInSpaceException - if an entry with the same UID already exists in space (Modifiers.WRITE)

EntryNotInSpaceException - if an entry with such a UID doesn't exits in the space (Modifiers.UPDATE)

OperationTimeoutException - if timeout expires (when used with UpdateModifiers.UPDATE_OR_WRITE modifier)

net.jini.core.transaction.TransactionException - if a transaction error occurs

RemoteException - if a communication error occurs

updateMultiple

Object[] updateMultiple(Object[] objects,
                        net.jini.core.transaction.Transaction transaction,
                        long[] leases,
                        int updateModifiers)
                        throws net.jini.core.entry.UnusableEntryException,
                               net.jini.core.transaction.TransactionException,
                               RemoteException

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 com.j_spaces.core.client.UpdateModifiers#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.

 IJSpace aSpace = (IJSpace)SpaceFinder.find("jini://lookup-host/container-name/space-name");
 Lease[] leases = ...//see writeMultiple
 Object[] results = aSpace.readMultiple( multiTmpl, null, Integer.MAX_VALUE );
 for (int i=0; i<results.length; i++)
 {
    // modify entry Object by adding an index to the content
    ((Message)results[i]).content += i;
 }

 // updates the space with the modified entries
 Object[] results = aSpace.updateMultiple(results, null, leases);
 

Parameters:

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

transaction - The transaction under which to perform the operation.

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
  • EntryVersionConflictException - 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:

net.jini.core.transaction.TransactionException - if a transaction error occurs

net.jini.core.entry.UnusableEntryException - if any serialized field of the entry being read cannot be deserialized for any reason

RemoteException - if a communication error occurs

getProxyAdmin

IProxyAdmin getProxyAdmin()

Returns a proxy admin.

Returns:

proxy admin.

Since:

6.1

getServerAdmin

IServerAdmin getServerAdmin()

Return a server admin.

Returns:

server admin.

Since:

6.1