com.j_spaces.core
Interface IJSpace

All Superinterfaces:

JavaSpace

public interface IJSpace
extends JavaSpace

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 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	clean() Cleans this space.
void	clear(Entry template, Transaction txn) Removes the entries that match the specified template and the specified transaction from this space.
void	clear(Object template, Transaction txn) Removes the objects that match the specified template and the specified transaction from this space.
int	count(Entry template, Transaction txn) Counts the number of entries that match the specified template and the specified transaction.
int	count(Object template, Transaction txn) Counts the number of objects that match the specified template and the specified transaction.
void	dropClass(String className) Drops all Class's entries and all its templates from the space.
Object	getAdmin() Returns the admin object to the remote part of this space.
IJSpaceContainer	getContainer() Returns the container proxy this space resides in.
String	getName() Returns the name of this space.
int	getReadTakeModifiers() Gets the proxyReadTakeModifiers.
Uuid	getReferentUuid() Returns the unique uid of this space instance.
IStubHandler	getStubHandler() Returns the StubHandler of this space.
int	getUpdateModifiers() Gets the proxyUpdateModifiers.
SpaceURL	getURL() Returns the SpaceURL instance which was used to initialize the space.
boolean	isEmbedded() Checks whether proxy is connected to embedded or remote space.
boolean	isFifo() Returns true if this proxy FIFO enabled, otherwise false.
boolean	isNOWriteLeaseMode() Checks the write mode.
boolean	isOptimisticLockingEnabled() Returns status of Optimistic Lock protocol.
boolean	isSecured() Returns an indication : is this space secured.
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 object, Transaction transaction, RemoteEventListener remoteeventlistener, long lease, MarshalledObject marshalledobject) When objects that match this template are written, notification is sent to the given listener with a RemoteEvent that includes the handback object.
EventRegistration	notify(Object template, Transaction txn, RemoteEventListener listener, long lease, MarshalledObject handback, int modifiers) An extension to the standard JavaSpace.notify() method.
void	ping() Checks whether the space is alive and accessible.
Object	read(Object entry, Transaction transaction, long timeout) Read any matching object from the space, blocking until one exists.
Object	readIfExists(Object object, Transaction transaction, long timeout) Read if exists any matching object from the space, blocking until one exists.
Entry[]	readMultiple(Entry template, Transaction txn, int maxEntries) Reads all the entries matching the specified template from this space.
Object[]	readMultiple(Object template, Transaction txn, int maxEntries) Reads all the objects matching the specified template from this space.
Object[]	replace(Entry template, Entry newEntry, Transaction txn, long lease) Deprecated. use instead: update(Entry, Transaction, long, long, int)
void	setDefaultTransaction(Transaction txn) Sets default transaction to use in case that null parameter is used as transaction parameter with JavaSpace methods.
void	setFifo(boolean enabled) Sets FIFO mode for proxy.
void	setNOWriteLeaseMode(boolean noWriteLeaseMode) If set to true, Lease object will not return from write/writeMultiple operations.
void	setOptimisticLocking(boolean enabled) Enable/Disable Optimistic Lock protocol.
int	setReadTakeModifiers(int newModifiers) Sets the read-take mode modifiers for proxy level.
void	setSecurityContext(SecurityContext sc) This function is called by the client (usually at the beginning of the session) in order to set a security context for the following operations.
int	setUpdateModifiers(int newModifiers) Sets the update mode modifiers for proxy level.
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 object, Transaction transaction, long timeout) Take any matching entry from the space, blocking until one exists.
Object	takeIfExists(Object object, Transaction transaction, long timeout) Take if exists any matching entry from the space, blocking until one exists.
Entry[]	takeMultiple(Entry template, Transaction txn, int maxEntries) Takes all the entries matching the specified template from this space.
Object[]	takeMultiple(Object template, Transaction txn, int maxEntries) Takes all the entries matching the specified template from this space.
Object[]	update(Entry template, Entry newEntry, Transaction txn, long lease) Deprecated. use instead: update(Entry, Transaction, long, long, int)
Entry	update(Entry template, Entry updatedEntry, Transaction transaction, long lease, long timeout) Deprecated. use instead: update(Entry, Transaction, long, long, int)
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 setUpdateModifiers(int).
Entry	update(Entry updatedEntry, Transaction transaction, long lease, long timeout, boolean writeIfAbsent) Deprecated. use instead update(Entry, Transaction, long, long, int) with UpdateModifiers.UPDATE_OR_WRITE modifier which is equivalent to setting writeIfAbsent=true.
Entry	update(Entry updatedEntry, Transaction transaction, long lease, long timeout, int updateModifiers) Equivalent to calling 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	update(Object updatedEntry, Transaction transaction, long lease, long timeout) Equivalent to calling update(Object, Transaction, long, long, int) with modifiers (if any) set by setUpdateModifiers(int).
Object	update(Object updatedEntry, 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(Entry[] entries, Transaction transaction, long[] leases) Equivalent to calling updateMultiple(Entry[], Transaction, long[], int) with modifiers (if any) set by setUpdateModifiers(int).
Object[]	updateMultiple(Entry[] entries, Transaction transaction, long[] leases, int updateModifiers) Equivalent to calling 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[]	updateMultiple(Object[] entries, Transaction transaction, long[] leases) Equivalent to calling updateMultiple(Object[], Transaction, long[], int) with modifiers (if any) set by setUpdateModifiers(int).
Object[]	updateMultiple(Object[] objects, 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 Modifiers.NONE).
LeaseContext	write(Object object, Transaction transaction, long lease) Equivalent to calling write(Object, Transaction, long, long, int) with the UpdateModifiers.UPDATE_OR_WRITE.
LeaseContext	write(Object object, Transaction transaction, long lease, long timeout, int modifiers) Writes a new object to the space, returning its Lease.
Lease[]	writeMultiple(Entry[] entries, Transaction txn, long lease) Writes the specified entries to this space.
Lease[]	writeMultiple(Object[] objects, Transaction txn, long lease) Writes the specified objects to this space.

Methods inherited from interface net.jini.space.JavaSpace

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

Method Detail

getName

String getName()

Returns the name of this space.

 IJSpace aSpace = (IJSpace)SpaceFinder.find("jini://lookup-host/container-name/");
 String name = aSpace.getName();
 

Returns:

the name of this space.

clean

void clean()
           throws RemoteException

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.

 IJSpace aSpace = (IJSpace)SpaceFinder.find("jini://lookup-host/container-name/space-name");
 aSpace.clean();
 

Throws:

RemoteException - if a communication error occurs

getAdmin

Object getAdmin()
                throws RemoteException

Returns the admin object to the remote part of this space.

 // get a list of classes and the number of entries of each class
 IRemoteJSpaceAdmin spaceAdmin = (IRemoteJSpaceAdmin)space.getAdmin();
 Object classList[] = spaceAdmin.getRuntimeInfo().m_ClassNames.toArray();
 List numOFEntries = spaceAdmin.getRuntimeInfo().m_NumOFEntries;
 

Returns:

the admin object to the remote part of this space.

Throws:

RemoteException - if a communication error occurs

ping

void ping()
          throws RemoteException

Checks whether the space is alive and accessible.

 IJSpace aSpace = (IJSpace)SpaceFinder.find("jini://lookup-host/container-name/space-name");
 try{
    aSpace.ping();
    System.out.println("Space alive");
 }
 catch (java.rmi.RemoteException re) {
    System.out.println("Space unreachable");
 }
 

Throws:

RemoteException - when space was unreachable

replace

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)

