org.apache.river.outrigger

Class SpaceProxy2

java.lang.Object

org.apache.river.outrigger.SpaceProxy2

All Implemented Interfaces:

Serializable, Administrable, ReferentUuid, JavaSpace, JavaSpace05

Direct Known Subclasses:

ConstrainableSpaceProxy2

class SpaceProxy2
extends Object
implements JavaSpace05, Administrable, ReferentUuid, Serializable

This class is the client-side proxy for the Outrigger implementation of a JavaSpaces^TM service. OutriggerServerImpl implements the OutriggerSpace interface, and each SpaceProxy2 object holds a reference to the remote OutriggerSpace server it represents to the client. The client makes calls from the JavaSpace interface, which the SpaceProxy2 translates into appropriate OutriggerSpace calls to the OutriggerServerImpl server.

Author:

Sun Microsystems, Inc.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	SpaceProxy2.ReadProperityPrivilegedAction PrivilegedAction for reading a property.

Field Summary

Fields

Modifier and Type	Field and Description
private static Logger	logger Logger for logging information about operations carried out in the client.
private long	maxServerQueryTimeout Maximum time any sub-query should be allowed to run for.
private static long	maxServerQueryTimeoutPropertyValue Value (as a long) of the org.apache.river.outrigger.maxServerQueryTimeout property in this VM, or a non-positive number if it is not set.
(package private) static long	serialVersionUID
(package private) long	serverMaxServerQueryTimeout The value to use for maxServerQueryTimeout if no local value is provided.
(package private) OutriggerServer	space The remote server this proxy works with.
(package private) Uuid	spaceUuid The Uuid that identifies the space this proxy is for.

Fields inherited from interface net.jini.space.JavaSpace

NO_WAIT

Constructor Summary

Constructors

Constructor and Description
SpaceProxy2(OutriggerServer space, Uuid spaceUuid, long serverMaxServerQueryTimeout) Create a new SpaceProxy2 for the given space.

Method Summary

Modifier and Type	Method and Description
private long	calcEndTime(long timeout) Utility method to calculate the absolute end time of a query.
protected Lease	constructLease(Uuid uuid, long expiration) Create a new lease with the specified id and initial expiration
MatchSet	contents(Collection tmpls, Transaction txn, long leaseDuration, long maxEntries) Creates a match set that can be used to exhaustively read through all of the matching entries in the space that are visible to the passed Transaction and remain visible for the lifetime of the match set.
(package private) static Entry	entryFrom(EntryRep rep) Return an entry generated from the given rep.
boolean	equals(Object other)
Object	getAdmin() Returns an object that implements whatever administration interfaces are appropriate for the particular service.
private static long	getMaxServerQueryTimeoutPropertyValue() Safely read the value of org.apache.river.outrigger.maxServerQueryTimeout.
Uuid	getReferentUuid() Return the Uuid that has been assigned to the resource this proxy represents.
int	hashCode()
private void	logQuery(String op, long serverTimeout, OutriggerServer.QueryCookie cookie, long remaining) Log query call to server
protected Lease	newLease(Uuid uuid, long duration) Create a new lease with the specified id and initial duration
EventRegistration	notify(Entry tmpl, Transaction txn, RemoteEventListener listener, long lease, MarshalledObject handback) When entries are written that match this template notify the given listener with a RemoteEvent that includes the handback object.
Entry	read(Entry tmpl, Transaction txn, long timeout) Read any matching entry from the space, blocking until one exists.
Entry	readIfExists(Entry tmpl, Transaction txn, long timeout) Read any matching entry from the space, returning null if there is currently is none.
private void	readObject(ObjectInputStream in) Read this object back setting the maxServerQueryTimeout field and validate state.
private void	readObjectNoData() We should always have data in the stream, if this method gets called there is something wrong.
EventRegistration	registerForAvailabilityEvent(Collection tmpls, Transaction txn, boolean visibilityOnly, RemoteEventListener listener, long leaseDuration, MarshalledObject handback) Register for events triggered when a matching Entry transitions from unavailable to available.
(package private) static EntryRep[]	repFor(Collection entries, String argName)
(package private) static EntryRep	repFor(Entry entry) Return an EntryRep object for the given Entry.
private void	setMaxServerQueryTimeout() Set maxServerQueryTimeout based on the values of serverMaxServerQueryTimeout and maxServerQueryTimeoutPropertyValue.
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.
Collection	take(Collection tmpls, Transaction txn, long timeout, long maxEntries) This method provides an overload of the JavaSpace.take method that attempts to remove, optionally under a Transaction, and return one or more entries from the space.
Entry	take(Entry tmpl, Transaction txn, long timeout) Take a matching entry from the space, waiting until one exists.
Entry	takeIfExists(Entry tmpl, Transaction txn, long timeout) Take a matching entry from the space, returning null if there is currently is none.
String	toString()
Lease	write(Entry entry, Transaction txn, long lease) Write a new entry into the space.
List	write(List entries, Transaction txn, List leaseDurations) This method provides an overload of the JavaSpace.write method that allows new copies of multiple Entry instances to be stored in the space using a single call.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

