org.apache.river.outrigger

Class OutriggerServerImpl

java.lang.Object

org.apache.river.outrigger.OutriggerServerImpl

All Implemented Interfaces:

ServiceAttributesAccessor, ServiceIDAccessor, ServiceProxyAccessor, ServerProxyTrust, Startable, org.apache.river.constants.TimeConstants, LocalLandlord, Recover

public class OutriggerServerImpl
extends Object
implements org.apache.river.constants.TimeConstants, LocalLandlord, Recover, ServerProxyTrust, Startable, ServiceProxyAccessor, ServiceAttributesAccessor, ServiceIDAccessor

A basic implementation of a JavaSpaces^TM service. This class is designed for use by both transient and persistent instances. Persistence is delegated to Store and LogOps objects which handles the details of implementing a particular persistence strategy. If transient a null value is used for the LogOps object.

OutriggerServerImpl maintains a list of types of entries it has seen and their subtypes using a TypeTree object. Each type of entry has an EntryHolder that is stored in the EntryHolderSet object named contents.

On write, the written entry's class and superclass are added to the known types, and its EntryRep is added to the space's contents.

On read, the find method searches through the entries of its type and subtypes, asking each entry holder if it has an entry that matches the template. If a match is found, the matching EntryRep is returned. If none of the appropriate holders has a match, it will return null.

On take we also use find with a boolean that says to remove the entry that matches.

Notification requires a separate Notifier queue and thread. When an entry is written, a reference to it is added to the queue of "unexamined entries". The notifier thread pulls entries off the queue and checks them against registered notification templates. When it has found all matches for the template, the Notifier thread adds the notifications for this write to its list of undelivered notifications, which it periodically attempts to deliver.

On notify, the template is added to the TemplateHolderSet named template. This stores TemplateHolder objects for each known type.

In this implementation, EntryRep ID's are approximate time stamps.

Author:

Sun Microsystems, Inc.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	OutriggerServer.QueryCookie Marker interface for objects that represent state that the server finds useful to share across sub-queries.

Nested classes/interfaces inherited from interface org.apache.river.landlord.Landlord

Landlord.RenewResults

Field Summary

Fields

Modifier and Type	Field and Description
static String	COMPONENT_NAME Component name we use to find items in the configuration and loggers.
static String	PERSISTENCE_DIR_CONFIG_ENTRY The name of the configuration entry we use to get the the name of the log directory from.
static String	storeLoggerName Logger name for information related to persistence

Fields inherited from interface net.jini.core.transaction.server.TransactionConstants

ABORTED, ACTIVE, COMMITTED, NOTCHANGED, PREPARED, VOTING

Fields inherited from interface org.apache.river.constants.TimeConstants

DAYS, HOURS, MINUTES, SECONDS

Method Summary

