com.j_spaces.core
Interface IJSpace

All Superinterfaces:

IPojoSpace, IProxyAdmin, IServerAdmin, JavaSpace

public interface IJSpace
extends JavaSpace, IPojoSpace, IProxyAdmin, IServerAdmin

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

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 IServerAdmin.clean()) are required.

Since this interface extends the JavaSpace interface, standard JavaSpaces methods may be invoked without downcasting.

The POJO UID generation and usage scenarios:
Scenario A: Inserting POJO into 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:

1.0

See Also:

IJSpaceContainer, SpaceFinder

Field Summary

Fields inherited from interface net.jini.space.JavaSpace

NO_WAIT

Method Summary

void	clear(Entry template, Transaction txn) Removes the entries that match the specified template and the specified transaction from this space.
int	count(Entry tmpl, Transaction txn) Count any matching entry from the space, visible under the specified transaction.
int	count(Entry tmpl, Transaction txn, int modifiers) Count (according to the modifiers) any matching entry from the space, visible under the specified transaction.
int	getReadTakeModifiers() Deprecated. use IProxyAdmin.getReadModifiers() instead
EventRegistration	notify(Entry template, Transaction txn, RemoteEventListener listener, long lease, MarshalledObject handback, int notifyType) An extension to the standard JavaSpace.notify() method.
EventRegistration	notify(Object template, Transaction txn, long lease, com.gigaspaces.events.NotifyInfo info) Deprecated. Use EventSessionFactory instead.
EventRegistration	notify(Object template, Transaction txn, RemoteEventListener listener, long lease, MarshalledObject handback) Deprecated. Use EventSessionFactory instead.
EventRegistration	notify(Object template, Transaction txn, RemoteEventListener listener, long lease, MarshalledObject handback, int modifiers) Deprecated. Use EventSessionFactory instead.
Entry	read(Entry tmpl, Transaction txn, long timeout, int modifiers) Read (according to the modifiers) any matching entry from the space, blocking until one exists.
Entry	readIfExists(Entry tmpl, Transaction txn, long timeout, int modifiers) Read (according to the modifiers) any matching entry from the space, returning null if there currently is none.
Entry[]	readMultiple(Entry tmpl, Transaction txn, int limit) Read any matching entries from the space.
Entry[]	readMultiple(Entry tmpl, Transaction txn, int limit, int modifiers) Read (according to the modifiers) any matching entries from the space.
Object[]	replace(Entry template, Entry newEntry, Transaction txn, long lease) Deprecated. use instead: update(Entry, Transaction, long, long, int)
int	setReadTakeModifiers(int newModifiers) Deprecated. use IProxyAdmin.setReadModifiers(int) instead
Entry[]	takeMultiple(Entry template, Transaction txn, int limit) Takes all the entries matching the specified template from this space.
Entry[]	takeMultiple(Entry template, Transaction txn, int maxEntries, int modifiers) Takes all the entries matching the specified template from this space.
Entry	update(Entry updatedEntry, Transaction transaction, long lease, long timeout) Equivalent to calling update(Entry, Transaction, long, long, int) with modifiers (if any) set by IProxyAdmin.setUpdateModifiers(int).
Entry	update(Entry updatedEntry, Transaction transaction, long lease, long timeout, int updateModifiers) Equivalent to calling IPojoSpace.update(Object, Transaction, long, long, int) by use of a cast from Entry to Object. see it also as a reference to further semantics of this method.
Object[]	updateMultiple(Entry[] entries, Transaction transaction, long[] leases) Equivalent to calling updateMultiple(Entry[], Transaction, long[], int) with modifiers (if any) set by IProxyAdmin.setUpdateModifiers(int).
Object[]	updateMultiple(Entry[] entries, Transaction transaction, long[] leases, int updateModifiers) Equivalent to calling IPojoSpace.updateMultiple(Object[], Transaction, long[], int) by use of an array of Object[] constructed as new Entry[]. see it also as a reference to further semantics of this method.
Lease[]	writeMultiple(Entry[] entries, Transaction txn, long lease) Writes the specified entries to this space.