serialVersionUID

static final long serialVersionUID

See Also:

Constant Field Values

space

final OutriggerServer space

The remote server this proxy works with. Package protected so it can be read by subclasses and proxy verifier

spaceUuid

final Uuid spaceUuid

The Uuid that identifies the space this proxy is for. Package protected so it can be read by subclasses and proxy verifier

serverMaxServerQueryTimeout

final long serverMaxServerQueryTimeout

The value to use for maxServerQueryTimeout if no local value is provided. Package protected so it can be read by subclasses.

maxServerQueryTimeout

private transient volatile long maxServerQueryTimeout

Maximum time any sub-query should be allowed to run for.

maxServerQueryTimeoutPropertyValue

private static final long maxServerQueryTimeoutPropertyValue

Value (as a long) of the org.apache.river.outrigger.maxServerQueryTimeout property in this VM, or a non-positive number if it is not set.

logger

private static final Logger logger

Logger for logging information about operations carried out in the client. Note, we hard code "org.apache.river.outrigger" so we don't drag in OutriggerServerImpl to outrigger-dl.jar.

Constructor Detail

SpaceProxy2

SpaceProxy2(OutriggerServer space,
            Uuid spaceUuid,
            long serverMaxServerQueryTimeout)

Create a new SpaceProxy2 for the given space.

Parameters:

space - The OutriggerServer for the space.

spaceUuid - The universally unique ID for the space

serverMaxServerQueryTimeout - The value this proxy should use for the maxServerQueryTimeout if no local value is provided.

Throws:

NullPointerException - if space or spaceUuid is null.

IllegalArgumentException - if serverMaxServerQueryTimeout is not larger than zero.

Method Detail

toString

public String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object other)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

getReferentUuid

public Uuid getReferentUuid()

Description copied from interface: ReferentUuid

Return the Uuid that has been assigned to the resource this proxy represents.

Specified by:

getReferentUuid in interface ReferentUuid

Returns:

the Uuid associated with the resource this proxy represents. Will not return null.

getMaxServerQueryTimeoutPropertyValue

private static long getMaxServerQueryTimeoutPropertyValue()

Safely read the value of org.apache.river.outrigger.maxServerQueryTimeout. If it can't be read return -1.

setMaxServerQueryTimeout

private void setMaxServerQueryTimeout()

Set maxServerQueryTimeout based on the values of serverMaxServerQueryTimeout and maxServerQueryTimeoutPropertyValue.

readObject

private void readObject(ObjectInputStream in)
                 throws IOException,
                        ClassNotFoundException

Read this object back setting the maxServerQueryTimeout field and validate state.

Throws:

IOException

ClassNotFoundException

readObjectNoData

private void readObjectNoData()
                       throws InvalidObjectException

We should always have data in the stream, if this method gets called there is something wrong.

Throws:

InvalidObjectException

write

