com.j_spaces.jca
Class JSInteraction

java.lang.Object
  com.j_spaces.jca.JSInteraction

All Implemented Interfaces:

Interaction

Direct Known Subclasses:

GSInteraction

public class JSInteraction
extends Object
implements Interaction

JCA Interaction Class - provide basic JavaSpaces methods

Field Summary

static String	CLEAN_OPERATION
static String	CLEAR_OPERATION
static String	COUNT_OPERATION
static String	EXCEPTIONTYPE_REMOTEEXCEPTION
static String	EXCEPTIONTYPE_TX
static String	INSTANCE_COUNT_OPERATION
static String	NOTIFY_OPERATION
static String	READ_OPERATION
static String	SNAPSHOT_OPERATION
static String	TAKE_OPERATION
static String	WRITE_OPERATION

Constructor Summary

JSInteraction(GSConnection c)

Method Summary

void	clean() Cleans this space.
void	clear(Entry template) Removes the entries that match the specified template and the specified transaction from this space.
void	clear(Entry template, boolean isTx) Removes the entries that match the specified template and the specified transaction from this space.
void	clearWarnings()
void	close()
int	count(Entry template) Returns the number of entries that match the specified template and the specified transaction.
int	count(Entry template, boolean isTx) Returns the number of entries that match the specified template and the specified transaction.
Record	execute(InteractionSpec is, Record entry)
boolean	execute(InteractionSpec param1, Record param2, Record param3)
Connection	getConnection()
IRemoteJSpaceAdmin	getSpaceAdmin() Returns the admin object to the remote part of this space
String	getSpaceURL()
ResourceWarning	getWarnings()
boolean	isSecured() Return an indication : is this space secured.
EventRegistration	notify(Entry tmpl, RemoteEventListener listener) When entries are written that match this template notify the given listener with a RemoteEvent that includes the handback object.
Entry	read(Entry tmpl, boolean isTx, long timeout) Read any matching entry from the space, blocking until one exists.
Entry	read(Entry tmpl, long timeout) Read any matching entry from the space, blocking until one exists.
Entry	readIfExists(Entry tmpl, boolean isTx, long timeout) Read any matching entry from the space, returning null if there is currently is none.
Entry	readIfExists(Entry tmpl, long timeout) Read any matching entry from the space, returning null if there is currently is none.
Entry	snapshot(Entry entry) The process of serializing an entry for transmission to a JavaSpaces service will be identical if the same entry is used twice.
Entry	take(Entry tmpl, boolean isTx, long timeout) Take a matching entry from the space, waiting until one exists.
Entry	take(Entry tmpl, long timeout) Take a matching entry from the space, waiting until one exists.
Entry	takeIfExists(Entry tmpl, boolean isTx, long timeout) Take a matching entry from the space, returning null if there is currently is none.
Entry	takeIfExists(Entry tmpl, long timeout) Take a matching entry from the space, returning null if there is currently is none.
Lease	write(Entry entry, boolean isTx, long timeout) Write a new entry into the space.
Lease	write(Entry entry, long timeout) Write a new entry into the space.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TAKE_OPERATION

public static final String TAKE_OPERATION

See Also:

Constant Field Values

NOTIFY_OPERATION

public static final String NOTIFY_OPERATION

See Also:

Constant Field Values

WRITE_OPERATION

public static final String WRITE_OPERATION

See Also:

Constant Field Values

READ_OPERATION

public static final String READ_OPERATION

See Also:

Constant Field Values

SNAPSHOT_OPERATION

public static final String SNAPSHOT_OPERATION

See Also:

Constant Field Values

CLEAR_OPERATION

public static final String CLEAR_OPERATION

See Also:

Constant Field Values

CLEAN_OPERATION

public static final String CLEAN_OPERATION

See Also:

Constant Field Values

COUNT_OPERATION

public static final String COUNT_OPERATION

See Also:

Constant Field Values

INSTANCE_COUNT_OPERATION

public static final String INSTANCE_COUNT_OPERATION

See Also:

Constant Field Values

EXCEPTIONTYPE_TX

public static final String EXCEPTIONTYPE_TX

See Also:

Constant Field Values

EXCEPTIONTYPE_REMOTEEXCEPTION

public static final String EXCEPTIONTYPE_REMOTEEXCEPTION

See Also:

Constant Field Values

Constructor Detail

JSInteraction

public JSInteraction(GSConnection c)

Method Detail

clearWarnings

public void clearWarnings()
                   throws ResourceException

Specified by:

clearWarnings in interface Interaction

Throws:

ResourceException

getWarnings

public ResourceWarning getWarnings()
                            throws ResourceException

Specified by:

getWarnings in interface Interaction

Throws:

ResourceException

getSpaceURL

public String getSpaceURL()
                   throws ResourceException

Throws:

ResourceException

close

public void close()
           throws ResourceException

Specified by:

close in interface Interaction

Throws:

ResourceException

execute

public Record execute(InteractionSpec is,
                      Record entry)
               throws ResourceException

Specified by:

execute in interface Interaction

Throws:

ResourceException

execute

public boolean execute(InteractionSpec param1,
                       Record param2,
                       Record param3)
                throws ResourceException

Specified by:

execute in interface Interaction

Throws:

ResourceException

getConnection

public Connection getConnection()

Specified by:

getConnection in interface Interaction

take

public Entry take(Entry tmpl,
                  long timeout)
           throws ResourceException