Modifier and Type	Method and Description
void	abort(TransactionManager mgr, long id) Requests that the participant roll back any changes for the specified transaction and unlock any resources locked by the transaction.
void	addLookupAttributes(Entry[] attrSets) Add attribute sets for the service.
void	addLookupGroups(String[] groups) Add new groups to the set to join.
void	addLookupLocators(LookupLocator[] locators) Add locators for specific new lookup services to join.
void	cancel(Uuid cookie) Called by the lease when its cancel method is called.
Map	cancelAll(Uuid[] cookies) Called by the lease map when its cancelAll method is called.
void	close(Uuid iterationUuid) Forget about the indicated iteration
void	commit(TransactionManager mgr, long id) Requests that the participant make all of its PREPARED changes for the specified transaction visible outside of the transaction and unlock any resources locked by the transaction.
org.apache.river.outrigger.MatchSetData	contents(org.apache.river.outrigger.EntryRep[] tmpls, Transaction tr, long leaseTime, long limit) Start a new contents query.
Uuid	contents(org.apache.river.outrigger.EntryRep tmpl, Transaction tr) Return the remote iterator object needed by JavaSpaceAdmin.contents.
void	delete(Uuid iterationUuid, Uuid entryUuid) Delete the given entry if the given iteration is still valid and the entry was retured by the last call to nextReps.
void	destroy() Destroy this space, exiting when finished.
Object	getAdmin() Return a proxy that implements that JavaSpaceAdmin interface.
Entry[]	getLookupAttributes() Get the current attribute sets for the service.
String[]	getLookupGroups() Get the list of groups to join.
LookupLocator[]	getLookupLocators() Get the list of locators of specific lookup services to join.
TrustVerifier	getProxyVerifier() Returns a TrustVerifier that can be used to verify that a proxy can be trusted as a proxy for the service; that is, the isTrustedObject method of the returned verifier can be called with a candidate proxy.
Entry[]	getServiceAttributes()
Object	getServiceProxy() Returns a proxy object for this object.
void	modifyLookupAttributes(Entry[] attrSetTemplates, Entry[] attrSets) Modify the current attribute sets, using the same semantics as ServiceRegistration.modifyAttributes.
org.apache.river.outrigger.EntryRep[]	nextBatch(Uuid contentsQueryUuid, Uuid entryUuid) Return the next batch of entries associated with the specified contents query.
org.apache.river.outrigger.EntryRep[]	nextReps(Uuid iterationUuid, int max, Uuid entryUuid) Fetch up to max EntryRep objects from the specified iteration.
EventRegistration	notify(org.apache.river.outrigger.EntryRep tmpl, Transaction tr, RemoteEventListener listener, long leaseTime, MarshalledObject handback) When entries are written that match this template notify the given listener.
int	prepare(TransactionManager mgr, long id) Requests that the participant prepare itself to commit the transaction, and to vote on the outcome of the transaction.
int	prepareAndCommit(TransactionManager mgr, long id) A combination of prepare and commit, which can be used by the manager when there is just one participant left to prepare and all other participants (if any) have responded with NOTCHANGED.
Object	read(org.apache.river.outrigger.EntryRep tmpl, Transaction txn, long timeout, OutriggerServer.QueryCookie cookie) Find an entry in the space that matches the passed template and is visible to the passed transaction.
Object	readIfExists(org.apache.river.outrigger.EntryRep tmpl, Transaction txn, long timeout, OutriggerServer.QueryCookie cookie) Find an entry in the space that matches the passed template and is visible to the passed transaction.
void	recoverJoinState(StoredObject state) Recover the join state from the previous session.
void	recoverRegister(StoredResource registration, String type, StoredObject[] storedTemplates) Recover an event registration.
void	recoverSessionId(long sessionId) Recover the id from the previous session and determine the new basis value for the seq numbers issued by this session.
void	recoverTake(Uuid cookie, Long txnId) Recover a take operation.
void	recoverTransaction(Long txnId, StoredObject transaction) Recover a prepared transaction.
void	recoverUuid(Uuid uuid) Recover the Uuid for the service as a whole.
void	recoverWrite(StoredResource entry, Long txnId) Recover a write operation.
EventRegistration	registerForAvailabilityEvent(org.apache.river.outrigger.EntryRep[] tmpls, Transaction tr, boolean visibilityOnly, RemoteEventListener listener, long leaseTime, MarshalledObject handback) When entries that match one or more of the passed templates transition from invisible to visible notify the give listener.
void	removeLookupGroups(String[] groups) Remove groups from the set to join.
void	removeLookupLocators(LookupLocator[] locators) Remove locators for specific lookup services from the set to join.
long	renew(Uuid cookie, long extension) Called by the lease when its renew method is called.
Landlord.RenewResults	renewAll(Uuid[] cookies, long[] extensions) Called by the lease map when its renewAll method is called.
ServiceID	serviceID()
void	setLookupGroups(String[] groups) Replace the list of groups to join with a new list.
void	setLookupLocators(LookupLocator[] locators) Replace the list of locators of specific lookup services to join with a new list.
JavaSpace	space() Return the space administered by this object.
void	start() Called after construction, this method enables objects to delay starting threads or exporting until after construction is complete, to allow safe publication of the service in accordance with the JMM.
Object	take(org.apache.river.outrigger.EntryRep[] tmpls, Transaction tr, long timeout, int limit, OutriggerServer.QueryCookie queryCookieFromClient) Find and remove up to limit entries in the space that match one or more of the passed templates and are visible to the passed transaction.
Object	take(org.apache.river.outrigger.EntryRep tmpl, Transaction txn, long timeout, OutriggerServer.QueryCookie cookie) Find and remove an entry in the space that matches the passed template and is visible to the passed transaction.
Object	takeIfExists(org.apache.river.outrigger.EntryRep tmpl, Transaction txn, long timeout, OutriggerServer.QueryCookie cookie) Find and remove an entry in the space that matches the passed template and is visible to the passed transaction.
long[]	write(org.apache.river.outrigger.EntryRep[] entries, Transaction tr, long[] leaseTimes) Write a set of entries into the space.
long[]	write(org.apache.river.outrigger.EntryRep rep, Transaction tr, long lease) Write a new entry into the space.

Methods inherited from class java.lang.Object

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

Field Detail

COMPONENT_NAME

public static final String COMPONENT_NAME

Component name we use to find items in the configuration and loggers.

See Also:

Constant Field Values

storeLoggerName

public static final String storeLoggerName

Logger name for information related to persistence

See Also:

Constant Field Values

PERSISTENCE_DIR_CONFIG_ENTRY

public static final String PERSISTENCE_DIR_CONFIG_ENTRY

The name of the configuration entry we use to get the the name of the log directory from.

See Also:

Constant Field Values

Method Detail

start

public void start()
           throws IOException,
                  ConfigurationException,
                  LoginException

Description copied from interface: Startable

Called after construction, this method enables objects to delay starting threads or exporting until after construction is complete, to allow safe publication of the service in accordance with the JMM.

In addition to starting threads after construction, it also allows objects to avoid throwing an exception during construction to avoid finalizer attacks.

The implementation is required to ensure start() is idempotent (only executed once, additional invocations must return immediately).

Specified by:

start in interface Startable

Throws:

IOException

ConfigurationException

LoginException

getServiceAttributes