update

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

Equivalent to calling update(Object, Transaction, long, long, int) with modifiers (if any) set by 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 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(Object, Transaction, long, long, int), UpdateModifiers, setUpdateModifiers(int)

update

Object update(Object updatedEntry,
              Transaction transaction,
              long lease,
              long timeout,
              int updateModifiers)
              throws TransactionException,
                     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 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, 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)

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:

UpdateModifiers, IMetaDataEntry

updateMultiple

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

Equivalent to calling updateMultiple(Object[], Transaction, long[], int) with modifiers (if any) set by 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 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

setSecurityContext

void setSecurityContext(SecurityContext sc)
                        throws SpaceSecurityException,
                               RemoteException

This function is called by the client (usually at the beginning of the session) in order to set a security context for the following operations.

 IJSpace aSpace = (IJSpace)SpaceFinder.find("jini://lookup-host/container-name/space-name");
 SecurityContext sc = new SecurityContext("anonymous", "anonymous");
 aSpace.setSecurityContext(sc);
 

Parameters:

sc - the SecurityContext to be active (or null to disable).

Throws:

SpaceSecurityException - Thrown by the Space or Filter to indicate a security violation.

RemoteException - if a communication error occurs

isSecured

boolean isSecured()

Returns an indication : is this space secured. If for this space defined Security Filter, the space will be secured.