Take a matching entry from the space, waiting until one exists. Matching is and timeout done as for read.

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

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:

the entry taken 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 take occurs is interrupted

IllegalArgumentException - - if a negative timeout value is used

ResourceException - - if a communication error occurs

take

public Entry take(Entry tmpl,
                  boolean isTx,
                  long timeout)
           throws ResourceException

Take a matching entry from the space, waiting until one exists. Matching is and timeout done as for read.

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

isTx - true indicates method to be done under transaction. false - without transcation true indicates method to be done under transaction. false - without transcation

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:

the entry taken 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 take occurs is interrupted

IllegalArgumentException - - if a negative timeout value is used

ResourceException - - if a communication error occurs

takeIfExists

public Entry takeIfExists(Entry tmpl,
                          long timeout)
                   throws ResourceException

Take a matching entry from the space, returning null if there is currently is none. Matching is and timeout done as for read, except that blocking in this call is done only if necessary to wait for transactional state to settle.

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

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:

the entry taken 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 take occurs is interrupted

IllegalArgumentException - - if a negative timeout value is used

ResourceException - - if a communication error occurs

takeIfExists

public Entry takeIfExists(Entry tmpl,
                          boolean isTx,
                          long timeout)
                   throws ResourceException

Take a matching entry from the space, returning null if there is currently is none. Matching is and timeout done as for read, except that blocking in this call is done only if necessary to wait for transactional state to settle.

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

isTx - true indicates method to be done under transaction. false - without transcation

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:

the entry taken 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 take occurs is interrupted

IllegalArgumentException - - if a negative timeout value is used

ResourceException - - if a communication error occurs

read

public Entry read(Entry tmpl,
                  long timeout)
           throws ResourceException

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

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

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

IllegalArgumentException - - if a negative timeout value is used

ResourceException - - if a communication error occurs

read

public Entry read(Entry tmpl,
                  boolean isTx,
                  long timeout)
           throws ResourceException

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

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

isTx - true indicates method to be done under transaction. false - without transcation

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

IllegalArgumentException - - if a negative timeout value is used

ResourceException - - if a communication error occurs

readIfExists

public Entry readIfExists(Entry tmpl,
                          long timeout)
                   throws ResourceException

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

Parameters:

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

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

IllegalArgumentException - - if a negative timeout value is used

ResourceException - - if a communication error occurs

readIfExists

public Entry readIfExists(Entry tmpl,
                          boolean isTx,
                          long timeout)
                   throws ResourceException

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

Parameters:

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

isTx - true indicates method to be done under transaction. false - without transcation

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

IllegalArgumentException - - if a negative timeout value is used

ResourceException - - if a communication error occurs

snapshot

public Entry snapshot(Entry entry)
               throws ResourceException

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

Parameters:

entry - - the entry to take a snapshot of.

Returns:

a snapshot of the entry.

Throws:

ResourceException - - if a communication error occurs

write

public Lease write(Entry entry,
                   long timeout)
            throws ResourceException

Write a new entry into the space.

Parameters:

entry - - the entry to write

timeout - - the requested lease time, in milliseconds

Returns:

a lease for the entry that was written to the space

Throws:

TransactionException - - if a transaction error occurs

ResourceException - - if a communication error occurs

write

public Lease write(Entry entry,
                   boolean isTx,
                   long timeout)
            throws ResourceException

Write a new entry into the space.

Parameters:

entry - - the entry to write

isTx - true indicates method to be done under transaction. false - without transcation

timeout - - the requested lease time, in milliseconds

Returns:

a lease for the entry that was written to the space

Throws:

TransactionException - - if a transaction error occurs

ResourceException - - if a communication error occurs

notify

public EventRegistration notify(Entry tmpl,
                                RemoteEventListener listener)
                         throws ResourceException

When entries are written that match this template notify the given listener with a RemoteEvent that includes the handback object. Matching is done as for read. Parameters:

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

listener - - The remote event listener to notify.

Returns:

the event registration to the the registrant

Throws:

TransactionException - - if a transaction error occurs

ResourceException - - if a communication error occurs

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

clean

public void clean()
           throws ResourceException

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-initalizes itself.

Throws:

ResourceException

clear

public void clear(Entry template)
           throws ResourceException

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

Parameters:

template - The template used for matching.

Throws:

TransactionException

UnusableEntryException

ResourceException

clear

public void clear(Entry template,
                  boolean isTx)
           throws ResourceException

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

Parameters:

template - The template used for matching.

isTx - true indicates method to be done under transaction. false - without transcation

Throws:

TransactionException

UnusableEntryException

ResourceException

count

public int count(Entry template)
          throws ResourceException

Returns the number of entries that match the specified template and the specified transaction.

Parameters:

template - The template used for matching.

Throws:

TransactionException

UnusableEntryException

ResourceException

count

public int count(Entry template,
                 boolean isTx)
          throws ResourceException

Returns the number of entries that match the specified template and the specified transaction.

Parameters:

template - The template used for matching.

isTx - true indicates method to be done under transaction. false - without transcation true indicates method to be done under transaction. false - without transcation

Throws:

TransactionException

UnusableEntryException

ResourceException

getSpaceAdmin

public IRemoteJSpaceAdmin getSpaceAdmin()
                                 throws ResourceException

Returns the admin object to the remote part of this space

Throws:

ResourceException

isSecured

public boolean isSecured()
                  throws ResourceException

Return an indication : is this space secured.

Throws:

ResourceException