com.sun.jini.outrigger
Class SpaceProxy2

java.lang.Object
  extended by com.sun.jini.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 JavaSpacesTM 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
private static class SpaceProxy2.ReadProperityPrivilegedAction
          PrivilegedAction for reading a property.
 
Field Summary
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 com.sun.jini.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
SpaceProxy2(OutriggerServer space, Uuid spaceUuid, long serverMaxServerQueryTimeout)
          Create a new SpaceProxy2 for the given space.
 
Method Summary
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 com.sun.jini.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 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 com.sun.jini.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 "com.sun.jini.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 com.sun.jini.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:

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



Copyright 2007-2010, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.