Returns:

boolean true if this space secured, otherwise false.

See Also:

DefaultSecurityFilter

dropClass

void dropClass(String className)
               throws RemoteException,
                      DropClassException

Drops all Class's entries and all its templates from the space. Calling this method will remove all internal meta data related to this class stored in the space. When using persistent spaced the relevant RDBMS table will be dropped. It is the caller responsibility to ensure that no entries from this class are written to the space while this method is called. This method is protected through the space Default Security Filter. Admin permissions required to execute this request successfully.

 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);

 aSpace.dropClass( Message.class.getName());
 

Parameters:

className - name of class to delete.

Throws:

DropClassException - Failed to drop desired class.

RemoteException - if a communication error occurs

See Also:

clear(Entry, Transaction)

isEmbedded

boolean isEmbedded()

Checks whether proxy is connected to embedded or remote space.

Returns:

Returns true if the proxy embedded, otherwise false.

setOptimisticLocking

void setOptimisticLocking(boolean enabled)

Enable/Disable Optimistic Lock protocol.

Parameters:

enabled - true enable Optimistic Lock protocol, false disable.

See Also:

IMetaDataEntry

isOptimisticLockingEnabled

boolean isOptimisticLockingEnabled()

Returns status of Optimistic Lock protocol.

Returns:

true Optimistic Lock enabled, otherwise false.

See Also:

IMetaDataEntry

setFifo

void setFifo(boolean enabled)

Sets FIFO mode for proxy. Every operation that come through the proxy will be FIFO enabled. The other way to set FIFO enabled using com.j_spaces.core.client.SpaceFinder: SpaceFinder.find("jini://localhost/myContainerName/JavaSpaces?fifo=true") If this mode enabled, you don't need to use com.j_spaces.core.client.MetaDataEntry.setFifo(boolean) for every entry/template. All entries and templates will be FIFO enabled.

Parameters:

enabled - if true this proxy FIFO enabled, otherwise false.

See Also:

IMetaDataEntry

isFifo

boolean isFifo()

Returns true if this proxy FIFO enabled, otherwise false.

Returns:

Returns true if this proxy FIFO enabled, otherwise false.

See Also:

IMetaDataEntry

setNOWriteLeaseMode

void setNOWriteLeaseMode(boolean noWriteLeaseMode)

If set to true, Lease object will not return from write/writeMultiple operations.
The other way to set noWriteLease mode enabled using SpaceFinder:
SpaceFinder.find("jini://localhost/myContainerName/JavaSpaces?noWriteLease")

Parameters:

noWriteLeaseMode - write mode.

See Also:

SpaceURL

isNOWriteLeaseMode

boolean isNOWriteLeaseMode()

Checks the write mode.

Returns:

true if do not return Lease object after write, otherwise false.

See Also:

setNOWriteLeaseMode(boolean)

getStubHandler

IStubHandler getStubHandler()

Returns the StubHandler of this space.

Returns:

StubHandler of this space.

getReferentUuid

Uuid getReferentUuid()

Returns the unique uid of this space instance.

Returns:

Returns the unique uid of the space

See Also:

ReferentUuid

setDefaultTransaction

void setDefaultTransaction(Transaction txn)

Sets default transaction to use in case that null parameter is used as transaction parameter with JavaSpace methods.
Notice: after commit/abort the default transaction should be set to null otherwise the TransactionException will be thrown on the next space operation call.

 space.setDefaultTransaction( txn);

 space.write( entry1, null, Lease.FOREVER );
 space.write( entry2, null, Lease.FOREVER );
 txn.commit();

 space.setDefaultTransaction( null);
 