Methods inherited from interface net.jini.space.JavaSpace

notify, read, readIfExists, snapshot, take, takeIfExists, write

Methods inherited from interface com.gigaspaces.client.IPojoSpace

clear, count, count, getProxyAdmin, getServerAdmin, read, read, readIfExists, readIfExists, readMultiple, readMultiple, snapshot, take, takeIfExists, takeMultiple, takeMultiple, update, update, updateMultiple, updateMultiple, write, write, writeMultiple

Methods inherited from interface com.gigaspaces.client.IProxyAdmin

getFinderURL, getReadModifiers, getUpdateModifiers, isFifo, isNOWriteLeaseMode, isOptimisticLockingEnabled, isSecured, setDefaultTransaction, setFifo, setNOWriteLeaseMode, setOptimisticLocking, setReadModifiers, setSecurityContext, setUpdateModifiers

Methods inherited from interface com.gigaspaces.client.IServerAdmin

clean, dropClass, getAdmin, getContainer, getName, getReferentUuid, getStubHandler, getURL, isEmbedded, ping

Method Detail

count

int count(Entry tmpl,
          Transaction txn)
          throws UnusableEntryException,
                 TransactionException,
                 RemoteException

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

Parameters:

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

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

Returns:

The number of matching entries.

Throws:

UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason

TransactionException - if a transaction error occurs

RemoteException - if a communication error occurs

count

int count(Entry tmpl,
          Transaction txn,
          int modifiers)
          throws UnusableEntryException,
                 TransactionException,
                 RemoteException

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