public Entry[] getServiceAttributes()
                             throws IOException

Specified by:

getServiceAttributes in interface ServiceAttributesAccessor

Returns:

Throws:

IOException

serviceID

public ServiceID serviceID()
                    throws IOException

Specified by:

serviceID in interface ServiceIDAccessor

Throws:

IOException

write

public long[] write(org.apache.river.outrigger.EntryRep rep,
                    Transaction tr,
                    long lease)
             throws TransactionException,
                    RemoteException

Write a new entry into the space.

Parameters:

rep - The EntryRep representing the Entry.

tr - the Transaction.

lease - the lease duration.

Returns:

an array consisting of three long values, the lease duration, followed by the least significant bits, then the most significant bits of the EntryRep's Uuid.

Throws:

TransactionException - A transaction error occurred

RemoteException - if a communication related exception occurs.

write

public long[] write(org.apache.river.outrigger.EntryRep[] entries,
                    Transaction tr,
                    long[] leaseTimes)
             throws TransactionException,
                    RemoteException

Write a set of entries into the space.

Parameters:

entries - array of entries to be written into the space.

tr - the Transaction

leaseTimes - for each EntryRep in entries at the same array index.

Returns:

an array of longs that can be used to construct the leases on the client side. The array will have 3 elements for each lease, the first will be the duration, followed by the high order bits of the Uuid and then the lower order bits of the Uuid.

Throws:

TransactionException - A transaction error occurred

RemoteException - if a connection related exception occurs.

notify

public EventRegistration notify(org.apache.river.outrigger.EntryRep tmpl,
                                Transaction tr,
                                RemoteEventListener listener,
                                long leaseTime,
                                MarshalledObject handback)
                         throws TransactionException,
                                RemoteException

When entries are written that match this template notify the given listener. Matching is done as for read.

Parameters:

tmpl - template

tr - transaction

listener - listener

leaseTime - lease duration in milliseconds

handback - MarshalledObject.

Returns:

the EventRegistration.

Throws:

TransactionException - if a transaction related exception occurs.

RemoteException - if a communication related exception occurs.

registerForAvailabilityEvent

public EventRegistration registerForAvailabilityEvent(org.apache.river.outrigger.EntryRep[] tmpls,
                                                      Transaction tr,
                                                      boolean visibilityOnly,
                                                      RemoteEventListener listener,
                                                      long leaseTime,
                                                      MarshalledObject handback)
                                               throws TransactionException,
                                                      RemoteException

When entries that match one or more of the passed templates transition from invisible to visible notify the give listener. Matching is done as for read.

Parameters:

tmpls - the templates that specify what entries should generate events

tr - if non-null entries that become visible to txn should generate events even if txn is never committed. Registration is terminated when txn leaves the active state

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 - object to notify when an entry becomes (re)visible

leaseTime - initial requested lease time for the registration

handback - object to be included with every notification

Returns:

An object with information on the registration

Throws:

TransactionException - if txn is non-null and not active or otherwise invalid

RemoteException - if a connection related exception occurs.

cancel

public void cancel(Uuid cookie)
            throws UnknownLeaseException

Description copied from interface: Landlord

Called by the lease when its cancel method is called. Cancels the lease that is associated with the given cookie.

Specified by:

cancel in interface LocalLandlord

Parameters:

cookie - the Uuid associated with the lease who's renew method was called

Throws:

UnknownLeaseException - if landlord does not know about a lease with the specified cookie

renew

public long renew(Uuid cookie,
                  long extension)
           throws UnknownLeaseException,
                  LeaseDeniedException

Description copied from interface: Landlord

Called by the lease when its renew method is called. Renews the lease that is associated with the given cookie.

Specified by:

renew in interface LocalLandlord

Parameters:

cookie - the Uuid associated with the lease who's renew method was called

extension - argument passed to the renew call

Returns:

The new duration the lease should have

Throws:

UnknownLeaseException - if landlord does not know about a lease with the specified cookie

LeaseDeniedException - if the landlord is unwilling to renew the lease

renewAll

public Landlord.RenewResults renewAll(Uuid[] cookies,
                                      long[] extensions)

Description copied from interface: Landlord

Called by the lease map when its renewAll method is called. Should renew the lease that is associated with each element of cookies

Parameters:

cookies - an array of Uuids, each universally and uniquely identifying a lease granted by this Landlord

extensions - an array of longs, each representing an a duration in milliseconds that the client wants the lease associated with the Uuid from the corresponding element of cookies renewed for

Returns:

A RenewResults object that contains the new duration of each lease that was successfully renewed or the exception encountered for each lease that could not be renewed

cancelAll

public Map cancelAll(Uuid[] cookies)

Description copied from interface: Landlord

Called by the lease map when its cancelAll method is called. Should cancel the lease that is associated with each element of cookies This method is now default, because it is unsafe to return a Map that has been serialized, without having its invariants checked during deserialization. A gadget attack could utilize the map to contain other objects.

Parameters:

cookies - an array of Uuids, each universally and uniquely identifying a lease granted by this Landlord

Returns:

If all the leases specified in the cookies could be canceled return null. Otherwise, return a Map that for each failed cancel attempt maps the corresponding cookie object to an exception describing the failure.

read

public Object read(org.apache.river.outrigger.EntryRep tmpl,
                   Transaction txn,
                   long timeout,
                   OutriggerServer.QueryCookie cookie)
            throws TransactionException,
                   RemoteException,
                   InterruptedException

Find an entry in the space that matches the passed template and is visible to the passed transaction. Depending on the state of the space and the arguments this call may block if no entry can be immediately returned. The proxy can specify the maximum period it is willing to wait for a response using the timeout parameter. The proxy may choose to breakup a query from the client with a very long timeout into a set of sub-queries. In such cases it may get a QueryCookie as response to the sub-queries, in these cases it should pass the QueryCookie to the next sub-query (if any) associated with the same request from the client.

If a match is found it is returned as an EntryRep. If txn is non-null the entry is read locked by the transaction, this allows other queries to read, but not take the entry. The lock will be released when the transaction is aborted or prepared.

If no match is found the call will block for up to the specified timeout for a match to appear. If there is still no match available the call will return a QueryCookie.

Parameters:

tmpl - The template that describes the entry being searched for. May be null if any visible entry is acceptable.

txn - The transaction the operation should be performed under. Maybe be null. If non-null and entry is found it will read locked/removed under this transaction.

timeout - The maximum number of milliseconds this call should block in the server before returning an answer (this not necessarily the timeout the client asked for.) A value of 0 indicates the initial search should be performed, but if no match can be found null or a QueryCookie (as appropriate) should be returned immediately.

cookie - If this call is a continuation of an earlier query, the cookie from the last sub-query.

Returns:

an EntryRep if match found, otherwise it will return a QueryCookie

Throws:

TransactionException - if there is a problem with the specified transaction such as it can not be joined, or leaves the active state before the call is complete.

RemoteException - if a network failure occurs.

InterruptedException - if the thread in the server is interrupted before the query can be completed.

take

public Object take(org.apache.river.outrigger.EntryRep tmpl,
                   Transaction txn,
                   long timeout,
                   OutriggerServer.QueryCookie cookie)
            throws TransactionException,
                   RemoteException,
                   InterruptedException

Find and remove an entry in the space that matches the passed template and is visible to the passed transaction. Depending on the state of the space and the arguments this call may block if no entry can be immediately returned. The proxy can specify the maximum period it is willing to wait for a response using the timeout parameter. The proxy may choose to breakup a query from the client with a very long timeout into a set of sub-queries. In such cases it may get a QueryCookie as response to the sub-queries, in these cases it should pass the QueryCookie to the next sub-query (if any) associated with the same request from the client.

If a match is found it is returned as an EntryRep. If txn is null the entry is removed from the space. If txn is non-null the entry is exclusively locked by the transaction and will be removed from the space if the transaction is committed.

If no match is found the call will block for up to the specified timeout for a match to appear. If there is still no match available the call will return a QueryCookie.

Parameters:

tmpl - The template that describes the entry being searched for. May be null if any visible entry is acceptable.

txn - The transaction the operation should be performed under. Maybe be null. If non-null and entry is found it will read locked/removed under this transaction.

timeout - The maximum number of milliseconds this call should block in the server before returning an answer (this not necessarily the timeout the client asked for.) A value of 0 indicates the initial search should be performed, but if no match can be found null or a QueryCookie (as appropriate) should be returned immediately.

cookie - If this call is a continuation of an earlier query, the cookie from the last sub-query.

Returns:

an EntryRep if a match is found, otherwise returns a QueryCookie.

Throws:

TransactionException - if there is a problem with the specified transaction such as it can not be joined, or leaves the active state before the call is complete.

RemoteException - if a network failure occurs.

InterruptedException - if the thread in the server is interrupted before the query can be completed.

readIfExists

public Object readIfExists(org.apache.river.outrigger.EntryRep tmpl,
                           Transaction txn,
                           long timeout,
                           OutriggerServer.QueryCookie cookie)
                    throws TransactionException,
                           RemoteException,
                           InterruptedException

Find an entry in the space that matches the passed template and is visible to the passed transaction. Depending on the state of the space and the arguments this call may block if no entry can be immediately returned. The proxy can specify the maximum period it is willing to wait for a response using the timeout parameter. The proxy may choose to breakup a query from the client with a very long timeout into a set of sub-queries. In such cases it may get a QueryCookie as response to the sub-queries, in these cases it should pass the QueryCookie to the next sub-query (if any) associated with the same request from the client.

If a match is found it is returned as an EntryRep. If txn is non-null the entry is read locked by the transaction, this allows other queries to read, but not take the entry. The lock will be released when the transaction is aborted or prepared.

If no match can be initially found the call will block until either the timeout expires or for a detectable period of time there are no entries in the space (visible to the transaction or not) that match the passed template. If at some point there are no matching entries in the space null will be returned. If the timeout expires and there are matching entries in the space but none are visible to the passed transaction a QueryCookie will be returned.

Parameters:

tmpl - The template that describes the entry being searched for. May be null if any visible entry is acceptable.

