org.apache.river.outrigger

Interface OutriggerServer

All Superinterfaces:

DestroyAdmin, JoinAdmin, Landlord, OutriggerAdmin, Remote, ServiceProxyAccessor, TransactionConstants, TransactionParticipant

All Known Implementing Classes:

OutriggerServerImpl, OutriggerServerWrapper, PersistentOutriggerImpl, TransientOutriggerImpl

interface OutriggerServer
extends TransactionParticipant, Landlord, OutriggerAdmin, ServiceProxyAccessor, Remote

This interface is the private wire protocol to the Outrigger implementations of JavaSpaces^TM technology.

Author:

Sun Microsystems, Inc.

See Also:

EntryRep

Nested Class Summary

Nested Classes

Modifier and Type	Interface 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 inherited from interface net.jini.core.transaction.server.TransactionConstants

ABORTED, ACTIVE, COMMITTED, NOTCHANGED, PREPARED, VOTING

Method Summary

Modifier and Type	Method and Description
MatchSetData	contents(EntryRep[] tmpls, Transaction tr, long leaseTime, long limit) Start a new contents query.
Object	getAdmin() Return the admin proxy for this space.
EntryRep[]	nextBatch(Uuid contentsQueryUuid, Uuid entryUuid) Return the next batch of entries associated with the specified contents query.
EventRegistration	notify(EntryRep tmpl, Transaction txn, RemoteEventListener listener, long lease, MarshalledObject handback) When entries are written that match this template notify the given listener.
Object	read(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(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.
EventRegistration	registerForAvailabilityEvent(EntryRep[] tmpls, Transaction txn, 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.
Object	take(EntryRep[] tmpls, Transaction tr, long timeout, int limit, OutriggerServer.QueryCookie cookie) 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(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(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(EntryRep[] entries, Transaction txn, long[] leaseTimes) Write a set of entires into the space.
long[]	write(EntryRep entry, Transaction txn, long lease) Write a new entry into the space.

Methods inherited from interface net.jini.core.transaction.server.TransactionParticipant

abort, commit, prepare, prepareAndCommit

Methods inherited from interface org.apache.river.landlord.Landlord

cancel, cancelAll, renew, renewAll

Methods inherited from interface org.apache.river.outrigger.OutriggerAdmin

close, contents, delete, nextReps, space

Methods inherited from interface org.apache.river.admin.DestroyAdmin

destroy

Methods inherited from interface net.jini.admin.JoinAdmin

addLookupAttributes, addLookupGroups, addLookupLocators, getLookupAttributes, getLookupGroups, getLookupLocators, modifyLookupAttributes, removeLookupGroups, removeLookupLocators, setLookupGroups, setLookupLocators

Methods inherited from interface org.apache.river.start.ServiceProxyAccessor

getServiceProxy

Method Detail

write

long[] write(EntryRep entry,
             Transaction txn,
             long lease)
      throws TransactionException,
             RemoteException

Write a new entry into the space.

Throws:

TransactionException - A transaction error occurred

RemoteException

read

Object read(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.

Throws:

RemoteException - if a network failure occurs.

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.

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

SecurityException - if the server decides the caller has insufficient privilege to carry out the operation.

IllegalArgumentException - if a negative timeout value is used

InternalSpaceException - if there is an internal problem with the server.

readIfExists

Object readIfExists(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.

Throws:

RemoteException - if a network failure occurs.

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.

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

SecurityException - if the server decides the caller has insufficient privilege to carry out the operation.

IllegalArgumentException - if a negative timeout value is used

InternalSpaceException - if there is an internal problem with the server.

take

Object take(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.

Throws:

RemoteException - if a network failure occurs.

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.

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

SecurityException - if the server decides the caller has insufficient privilege to carry out the operation.

IllegalArgumentException - if a negative timeout value is used

InternalSpaceException - if there is an internal problem with the server.

takeIfExists

Object takeIfExists(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.

Throws:

RemoteException - if a network failure occurs.

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.

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

SecurityException - if the server decides the caller has insufficient privilege to carry out the operation.

IllegalArgumentException - if a negative timeout value is used

InternalSpaceException - if there is an internal problem with the server.

notify

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

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

Throws:

TransactionException

RemoteException

write

long[] write(EntryRep[] entries,
             Transaction txn,
             long[] leaseTimes)
      throws TransactionException,
             RemoteException

Write a set of entires into the space.

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

take

Object take(EntryRep[] tmpls,
            Transaction tr,
            long timeout,
            int limit,
            OutriggerServer.QueryCookie cookie)
     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

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

Throws:

RemoteException - if a network failure occurs.

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.

SecurityException - if the server decides the caller has insufficient privilege to carry out the operation.

IllegalArgumentException - if a negative timeout value is used or if a non-positive limit value is used

InternalSpaceException - if there is an internal problem with the server.

registerForAvailabilityEvent

EventRegistration registerForAvailabilityEvent(EntryRep[] tmpls,
                                               Transaction txn,
                                               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

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

contents

MatchSetData contents(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

IllegaleArgumentException - if limit is non-positive or leaseTime is less than -1

NullPointerException - if tmpls is null

RemoteException

nextBatch

EntryRep[] nextBatch(Uuid contentsQueryUuid,
                     Uuid entryUuid)
              throws RemoteException

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

RemoteException

getAdmin

Object getAdmin()
         throws RemoteException

Return the admin proxy for this space.

Throws:

RemoteException