com.sun.jini.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 JavaSpacesTM technology.

Author:
Sun Microsystems, Inc.
See Also:
EntryRep

Nested Class Summary
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 com.sun.jini.landlord.Landlord
Landlord.RenewResults
 
Field Summary
 
Fields inherited from interface net.jini.core.transaction.server.TransactionConstants
ABORTED, ACTIVE, COMMITTED, NOTCHANGED, PREPARED, VOTING
 
Method Summary
 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 com.sun.jini.landlord.Landlord
cancel, cancelAll, renew, renewAll
 
Methods inherited from interface com.sun.jini.outrigger.OutriggerAdmin
close, contents, delete, nextReps, space
 
Methods inherited from interface com.sun.jini.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 com.sun.jini.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


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