txn - The transaction the operation should be performed under. Maybe be null. If non-null and entry is found it will read locked/removed under this transaction.

timeout - The maximum number of milliseconds this call should block in the server before returning an answer (this not necessarily the timeout the client asked for.) A value of 0 indicates the initial search should be performed, but if no match can be found null or a QueryCookie (as appropriate) should be returned immediately.

cookie - If this call is a continuation of an earlier query, the cookie from the last sub-query.

Returns:

an EntryRep if a match is found, otherwise a QueryCookie

Throws:

TransactionException - if there is a problem with the specified transaction such as it can not be joined, or leaves the active state before the call is complete.

RemoteException - if a network failure occurs.

InterruptedException - if the thread in the server is interrupted before the query can be completed.

takeIfExists

public Object takeIfExists(org.apache.river.outrigger.EntryRep tmpl,
                           Transaction txn,
                           long timeout,
                           OutriggerServer.QueryCookie cookie)
                    throws TransactionException,
                           RemoteException,
                           InterruptedException

Find and remove an entry in the space that matches the passed template and is visible to the passed transaction. Depending on the state of the space and the arguments this call may block if no entry can be immediately returned. The proxy can specify the maximum period it is willing to wait for a response using the timeout parameter. The proxy may choose to breakup a query from the client with a very long timeout into a set of sub-queries. In such cases it may get a QueryCookie as response to the sub-queries, in these cases it should pass the QueryCookie to the next sub-query (if any) associated with the same request from the client.

If a match is found it is returned as an EntryRep. If txn is null the entry is removed from the space. If txn is non-null the entry is exclusively locked by the transaction and will be removed from the space if the transaction is committed.

If no match can be initially found the call will block until either the timeout expires or for a detectable period of time there are no entries in the space (visible to the transaction or not) that match the passed template. If at some point there are no matching entries in the space null will be returned. If the timeout expires and there are matching entries in the space but none are visible to the passed transaction a QueryCookie will be returned.

Parameters:

tmpl - The template that describes the entry being searched for. May be null if any visible entry is acceptable.

txn - The transaction the operation should be performed under. Maybe be null. If non-null and entry is found it will read locked/removed under this transaction.

timeout - The maximum number of milliseconds this call should block in the server before returning an answer (this not necessarily the timeout the client asked for.) A value of 0 indicates the initial search should be performed, but if no match can be found null or a QueryCookie (as appropriate) should be returned immediately.

cookie - If this call is a continuation of an earlier query, the cookie from the last sub-query.

Returns:

an EntryRep if a match is found, otherwise returns a QueryCookie.

Throws:

TransactionException - if there is a problem with the specified transaction such as it can not be joined, or leaves the active state before the call is complete.

RemoteException - if a network failure occurs.

InterruptedException - if the thread in the server is interrupted before the query can be completed.

take

public Object take(org.apache.river.outrigger.EntryRep[] tmpls,
                   Transaction tr,
                   long timeout,
                   int limit,
                   OutriggerServer.QueryCookie queryCookieFromClient)
            throws TransactionException,
                   RemoteException

Find and remove up to limit entries in the space that match one or more of the passed templates and are visible to the passed transaction. Depending on the state of the space and the arguments this call may block if no entry can be immediately returned. The proxy can specify the maximum period it is willing to wait for a response using the timeout parameter. The proxy may choose to breakup a query from the client with a very long timeout into a set of sub-queries. In such cases it may get a QueryCookie as response to the sub-queries, in these cases it should pass the QueryCookie to the next sub-query (if any) associated with the same request from the client.

If matchs are found they are returned as in an array of EntryRep. If txn is null the entries are removed from the space. If txn is non-null the entries are exclusively locked by the transaction and will be removed from the space if the transaction is committed.

If there are no matches the call will block for up to the specified timeout for a match to appear. If there is still no match available the call will return a QueryCookie.

Parameters:

tmpls - The templates that describes the entries being searched for

tr - The transaction the operation should be performed under. Maybe be null. If non-null and entries are found they will removed under this transaction.

timeout - The maximum number of milliseconds this call should block in the server before returning an answer (this not necessarily the timeout the client asked for.) A value of 0 indicates the initial search should be performed, but if no match can be found a QueryCookie should be returned immediately.

limit - The maximum number of entries that should be taken

queryCookieFromClient - If this call is a continuation of an earlier query, the cookie from the last sub-query.

Returns:

an array of EntryRep's if match is successful, otherwise a QueryCookie

Throws:

TransactionException - if there is a problem with the specified transaction such as it can not be joined, or leaves the active state before the call is complete.

RemoteException - if a network failure occurs.

contents

public org.apache.river.outrigger.MatchSetData contents(org.apache.river.outrigger.EntryRep[] tmpls,
                                                        Transaction tr,
                                                        long leaseTime,
                                                        long limit)
                                                 throws TransactionException,
                                                        RemoteException

Start a new contents query. Returns a MatchSetData with the initial batch of entries and (if applicable) the Uuid and initial lease duration. If the entire result set is contained in the returned MatchSetData the Uuid will be null and the lease duration will be -1.