public Lease write(Entry entry,
                   Transaction txn,
                   long lease)
            throws TransactionException,
                   RemoteException

Description copied from interface: JavaSpace

Write a new entry into the space.

Specified by:

write in interface JavaSpace

Parameters:

entry - the entry to write

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

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

RemoteException - if a communication error occurs

read

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

Description copied from interface: JavaSpace

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

Specified by:

read in interface JavaSpace

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

readIfExists

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

Description copied from interface: JavaSpace

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.

Specified by:

readIfExists in interface JavaSpace

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

See Also:

JavaSpace.read(net.jini.core.entry.Entry, net.jini.core.transaction.Transaction, long)

take

public Entry take(Entry tmpl,
                  Transaction txn,
                  long timeout)
           throws UnusableEntryException,
                  TransactionException,
                  InterruptedException,
                  RemoteException

Description copied from interface: JavaSpace

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

Specified by:

take in interface JavaSpace

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

RemoteException - if a communication error occurs

See Also:

JavaSpace.read(net.jini.core.entry.Entry, net.jini.core.transaction.Transaction, long)

takeIfExists

public Entry takeIfExists(Entry tmpl,
                          Transaction txn,
                          long timeout)
                   throws UnusableEntryException,
                          TransactionException,
                          InterruptedException,
                          RemoteException

Description copied from interface: JavaSpace

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.

Specified by:

takeIfExists in interface JavaSpace

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

RemoteException - if a communication error occurs

See Also:

JavaSpace.read(net.jini.core.entry.Entry, net.jini.core.transaction.Transaction, long)

snapshot

public Entry snapshot(Entry entry)
               throws MarshalException

Description copied from interface: JavaSpace

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.

Specified by:

snapshot in interface JavaSpace

Parameters:

entry - the entry to take a snapshot of.

Returns:

a snapshot of the entry.

Throws:

MarshalException

notify

public EventRegistration notify(Entry tmpl,
                                Transaction txn,
                                RemoteEventListener listener,
                                long lease,
                                MarshalledObject handback)
                         throws TransactionException,
                                RemoteException

Description copied from interface: JavaSpace

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.

Specified by:

notify in interface JavaSpace

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.

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 - if a transaction error occurs

RemoteException - if a communication error occurs

See Also:

JavaSpace.read(net.jini.core.entry.Entry, net.jini.core.transaction.Transaction, long), EventRegistration

write

public List write(List entries,
                  Transaction txn,
                  List leaseDurations)
           throws RemoteException,
                  TransactionException

Description copied from interface: JavaSpace05

This method provides an overload of the JavaSpace.write method that allows new copies of multiple Entry instances to be stored in the space using a single call. The client may specify a Transaction for the operation to be performed under. Each Entry to be stored in the space has a separate requested initial lease duration.

The effect on the space of an invocation of this method successfully storing an Entry is the same as if the Entry had been successfully stored by a call to the singleton form of write under txn with the given requested initial lease duration. This method returns the proxies to the leases for each newly stored Entry by returning a List of Lease instances. The i th element of the returned List will be a proxy for the lease on the Entry created from the i th element of entries.

If an invocation of this method returns normally, then a new copy of each element of entries must have been stored in the space. A new copy of each element will be stored even if there are duplicates (either in terms of object identity or of entry equivalence) in entries.

The order in which the entries stored by an invocation of this method will become visible in the space is unspecified, and different observers may see the entries become visible in different orders.

If a TransactionException, SecurityException, IllegalArgumentException, or NullPointerException is thrown, no entries will have been added to the space by this operation. If a RemoteException is thrown, either new copies of all of the elements of entries will have been stored or no entries will have been stored; that is, in the case of a RemoteException, the storing of new entries in the space will either fail or succeed as a unit.

Specified by:

write in interface JavaSpace05

Parameters:

entries - a List of Entry instances to be written to the space

txn - the Transaction this operation should be performed under, may be null

leaseDurations - a List of Longs representing the requested initial lease durations

Returns:

a List of Lease instances, one for each element of entries, may be immutable. The space will not keep a reference to the result

Throws:

RemoteException - if a communication error occurs

TransactionException - if txn is non-null and is not usable by the space

take

public Collection take(Collection tmpls,
                       Transaction txn,
                       long timeout,
                       long maxEntries)
                throws UnusableEntriesException,
                       TransactionException,
                       RemoteException

Description copied from interface: JavaSpace05

This method provides an overload of the JavaSpace.take method that attempts to remove, optionally under a Transaction, and return one or more entries from the space. Each Entry taken will match one or more elements of the passed Collection of templates, and all of the taken entries will be visible to the passed Transaction. If there are initially no matches in the space that are visible to the passed Transaction, an invocation of this method will block for up to a specified timeout for one or more matches to appear.

The effect on the space of an invocation of this method successfully taking an Entry will be the same as if the Entry had been taken using the singleton version of this method and passing txn as the Transaction.

The tmpls parameter must be a Collection of Entry instances to be used as templates. All of the entries taken must match one or more of these templates. The tmpls parameter may contain null values and may contain duplicates. An Entry is said to be available to an invocation of this method if the Entry could have been returned by an invocation of the singleton take method using txn.

If the method succeeds, a non-null Collection will be returned. The Collection will contain a copy of each Entry that was taken. If no entries were taken, the Collection will be empty. Each Entry taken will be represented by a distinct Entry instance in the returned Collection, even if some of the entries are equivalent to others taken by the operation. There will be no null elements in the returned Collection.

If one or more of the entries taken cannot be unmarshalled in the client, an UnusableEntriesException is thrown. The exception's UnusableEntriesException.getEntries method will return a Collection with a copy of each Entry that could be unmarshalled. The UnusableEntriesException.getUnusableEntryExceptions method will return a Collection with an UnusableEntryException for each Entry that could not be unmarshalled. Every Entry taken by the invocation will either be represented in the Collection returned by getEntries or in the Collection returned by getUnusableEntryExceptions.

If there is at least one matching Entry available in the space, an invocation of this method must take at least one Entry. If more than one matching Entry is available, the invocation may take additional entries. It must not take more than maxEntries, but an implementation may chose to take fewer entries from the space than the maximum available or the maximum allowed by maxEntries. If for whatever reason, an invocation of this method takes fewer entries than the maximum number of available matching entries, how an implementation selects which entries should be taken by the invocation and which are left in the space is unspecified. How consumption of entries is arbitrated between conflicting queries is also unspecified.

If there are initially no matching entries in the space, an invocation of this method should block for up to timeout milliseconds for a match to appear. If one or more matches become available before timeout expires, one or more of the newly available entries should be taken and the method should return without further blocking. If for some reason the invocation can't block for the full timeout and no entries have been taken, the invocation must fail with a RemoteException or TransactionException as appropriate.

If an invocation of this method removes (or locks) more than one Entry, the order in which the removal (or locking) occurs is undefined, and different observers may see the removal or locking of the entries in different orders.

If a TransactionException, SecurityException, IllegalArgumentException, or NullPointerException is thrown, no entries will have been taken. If a RemoteException is thrown, up to maxEntries may have been taken by this operation.

Specified by:

take in interface JavaSpace05

Parameters:

tmpls - a Collection of Entry instances, each representing a template. All of the entries taken by an invocation of this method will match one or more elements of tmpls

txn - the Transaction this operation should be performed under, may be null

timeout - if there are initially no available matches in the space, the maximum number of milliseconds to block waiting for a match to become available

maxEntries - the maximum number of entries that may be taken by this method

Returns:

a Collection that contains a copy of each Entry taken from the space by this method. The space will not keep a reference to this Collection. May be immutable

Throws:

UnusableEntriesException - if one or more of the entries taken can't be unmarshalled in the client

TransactionException - if txn is non-null and is not usable by the space.

RemoteException - if a communication error occurs

registerForAvailabilityEvent