Overloads count(Entry, 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:

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

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

modifiers - one or a union of ReadModifiers.

Returns:

The number of matching entries.

Throws:

UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason

TransactionException - if a transaction error occurs

RemoteException - if a communication error occurs

read

Entry read(Entry tmpl,
           Transaction txn,
           long timeout,
           int modifiers)
           throws UnusableEntryException,
                  TransactionException,
                  InterruptedException,
                  RemoteException

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

Overloads JavaSpace.read(Entry, 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:

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

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

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.

modifiers - one or a union of ReadModifiers.

Returns:

a copy of the entry read from the space.

Throws:

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

Since:

6.0

See Also:

JavaSpace.read(Entry, Transaction, long)

readIfExists

Entry readIfExists(Entry tmpl,
                   Transaction txn,
                   long timeout,
                   int modifiers)
                   throws UnusableEntryException,
                          TransactionException,
                          InterruptedException,
                          RemoteException

Read (according to the modifiers) any matching entry 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 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:

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

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

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.

modifiers - one or a union of ReadModifiers.

Returns:

a copy of the entry read from the space

Throws:

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

Since:

6.0

See Also:

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

readMultiple

Entry[] readMultiple(Entry tmpl,
                     Transaction txn,
                     int limit)
                     throws TransactionException,
                            UnusableEntryException,
                            RemoteException

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 limit. Returns an empty array if no match was found.

Note: Each matching entry has to be explicitly cast.

 Entry[] results =  ijspace.readMultiple( new MyEntry(), (Transaction)null, Integer.MAX_VALUE );
 for (int i=0; i<results.length; i++)
 {
        System.out.println( (MyEntry)results[i]) );
 }
 

Parameters:

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

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

limit - 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:

UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason

TransactionException - if a transaction error occurs

RemoteException - if a communication error occurs

readMultiple

Entry[] readMultiple(Entry tmpl,
                     Transaction txn,
                     int limit,
                     int modifiers)
                     throws TransactionException,
                            UnusableEntryException,
                            RemoteException

Read (according to the modifiers) any matching entries 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 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:

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

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

limit - 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:

UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason

TransactionException - if a transaction error occurs

RemoteException - if a communication error occurs

Since:

6.0

See Also:

readMultiple(Entry, Transaction, int)

replace

@Deprecated
Object[] replace(Entry template,
                            Entry newEntry,
                            Transaction txn,
                            long lease)
                 throws TransactionException,
                        UnusableEntryException,
                        RemoteException

Deprecated. use instead: update(Entry, Transaction, long, long, int)

Replaces the first entry matching the specified template, if found and there is no transaction conflict.

 IJSpace aSpace = (IJSpace)SpaceFinder.find("jini://lookup-host/container-name/space-name");
 Message tmpl = new Message("Hello World");
 Message msg = new Message("Goodbye World");
 Object[] result = aSpace.replace(tmpl, msg, null, Lease.FOREVER);
 Message old = (Message)result[0];
 long msgLease = ((Lease)result[1]).getExpiration();
 
 The replace method is not atomic (unless used with transaction)
 which means that the former call equals to:
 
 Message old = (Message)aSpace.take(tmpl, null, JavaSpace.NO_WAIT);
 Lease lease = aSpace.write(msg, null, Lease.FOREVER);
 

Parameters:

template - the template to use for matching.

newEntry - the value of the new entry.

txn - the transaction under which to perform the operation.

lease - the lease time of the new entry

Returns:

an array of 2 elements: the first element is the old object and the second element is the new lease. If not matching entry was found, null is returned.

Throws:

TransactionException - if a transaction error occurs

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

RemoteException - if a communication error occurs

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

See Also:

#update(Entry, Entry, Transaction, long)

setReadTakeModifiers

@Deprecated
int setReadTakeModifiers(int newModifiers)

Deprecated. use IProxyAdmin.setReadModifiers(int) instead

Sets the read-take mode modifiers for proxy level.
Default: ReadTakeModifiers.REPEATABLE_READ

Parameters:

newModifiers - new values for modifiers Values are defined in ReadTakeModifiers.

Returns:

old value of modifiers.

See Also:

ReadTakeModifiers

getReadTakeModifiers

@Deprecated
int getReadTakeModifiers()

Deprecated. use IProxyAdmin.getReadModifiers() instead

Gets the proxyReadTakeModifiers.
values are from ReadTakeModifiers.

Returns:

value of modifiers.

notify

@Deprecated
EventRegistration notify(Object template,
                                    Transaction txn,
                                    RemoteEventListener listener,
                                    long lease,
                                    MarshalledObject handback)
                         throws TransactionException,
                                RemoteException

Deprecated. Use EventSessionFactory instead.

When objects that match this template are written, notification is sent to the given listener with a RemoteEvent that includes the handback object. Matching is done in the same way with read operation.

Parameters:

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

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

listener - The remote event listener to notify.

lease - the requested lease time, in milliseconds

handback - An object to send to the listener as part of the event notification

Returns:

the event registration to the the registrant

Throws:

TransactionException

RemoteException

notify

@Deprecated
EventRegistration notify(Object template,
                                    Transaction txn,
                                    RemoteEventListener listener,
                                    long lease,
                                    MarshalledObject handback,
                                    int modifiers)
                         throws TransactionException,
                                RemoteException

Deprecated. Use EventSessionFactory instead.

An extension to the standard JavaSpace.notify() method.
When entries that match this template are written and also match the modifier criteria, notify is sent to the given listener with a RemoteEvent that includes the handback object. Matching is done in the same way with read operation. A notification will occur when operations are done on entries that match a certain template and modifier criteria.
One can register for all the "notifies" using NOTIFY_ALL, or use specific types:

 Available Notify types:
    NotifyModifiers.NOTIFY_WRITE
    NotifyModifiers.NOTIFY_UPDATE
    NotifyModifiers.NOTIFY_TAKE
    NotifyModifiers.NOTIFY_LEASE_EXPIRATION
    NotifyModifiers.NOTIFY_ALL

 IJSpace aSpace = (IJSpace)SpaceFinder.find("jini://lookup-host/container-name/space-name");
 Message template = new Message();
 EventRegistration eventReg = aSpace.notify( template, null, this, Lease.FOREVER, null, NotifyModifiers.NOTIFY_ALL);

 System.out.println("Notification registered. Registration id: "
                        + eventReg.getID() + " ; Sequence number: "
                        + eventReg.getSequenceNumber());

Note: the RemoteEventListner identifier has been passed as this, indicating that the current class implements RemoteEventListener.
Thus, this class also inherits and implements the notify method. You could then obtain the entry that triggered the event e.g.:

 void notify(RemoteEvent theEvent) {
        ...
        EntryArrivedRemoteEvent arrivedRemoteEvent = (EntryArrivedRemoteEvent)theEvent;
        Object entry = arrivedRemoteEvent.getObject();
        int notifyType = arrivedRemoteEvent.getNotifyType();
        ...
 }

Parameters:

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

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

listener - The remote event listener to notify.

lease - the requested lease time, in milliseconds

handback - An object to send to the listener as part of the event notification.

modifiers - the modifiers.

Returns:

the event registration handle to the registration

Throws:

TransactionException - if a transaction error occurs

RemoteException - if a communication error occurs

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

See Also:

JavaSpace.notify(Entry, Transaction, RemoteEventListener, long, MarshalledObject), NotifyModifiers, NotifyDelegator

notify

@Deprecated
EventRegistration notify(Object template,
                                    Transaction txn,
                                    long lease,
                                    com.gigaspaces.events.NotifyInfo info)
                         throws TransactionException,
                                RemoteException

Deprecated. Use EventSessionFactory instead.

Throws:

TransactionException

RemoteException

clear

void clear(Entry template,
           Transaction txn)
           throws RemoteException,
                  TransactionException,
                  UnusableEntryException

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

 IJSpace aSpace = (IJSpace)SpaceFinder.find("jini://lookup-host/container-name/space-name");
 Entry 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, therefor 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:
 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.

txn - the transaction under which to perform the operation.

Throws:

TransactionException - if a transaction error occurs

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

RemoteException - if a communication error occurs

See Also:

IServerAdmin.clean()

notify

EventRegistration notify(Entry template,
                         Transaction txn,
                         RemoteEventListener listener,
                         long lease,
                         MarshalledObject handback,
                         int notifyType)
                         throws TransactionException,
                                RemoteException

An extension to the standard JavaSpace.notify() method.
A notification will occur when operations are done on entries that match a certain template and modifier criteria.
One can register for all the "notifies" using NOTIFY_ALL, or use specific types:

 Available Notify types:
    NotifyModifiers.NOTIFY_WRITE
    NotifyModifiers.NOTIFY_UPDATE
    NotifyModifiers.NOTIFY_TAKE
    NotifyModifiers.NOTIFY_LEASE_EXPIRATION
    NotifyModifiers.NOTIFY_ALL

 IJSpace aSpace = (IJSpace)SpaceFinder.find("jini://lookup-host/container-name/space-name");
 Entry template = new Message();
 EventRegistration eventReg = aSpace.notify( template, null, this, Lease.FOREVER, null, NotifyModifiers.NOTIFY_ALL);

 System.out.println("Notification registered. Registration id: "
                        + eventReg.getID() + " ; Sequence number: "
                        + eventReg.getSequenceNumber());

Note: the RemoteEventListner identifier has been passed as this, indicating that the current class implements RemoteEventListener.
Thus, this class also inherits and implements the notify method. You could then obtain the entry that triggered the event e.g.:

 void notify(RemoteEvent theEvent) {
        ...
        EntryArrivedRemoteEvent arrivedRemoteEvent = (EntryArrivedRemoteEvent)theEvent;
        Entry entry = arrivedRemoteEvent.getEntry();
        int notifyType = arrivedRemoteEvent.getNotifyType();
        ...
 }

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

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

listener - The remote event listener to notify.

lease - the requested lease time, in milliseconds

handback - An object to send to the listener as part of the event notification.

notifyType - Notify type.

Returns:

the event registration to the the registrant

Throws:

TransactionException - if a transaction error occurs

RemoteException - if a communication error occurs

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

See Also:

JavaSpace.read(Entry, Transaction, long), NotifyModifiers, NotifyDelegator

takeMultiple

Entry[] takeMultiple(Entry template,
                     Transaction txn,
                     int limit)
                     throws TransactionException,
                            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");
 Entry multiTmpl = new Message();
 Entry[] 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.

Returns:

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

Throws:

TransactionException - if a transaction error occurs

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

RemoteException - if a communication error occurs

takeMultiple

Entry[] takeMultiple(Entry template,
                     Transaction txn,
                     int maxEntries,
                     int modifiers)
                     throws TransactionException,
                            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");
 Entry multiTmpl = new Message();
 Entry[] 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:

TransactionException - if a transaction error occurs

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

RemoteException - if a communication error occurs

update

Entry update(Entry updatedEntry,
             Transaction transaction,
             long lease,
             long timeout)
             throws TransactionException,
                    UnusableEntryException,
                    RemoteException,
                    InterruptedException

Equivalent to calling update(Entry, 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(Entry, Transaction, long, long, int) according to the set UpdateModifiers. (see IProxyAdmin.setUpdateModifiers(int)

Throws:

TransactionException - if a transaction error occurs

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(Entry, Transaction, long, long, int), UpdateModifiers, IProxyAdmin.setUpdateModifiers(int)

updateMultiple

Object[] updateMultiple(Entry[] entries,
                        Transaction transaction,
                        long[] leases)
                        throws UnusableEntryException,
                               TransactionException,
                               RemoteException

Equivalent to calling updateMultiple(Entry[], 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(Entry[], Transaction, long[], int) according to the set UpdateModifiers. (see IProxyAdmin.setUpdateModifiers(int)

Throws:

TransactionException - if a transaction error occurs

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

RemoteException - if a communication error occurs

updateMultiple

Object[] updateMultiple(Entry[] entries,
                        Transaction transaction,
                        long[] leases,
                        int updateModifiers)
                        throws UnusableEntryException,
                               TransactionException,
                               RemoteException

Equivalent to calling IPojoSpace.updateMultiple(Object[], Transaction, long[], int) by use of an array of Object[] constructed as new Entry[]. see it also as a reference to further semantics of this method.

 Object[] entries = new Entry[length];
 Lease[] leases = new Lease[length];
 
 for (int i=0; i<length; i++)
 {
        entries[i] = new Message("hello-"+i);
        leases[i] = Lease.FOREVER;
 }
 Object[] results = aSpace.updateMultiple(entries, null, leases, UpdateModifiers.UPDATE_ONLY);
 

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

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 if an update failuar occurred.

Throws:

TransactionException - if a transaction error occurs

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

RemoteException - if a communication error occurs

writeMultiple

Lease[] writeMultiple(Entry[] entries,
                      Transaction txn,
                      long lease)
                      throws TransactionException,
                             RemoteException

Writes the specified entries to this space.

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

Parameters:

entries - the entries to write.

txn - 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:

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)

update

Entry update(Entry updatedEntry,
             Transaction transaction,
             long lease,
             long timeout,
             int updateModifiers)
             throws TransactionException,
                    UnusableEntryException,
                    RemoteException,
                    InterruptedException

Equivalent to calling IPojoSpace.update(Object, Transaction, long, long, int) by use of a cast from Entry to Object. see it also as a reference to further semantics of this method.

Parameters:

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

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

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

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.

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)

TransactionException - if a transaction error occurs

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:

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