Parameters:

tmpls - the templates to use for the iteration

tr - the transaction to perform the iteration under, may be null

leaseTime - the requested lease time

limit - the maximum number of entries to return

Returns:

A MatchSetData with the initial batch of entries and (if applicable) the Uuid and initial lease duration. Initial batch will be the empty array if there are no matching entries in the space

Throws:

TransactionException - if tr is non-null and can't be used

RemoteException - if a communication related exception occurs.

nextBatch

public org.apache.river.outrigger.EntryRep[] nextBatch(Uuid contentsQueryUuid,
                                                       Uuid entryUuid)
                                                throws NoSuchObjectException

Return the next batch of entries associated with the specified contents query. If the returned array is not full then the query is complete.

Parameters:

contentsQueryUuid - the id of the contents query

entryUuid - the id of the last entry in the last batch. If this does not match what the server has on recored it will re-send the previous batch.

Returns:

an array of EntryReps representing the next batch of entries from the query. Query is complete if array is not full. Returns an empty array if there are no entries left

Throws:

NoSuchObjectException - if the server has no record of contentsQueryUuid

getServiceProxy

public Object getServiceProxy()

Description copied from interface: ServiceProxyAccessor

Returns a proxy object for this object. This value should not be null.

Specified by:

getServiceProxy in interface ServiceProxyAccessor

Returns:

a proxy object reference

getAdmin

public Object getAdmin()

Return a proxy that implements that JavaSpaceAdmin interface.

Returns:

the admin proxy.

See Also:

JavaSpaceAdmin

space

public JavaSpace space()

Return the space administered by this object.

Returns:

JavaSpace administered by this object.

contents

public Uuid contents(org.apache.river.outrigger.EntryRep tmpl,
                     Transaction tr)
              throws TransactionException,
                     RemoteException

Return the remote iterator object needed by JavaSpaceAdmin.contents.

Parameters:

tmpl - EntryRep

tr - Transaction

Returns:

Uuid of the Iterator.

Throws:

TransactionException - if transaction not active or other transaction related problem occurs.

RemoteException - if a communication related exception occurs.

nextReps

public org.apache.river.outrigger.EntryRep[] nextReps(Uuid iterationUuid,
                                                      int max,
                                                      Uuid entryUuid)
                                               throws NoSuchObjectException

Fetch up to max EntryRep objects from the specified iteration.

Parameters:

iterationUuid - The Uuid of the iteration to fetch entries from.

max - Advice on the number of entries to return

entryUuid - Uuid of the last entry received by the caller. If this does not match the ID of the last entry sent by the iterator will re-send that last batch in place of a new batch. May be null in which case a new batch will be sent. The first call to next() should have id set to null

Returns:

an EntryRep array.

Throws:

NoSuchObjectException

delete

public void delete(Uuid iterationUuid,
                   Uuid entryUuid)
            throws NoSuchObjectException

Delete the given entry if the given iteration is still valid and the entry was retured by the last call to nextReps.

Parameters:

iterationUuid - The Uuid of a valid iteration.

entryUuid - the Uuid of the entry to be deleted.

Throws:

NoSuchObjectException

close

public void close(Uuid iterationUuid)
           throws NoSuchObjectException

Forget about the indicated iteration

Parameters:

iterationUuid - The Uuid iteration to close.

Throws:

NoSuchObjectException

destroy

public void destroy()

Destroy this space, exiting when finished. This unregisters itself and related objects, and then destroys the persistent state.

getLookupAttributes

public Entry[] getLookupAttributes()

Description copied from interface: JoinAdmin

Get the current attribute sets for the service.

Returns:

the current attribute sets for the service

addLookupAttributes

public void addLookupAttributes(Entry[] attrSets)

Description copied from interface: JoinAdmin

Add attribute sets for the service. The resulting set will be used for all future joins. The attribute sets are also added to all currently-joined lookup services.

Parameters:

attrSets - the attribute sets to add

modifyLookupAttributes

public void modifyLookupAttributes(Entry[] attrSetTemplates,
                                   Entry[] attrSets)

Description copied from interface: JoinAdmin

Modify the current attribute sets, using the same semantics as ServiceRegistration.modifyAttributes. The resulting set will be used for all future joins. The same modifications are also made to all currently-joined lookup services.

Parameters:

attrSetTemplates - the templates for matching attribute sets

attrSets - the modifications to make to matching sets

See Also:

ServiceRegistration.modifyAttributes(net.jini.core.entry.Entry[], net.jini.core.entry.Entry[])

getLookupGroups

public String[] getLookupGroups()

Description copied from interface: JoinAdmin

Get the list of groups to join. An empty array means the service joins no groups (as opposed to "all" groups).

Returns:

an array of groups to join. An empty array means the service joins no groups (as opposed to "all" groups).

See Also:

JoinAdmin.setLookupGroups(java.lang.String[])

addLookupGroups

public void addLookupGroups(String[] groups)

Description copied from interface: JoinAdmin

Add new groups to the set to join. Lookup services in the new groups will be discovered and joined.