public EventRegistration registerForAvailabilityEvent(Collection tmpls,
                                                      Transaction txn,
                                                      boolean visibilityOnly,
                                                      RemoteEventListener listener,
                                                      long leaseDuration,
                                                      MarshalledObject handback)
                                               throws TransactionException,
                                                      RemoteException

Description copied from interface: JavaSpace05

Register for events triggered when a matching Entry transitions from unavailable to available. The resulting events will be instances of the AvailabilityEvent class and the AvailabilityEvent.getEntry method will return a copy of the Entry whose transition triggered the event.

An Entry makes a transition from unavailable to available when it goes from being in a state where it could not be returned by a JavaSpace.take using txn to a state where it could be returned. An Entry makes a transition from invisible to visible when it goes from being in a state where it could not be returned by a JavaSpace.read using txn to a state where it could be returned. Note, any transition from invisible to visible is also a transition from unavailable to available, but an already visible entry can be unavailable and then make a transition from unavailable to available. Because the entry was already visible, this transition would not be a transition from invisible to visible.

The tmpls parameter must be a Collection of Entry instances to be used as templates. Events will be generated when an Entry that matches one or more of these templates makes an appropriate transition. A single transition will generate only one event per registration, in particular the transition of an Entry that matches multiple elements of tmpls must still generate exactly one event for this registration. If a given Entry undergoes multiple applicable transitions while the registration is active, each must generate a separate event.

Events are not generated directly by the transition of matching entries, but instead by an abstract observer set up in the space for each registration. The observer may see the transitions out of order and as a result the order of the events generated for this registration (as determined by the sequence numbers assigned to the events) may be different from the order of the transitions themselves. Additionally, each registration will have its own abstract observer and different observers may see the same sequence of transitions in different orders. As a result, given a set of transitions that trigger events for two different registrations, the order of the events generated for one registration may differ from the order of the events generated for the other.

A non-null EventRegistration object will be returned. Each registration will be assigned an event ID. The event ID will be unique at least with respect to all other active event registrations for AvailabilityEvents on this space with a non-equivalent set of templates, a different transaction, and/or a different value for the visibilityOnly flag. The event ID can be obtained by calling the EventRegistration.getID method on the returned EventRegistration. The returned EventRegistration object's EventRegistration.getSource method will return a reference to the space.

Registrations are leased. leaseDurations represents the client's desired initial lease duration. If leaseDuration is positive, the initial lease duration will be a positive value less than or equal to leaseDuration. If leaseDuration is Lease.ANY, the space is free to pick any positive initial lease duration it desires. A proxy for the lease associated with the registration can be obtained by calling the returned EventRegistration's EventRegistration.getLease method.

A registration made with a non-null value for txn is implicitly dropped when the space observes txn has left the active state.

Specified by:

registerForAvailabilityEvent in interface JavaSpace05

Parameters:

tmpls - a Collection of Entry instances, each representing a template. Events for this registration will be generated by the transitions of entries matching one or more elements of tmpls

txn - the Transaction this operation should be performed under, may be null

visibilityOnly - if true, events will be generated for this registration only when a matching Entry transitions from invisible to visible, otherwise events will be generated when a matching Entry makes any transition from unavailable to available

listener - the object to which events generated for this registration should be delivered

leaseDuration - the requested initial lease time on the resulting event registration

handback - the MarshalledObject to be returned by the RemoteEvent.getRegistrationObject method of the events generated for this registration

Returns:

an EventRegistration object with information on this registration

Throws:

TransactionException - if txn is non-null and is not usable by the space

RemoteException - if a communication error occurs

contents

public MatchSet contents(Collection tmpls,
                         Transaction txn,
                         long leaseDuration,
                         long maxEntries)
                  throws RemoteException,
                         TransactionException

Description copied from interface: JavaSpace05

Creates a match set that can be used to exhaustively read through all of the matching entries in the space that are visible to the passed Transaction and remain visible for the lifetime of the match set. May also yield additional entries that match but are only visible for part of the lifetime of the match set.