Note: This function is unsupported when using it in conjunction with local cache.

Parameters:

txn - the default transaction.

getContainer

IJSpaceContainer getContainer()

Returns the container proxy this space resides in.
The container holds information and attributes of neighboring spaces, and exposes API for creating and destroying of spaces.

Returns:

Returns the container proxy.

getURL

SpaceURL getURL()

Returns the SpaceURL instance which was used to initialize the space.

Notice: The SpaceURL object contains information on the space and container configuration/setup such as space url used, space/container/cluster schema used and other attributes.

The IJSpaceContainer keeps also its reference of the SpaceURL which launched the container.

Returns:

SpaceURL which initialized that specific space instance.

setUpdateModifiers

int setUpdateModifiers(int newModifiers)

Sets the update mode modifiers for proxy level.

Parameters:

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

Returns:

old value of modifiers.

getUpdateModifiers

int getUpdateModifiers()

Gets the proxyUpdateModifiers. Values are defined in UpdateModifiers class.
Default value: UPDATE_ONLY.

Returns:

value of modifiers.

setReadTakeModifiers

int setReadTakeModifiers(int newModifiers)

Sets the read-take mode modifiers for proxy level.

Parameters:

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

Returns:

old value of modifiers.

getReadTakeModifiers

int getReadTakeModifiers()

Gets the proxyReadTakeModifiers.
values are from ReadTakeModifiers.

Returns:

value of modifiers.

notify

EventRegistration notify(Object object,
                         Transaction transaction,
                         RemoteEventListener remoteeventlistener,
                         long lease,
                         MarshalledObject marshalledobject)
                         throws TransactionException,
                                RemoteException

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:

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

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

remoteeventlistener - The remote event listener to notify.

lease - the requested lease time, in milliseconds

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

Returns:

the event registration to the the registrant

Throws:

TransactionException

RemoteException

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

notify

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

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 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.notify(Entry, Transaction, RemoteEventListener, long, MarshalledObject), NotifyModifiers, NotifyDelegator

takeMultiple

Object[] takeMultiple(Object template,
                      Transaction txn,
                      int maxEntries)
                      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");
 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.

maxEntries - 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

read

Object read(Object entry,
            Transaction transaction,
            long timeout)
            throws UnusableEntryException,
                   TransactionException,
                   InterruptedException,
                   RemoteException

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

Parameters:

entry - 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 object, if any, under which to perform the write lease the requested lease time, in milliseconds

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:

a object for the entry that was written to the space

Throws:

UnusableEntryException

TransactionException - - if a transaction error occurs,RemoteException - if a communication error occurs

InterruptedException

RemoteException

readIfExists

Object readIfExists(Object object,
                    Transaction transaction,
                    long timeout)
                    throws UnusableEntryException,
                           TransactionException,
                           InterruptedException,
                           RemoteException

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

Parameters:

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

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 IllegalArgumentException - if a negative timeout value is used

TransactionException

InterruptedException

RemoteException

take

Object take(Object object,
            Transaction transaction,
            long timeout)
            throws UnusableEntryException,
                   TransactionException,
                   InterruptedException,
                   RemoteException

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

Parameters:

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

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

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:

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

TransactionException

InterruptedException

RemoteException

takeIfExists

Object takeIfExists(Object object,
                    Transaction transaction,
                    long timeout)
                    throws UnusableEntryException,
                           TransactionException,
                           InterruptedException,
                           RemoteException

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

Parameters:

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

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

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:

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

TransactionException

InterruptedException

RemoteException

clear

void clear(Object template,
           Transaction txn)
           throws RemoteException,
                  TransactionException,
                  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.

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 de serialized for any reason

RemoteException - if a communication error occurs

See Also:

clean()

count

int count(Object template,
          Transaction txn)
          throws RemoteException,
                 TransactionException,
                 UnusableEntryException

Counts the number of objects that match the specified template and the specified transaction.

 IJSpace aSpace = (IJSpace)SpaceFinder.find("jini://lookup-host/container-name/space-name");
 Object multiTmpl = new Message();
 int counted = aSpace.count(multiTmpl, null);
 System.out.println("There are " + counted + " matches in the space");
 

Parameters