Parameters:

groups - groups to join

See Also:

JoinAdmin.removeLookupGroups(java.lang.String[])

removeLookupGroups

public void removeLookupGroups(String[] groups)

Description copied from interface: JoinAdmin

Remove groups from the set to join. Leases are cancelled at lookup services that are not members of any of the remaining groups.

Parameters:

groups - groups to leave

See Also:

JoinAdmin.addLookupGroups(java.lang.String[])

setLookupGroups

public void setLookupGroups(String[] groups)

Description copied from interface: JoinAdmin

Replace the list of groups to join with a new list. Leases are cancelled at lookup services that are not members of any of the new groups. Lookup services in the new groups will be discovered and joined.

Parameters:

groups - groups to join

See Also:

JoinAdmin.getLookupGroups()

getLookupLocators

public LookupLocator[] getLookupLocators()

Description copied from interface: JoinAdmin

Get the list of locators of specific lookup services to join.

Returns:

the list of locators of specific lookup services to join

See Also:

JoinAdmin.setLookupLocators(net.jini.core.discovery.LookupLocator[])

addLookupLocators

public void addLookupLocators(LookupLocator[] locators)
                       throws RemoteException

Description copied from interface: JoinAdmin

Add locators for specific new lookup services to join. The new lookup services will be discovered and joined.

Parameters:

locators - locators of specific lookup services to join

Throws:

RemoteException - when a communication issue occurs.

See Also:

JoinAdmin.removeLookupLocators(net.jini.core.discovery.LookupLocator[])

removeLookupLocators

public void removeLookupLocators(LookupLocator[] locators)
                          throws RemoteException

Description copied from interface: JoinAdmin

Remove locators for specific lookup services from the set to join. Any leases held at the lookup services are cancelled.

Parameters:

locators - locators of specific lookup services to leave

Throws:

RemoteException - when a communication issue occurs.

See Also:

JoinAdmin.addLookupLocators(net.jini.core.discovery.LookupLocator[])

setLookupLocators

public void setLookupLocators(LookupLocator[] locators)
                       throws RemoteException

Description copied from interface: JoinAdmin

Replace the list of locators of specific lookup services to join with a new list. Leases are cancelled at lookup services that were in the old list but are not in the new list. Any new lookup services will be discovered and joined.

Parameters:

locators - locators of specific lookup services to join

Throws:

RemoteException - when a communication issue occurs.

See Also:

JoinAdmin.getLookupLocators()

recoverSessionId

public void recoverSessionId(long sessionId)

Recover the id from the previous session and determine the new basis value for the seq numbers issued by this session. The typical usage for this routine is to read from permanent store somehow the previous sessionId (basis) for sequence numbers used by the last invocation of Outrigger. This value is then passed into this routine where a new basis is computed. That newly computed value should then be stored in persistent store so the next time we crash we can bump the value again. Once the store has recovered the new sessionId should be persisted by calling bootOp(...,sessionId)

Specified by:

recoverSessionId in interface Recover

Parameters:

sessionId - Value used by the previous invocation of Outrigger

See Also:

LogOps.bootOp(long, long)

recoverJoinState

public void recoverJoinState(StoredObject state)
                      throws Exception

Description copied from interface: Recover

Recover the join state from the previous session.

Specified by:

recoverJoinState in interface Recover

Parameters:

state - is the stored join state

Throws:

Exception - if the state can't be recovered.

See Also:

LogOps.joinStateOp(org.apache.river.outrigger.StorableObject)

recoverWrite

public void recoverWrite(StoredResource entry,
                         Long txnId)
                  throws Exception

Description copied from interface: Recover

Recover a write operation. The recovered entry is the stored form of the entry passed into writeOp. If the original write was done under a transaction, and the transaction was prepared txnId will be non-null.

Specified by:

recoverWrite in interface Recover

Parameters:

entry - stored from of the written entry

txnId - transaction identifier or null

Throws:

Exception - is thrown if any error occurs recovering the write

See Also:

LogOps.writeOp(org.apache.river.outrigger.StorableResource, java.lang.Long)

recoverTake

public void recoverTake(Uuid cookie,
                        Long txnId)
                 throws Exception

Description copied from interface: Recover

Recover a take operation. If the original take was done under a transaction, and the transaction was prepared, txnId will be non-null.

Specified by:

recoverTake in interface Recover

Parameters:

cookie - identifier of the entry to take

txnId - transaction identifier or null

Throws:

Exception - is thrown if any error occurs recovering the take

See Also:

LogOps.takeOp(net.jini.id.Uuid, java.lang.Long)

recoverTransaction

public void recoverTransaction(Long txnId,
                               StoredObject transaction)
                        throws Exception

Description copied from interface: Recover

Recover a prepared transaction. The recovered transaction is the stored form of the transaction passed into prepareOp.

Specified by:

recoverTransaction in interface Recover

Parameters:

txnId - transaction identifier

transaction - stored from of the prepared transaction

Throws:

Exception - is thrown if any error occurs recovering the transaction

See Also:

LogOps.prepareOp(java.lang.Long, org.apache.river.outrigger.StorableObject)

recoverRegister

public void recoverRegister(StoredResource registration,
                            String type,
                            StoredObject[] storedTemplates)
                     throws Exception

Description copied from interface: Recover

Recover an event registration. The recovered registration is the stored form of the registration passed into registerOp. The recovered template is the stored form of the template.

Specified by:

recoverRegister in interface Recover

Parameters:

registration - stored from of the logged registration

type - of registration, same value that was passed into corresponding registerOp call

storedTemplates - stored from of the logged templates

Throws:

Exception - is thrown if any error occurs recovering the registration

See Also:

LogOps.registerOp(org.apache.river.outrigger.StorableResource, java.lang.String, org.apache.river.outrigger.StorableObject[])

recoverUuid

public void recoverUuid(Uuid uuid)

Description copied from interface: Recover

Recover the Uuid for the service as a whole. Will only be called if a Uuid has be stored during a previous incarnation.

Specified by:

recoverUuid in interface Recover

Parameters:

uuid - The Uuid being recovered.

See Also:

LogOps.uuidOp(net.jini.id.Uuid)

getProxyVerifier

public TrustVerifier getProxyVerifier()

Description copied from interface: ServerProxyTrust

Returns a TrustVerifier that can be used to verify that a proxy can be trusted as a proxy for the service; that is, the isTrustedObject method of the returned verifier can be called with a candidate proxy. The verifier should be able to verify all proxies for the service, including proxies for resources (such as leases and registrations).

Specified by:

getProxyVerifier in interface ServerProxyTrust

Returns:

a TrustVerifier that can be used to verify that a proxy can be trusted as a proxy for the service

prepare

public int prepare(TransactionManager mgr,
                   long id)
            throws UnknownTransactionException,
                   UnmarshalException

Description copied from interface: TransactionParticipant

Requests that the participant prepare itself to commit the transaction, and to vote on the outcome of the transaction. The participant responds with either PREPARED, indicating that it is prepared; ABORT, indicating that it will abort, or NOTCHANGED, indicating that it did not have any state changed by the transaction (i.e., it was read-only). If the response is PREPARED, the participant must wait until it receives a commit or abort call from the transaction manager; it may query the transaction manager if needed as to the state of the transaction. If the response is ABORT, the participant should roll its state back to undo any changes that occurred due to operations performed under the transaction; it can then discard any information about the transaction. If the response is NOTCHANGED, the participant can immediately discard any knowledge of the transaction.

Parameters:

mgr - the manager of the transaction

id - the transaction ID

Returns:

an int representing this participant's state

Throws:

UnknownTransactionException - if the transaction is unknown to the transaction manager, either because the transaction ID is incorrect or because the transaction is complete and its state has been discarded by the manager.

UnmarshalException

commit

public void commit(TransactionManager mgr,
                   long id)
            throws UnknownTransactionException,
                   UnmarshalException

Description copied from interface: TransactionParticipant

Requests that the participant make all of its PREPARED changes for the specified transaction visible outside of the transaction and unlock any resources locked by the transaction. All state associated with the transaction can then be discarded by the participant.

Parameters:

mgr - the manager of the transaction

id - the transaction ID

Throws:

UnknownTransactionException - if the transaction is unknown to the transaction manager, either because the transaction ID is incorrect or because the transaction is complete and its state has been discarded by the manager.

UnmarshalException

abort

public void abort(TransactionManager mgr,
                  long id)
           throws UnknownTransactionException,
                  UnmarshalException

Description copied from interface: TransactionParticipant

Requests that the participant roll back any changes for the specified transaction and unlock any resources locked by the transaction. All state associated with the transaction can then be discarded by the participant.

Parameters:

mgr - the manager of the transaction

id - the transaction ID

Throws:

UnknownTransactionException - if the transaction is unknown to the transaction manager, either because the transaction ID is incorrect or because the transaction is complete and its state has been discarded by the manager.

UnmarshalException

prepareAndCommit

public int prepareAndCommit(TransactionManager mgr,
                            long id)
                     throws UnknownTransactionException,
                            UnmarshalException

Description copied from interface: TransactionParticipant

A combination of prepare and commit, which can be used by the manager when there is just one participant left to prepare and all other participants (if any) have responded with NOTCHANGED. The participant's implementation of this method must be equivalent to:

        public int prepareAndCommit(TransactionManager mgr, long id)
            throws UnknownTransactionException, RemoteException
        {
            int result = prepare(mgr, id);
            if (result == PREPARED) {
                commit(mgr, id);
                result = COMMITTED;
            }
            return result;
        }
 

Parameters:

mgr - the manager of the transaction

id - the transaction ID

Returns:

an int representing its state

Throws:

UnknownTransactionException - if the transaction is unknown to the transaction manager, either because the transaction ID is incorrect or because the transaction is complete and its state has been discarded by the manager.

UnmarshalException

See Also:

TransactionParticipant.prepare(net.jini.core.transaction.server.TransactionManager, long), TransactionParticipant.commit(net.jini.core.transaction.server.TransactionManager, long)