The tmpls parameter must be a Collection of Entry instances to be used as templates. All of the entries placed in the match set will match one or more of these templates. tmpls may contain null values and may contain duplicates. An Entry is said to be visible to an invocation of this method if the Entry could have been returned by a singleton JavaSpace.read using the same transaction.

The resulting match set must initially contain all of the visible matching entries in the space. During the lifetime of the match set an Entry may be, but is not required to be, added to the match set if it becomes visible. If the match set becomes empty, no more entries can be added and the match set enters the exhausted state.

Normally there are three conditions under which an Entry might be removed from the match set:

• Any Entry yielded by an invocation of the MatchSet.next method on the match set (either as the return value of a successful call or embedded in an UnusableEntryException) must be removed from the match set.
• Any Entry that remains in the match set after maxEntries entries are yielded by next invocations must be removed from the match set. In such a case, the criteria used to select which entries are yielded by next calls and which get removed from the set at the end is unspecified.
• Any Entry that during the lifetime of the match set becomes invisible may at the discretion of the implementation be removed from the match set.

An implementation may decide to remove an Entry from the set for other reasons. If it does so, however, it must invalidate the set.

If txn is non-null and still active, any Entry removed from the match set by a next call must be locked as if it had been returned by a read operation using txn. An implementation may establish the read lock on the Entry any time between when the Entry is added to the match set and when the Entry is removed from the match set by an invocation of next. These read locks are not released when the match set reaches either the exhausted state or the invalidated state. If from the space's perspective the txn leaves the active state, the space must remove from the match set any entries in the match set that have not yet been read locked. This may require the match set to be invalidated.

If the match set is leased and leaseDuration is positive, the initial duration of the lease must be less than or equal to leaseDuration. If leaseDuration is Lease.ANY, the initial duration of the lease can be any positive value desired by the implementation.

If there are remote method constraints associated with an invocation of this method, any remote communications performed by or on behalf of the match set's next method will be performed in compliance with these constraints, not with the constraints (if any) associated with next.

Specified by:

contents in interface JavaSpace05

Parameters:

tmpls - a Collection of Entry instances, each representing a template. All the entries added to the resulting match set will match one or more elements of tmpls

txn - the Transaction this operation should be performed under, may be null

leaseDuration - the requested initial lease time on the resulting match set

maxEntries - the maximum number of entries to remove from the set via MatchSet.next calls

Returns:

A proxy to the newly created match set

Throws:

RemoteException - if a communication error occurs

TransactionException - if txn is non-null and is not usable by the space

newLease

protected final Lease newLease(Uuid uuid,
                               long duration)

Create a new lease with the specified id and initial duration

constructLease

protected Lease constructLease(Uuid uuid,
                               long expiration)

Create a new lease with the specified id and initial expiration

getAdmin

public Object getAdmin()
                throws RemoteException

Description copied from interface: Administrable

Returns an object that implements whatever administration interfaces are appropriate for the particular service.

Specified by:

getAdmin in interface Administrable

Returns:

an object that implements whatever administration interfaces are appropriate for the particular service.

Throws:

RemoteException

See Also:

JoinAdmin

calcEndTime

private long calcEndTime(long timeout)

Utility method to calculate the absolute end time of a query.

Parameters:

timeout - relative timeout of query.

Returns:

timeout plus the current time, or Long.MAX_VALUE if timeout plus the current time is larger than Long.MAX_VALUE.

repFor

static EntryRep[] repFor(Collection entries,
                         String argName)
                  throws MarshalException

Throws:

MarshalException

repFor

static EntryRep repFor(Entry entry)
                throws MarshalException

Return an EntryRep object for the given Entry.

Throws:

MarshalException

entryFrom

static Entry entryFrom(EntryRep rep)
                throws UnusableEntryException

Return an entry generated from the given rep.

Throws:

UnusableEntryException

logQuery

private void logQuery(String op,
                      long serverTimeout,
                      OutriggerServer.QueryCookie cookie,
                      long remaining)

Log query call to server