public interface JavaSpace05 extends JavaSpace
JavaSpace05
interface extends the JavaSpace
interface to provide methods that allow clients to
perform batch operations on the space (which are generally more
efficient than performing an equivalent set of singleton
operations) and to more easily develop applications where a
given Entry
needs to be read by multiple clients.
Implementations of the JavaSpace
interface are not
required to implement this interface.
Unless otherwise noted, the effects of any invocation of a
method defined by this interface must be visible to any
operation on the space that is started after the invocation
returns normally. Note, the effects of a method invocation that
throws a RemoteException
are not necessarily visible
when the exception is thrown.
All of the methods of this interface take one or more Collection
s as arguments. Each such Collection
must be treated as immutable by implementations and must not be
changed by the client during the course of any method
invocation to which they have been passed.
This interface is not a remote interface. Each implementation of
this interface exports a proxy object that implements this
interface local to the client. Each method of the interface
takes as one of its arguments a Collection
of
Entry
instances. The entries themselves must be
serialized in accordance with the Jini Entry
Specification and will not be altered by the
call. Typically, the Collection
holding the entries
will not be serialized at all. If one of these entries can't be
serialized, a MarshalException
will be thrown. Aside
from the handling of these Collection
of
Entry
parameters, all methods defined by this
interface otherwise obey normal Java(TM) Remote Method
Invocation remote interface semantics.
Modifier and Type | Method and Description |
---|---|
MatchSet |
contents(Collection tmpls,
Transaction txn,
long leaseDuration,
long maxEntries)
Creates a match set that can be used to
exhaustively read through all of the matching entries in
the space that are visible to the passed
Transaction and remain visible for the lifetime of the
match set. |
EventRegistration |
registerForAvailabilityEvent(Collection tmpls,
Transaction txn,
boolean visibilityOnly,
RemoteEventListener listener,
long leaseDuration,
MarshalledObject handback)
Register for events triggered when a matching
Entry
transitions from unavailable to available. |
Collection |
take(Collection tmpls,
Transaction txn,
long timeout,
long maxEntries)
This method provides an overload of the
JavaSpace.take method that attempts to
remove, optionally under a Transaction , and return
one or more entries from the space. |
List |
write(List entries,
Transaction txn,
List leaseDurations)
This method provides an overload of the
JavaSpace.write method that allows new
copies of multiple Entry instances to be stored in
the space using a single call. |
notify, read, readIfExists, snapshot, take, takeIfExists, write
List write(List entries, Transaction txn, List leaseDurations) throws TransactionException, RemoteException
JavaSpace.write
method that allows new
copies of multiple Entry
instances to be stored in
the space using a single call. The client may specify a
Transaction
for the operation to be performed
under. Each Entry
to be stored in the space
has a separate requested initial lease duration.
The effect on the space of an invocation of this method
successfully storing an Entry
is the same as if
the Entry
had been successfully stored by a
call to the singleton form of write
under
txn
with the given requested initial lease
duration. This method returns the proxies to the leases for
each newly stored Entry
by returning a List
of Lease
instances. The i th element
of the returned List
will be a proxy for the
lease on the Entry
created from the i
th element of entries
.
If an invocation of this method returns normally, then a new
copy of each element of entries
must have been
stored in the space. A new copy of each element will be
stored even if there are duplicates (either in terms of
object identity or of entry equivalence) in
entries
.
The order in which the entries stored by an invocation of this method will become visible in the space is unspecified, and different observers may see the entries become visible in different orders.
If a TransactionException
, SecurityException
, IllegalArgumentException
, or
NullPointerException
is thrown, no entries will
have been added to the space by this operation. If a RemoteException
is thrown, either new copies of all of the
elements of entries
will have been stored or
no entries will have been stored; that is, in the case of a
RemoteException
, the storing of new entries in
the space will either fail or succeed as a unit.
entries
- a List
of Entry
instances to
be written to the spacetxn
- the Transaction
this operation should be
performed under, may be null
leaseDurations
- a List
of
Long
s representing the
requested initial lease durationsList
of Lease
instances, one
for each element of entries
, may be
immutable. The space will not keep a reference to
the resultTransactionException
- if txn
is
non-null
and is not usable by the
spaceRemoteException
- if a communication error occursIllegalArgumentException
- if entries
and
leaseDurations
are not the same length
or are empty, if any element of entries
is not an instance of Entry
, if any
element of leaseDurations
is not an
instance of Long
, or if any element of
leaseDurations
is a negative value
other than Lease.ANY
NullPointerException
- if either entries
or leaseDurations
is null
or contains a null
valueCollection take(Collection tmpls, Transaction txn, long timeout, long maxEntries) throws UnusableEntriesException, TransactionException, RemoteException
JavaSpace.take
method that attempts to
remove, optionally under a Transaction
, and return
one or more entries from the space. Each Entry
taken will match one or more elements of the passed Collection
of templates, and all of the taken entries will
be visible to the passed Transaction
. If there
are initially no matches in the space that are visible to
the passed Transaction
, an invocation of this
method will block for up to a specified timeout for one or
more matches to appear.
The effect on the space of an invocation of this method
successfully taking an Entry
will be the same
as if the Entry
had been taken using the
singleton version of this method and passing
txn
as the Transaction
.
The tmpls
parameter must be a
Collection
of Entry
instances to
be used as templates. All of the entries taken must match
one or more of these templates. The tmpls
parameter may contain null
values and may
contain duplicates. An Entry
is said to be
available to an invocation of this method if the
Entry
could have been returned by an
invocation of the singleton take
method using
txn
.
If the method succeeds, a non-null
Collection
will be returned. The
Collection
will contain a copy of each
Entry
that was taken. If no entries were taken,
the Collection
will be empty. Each
Entry
taken will be represented by a distinct
Entry
instance in the returned
Collection
, even if some of the entries are
equivalent to others taken by the operation. There will be
no null
elements in the returned
Collection
.
If one or more of the entries taken cannot be unmarshalled
in the client, an UnusableEntriesException
is
thrown. The exception's UnusableEntriesException.getEntries
method will return a
Collection
with a copy of each
Entry
that could be unmarshalled. The UnusableEntriesException.getUnusableEntryExceptions
method
will return a Collection
with an UnusableEntryException
for each Entry
that
could not be unmarshalled. Every Entry
taken
by the invocation will either be represented in the
Collection
returned by getEntries
or in the Collection
returned by
getUnusableEntryExceptions
.
If there is at least one matching Entry
available in the space, an invocation of this method must
take at least one Entry
. If more than one
matching Entry
is available, the invocation may
take additional entries. It must not take more than
maxEntries
, but an implementation may chose to
take fewer entries from the space than the maximum available or
the maximum allowed by maxEntries
. If for
whatever reason, an invocation of this method takes fewer
entries than the maximum number of available matching
entries, how an implementation selects which entries should be
taken by the invocation and which are left in the space is
unspecified. How consumption of entries is arbitrated
between conflicting queries is also unspecified.
If there are initially no matching entries in the space, an
invocation of this method should block for up to
timeout
milliseconds for a match to appear. If
one or more matches become available before
timeout
expires, one or more of the newly
available entries should be taken and the method should
return without further blocking. If for some reason the
invocation can't block for the full timeout and no entries
have been taken, the invocation must fail with a RemoteException
or TransactionException
as
appropriate.
If an invocation of this method removes (or locks) more than
one Entry
, the order in which the removal (or
locking) occurs is undefined, and different observers may see
the removal or locking of the entries in different
orders.
If a TransactionException
, SecurityException
, IllegalArgumentException
, or
NullPointerException
is thrown, no entries will
have been taken. If a RemoteException
is
thrown, up to maxEntries
may have been taken
by this operation.
tmpls
- a Collection
of Entry
instances, each representing a template. All
of the entries taken by an invocation of this
method will match one or more elements of
tmpls
txn
- the Transaction
this operation should be
performed under, may be null
timeout
- if there are initially no available
matches in the space, the maximum number of
milliseconds to block waiting for a match to
become availablemaxEntries
- the maximum number of entries that may be
taken by this methodCollection
that contains a copy of each
Entry
taken from the space by this
method. The space will not keep a reference to
this Collection
. May be immutableUnusableEntriesException
- if one or more of the
entries taken can't be unmarshalled in the clientTransactionException
- if txn
is
non-null
and is not usable by the
space.RemoteException
- if a communication error occursIllegalArgumentException
- if any non-null
element of tmpls
is not an instance of
Entry
, if tmpls
is empty,
if timeout
is negative, or if
maxEntries
is non-positiveNullPointerException
- if tmpls
is nullMatchSet contents(Collection tmpls, Transaction txn, long leaseDuration, long maxEntries) throws TransactionException, RemoteException
Transaction
and remain visible for the lifetime of the
match set. May also yield additional entries that match but
are only visible for part of the lifetime of the match
set.
The tmpls
parameter must be a Collection
of Entry
instances to be used as
templates. All of the entries placed in the match set will
match one or more of these templates. tmpls
may
contain null
values and may contain
duplicates. An Entry
is said to be
visible to an invocation of this method if the
Entry
could have been returned by a singleton
JavaSpace.read
using the same
transaction.
The resulting match set must initially contain all of the
visible matching entries in the space. During the lifetime
of the match set an Entry
may be, but is not
required to be, added to the match set if it becomes
visible. If the match set becomes empty, no more entries can
be added and the match set enters the exhausted state.
Normally there are three conditions under which an
Entry
might be removed from the match set:
Entry
yielded by an invocation of the
MatchSet.next
method on the match
set (either as the return value of a successful call or
embedded in an UnusableEntryException
) must be
removed from the match set.
Entry
that remains in the match set
after maxEntries
entries are yielded by
next
invocations must be removed from the
match set. In such a case, the criteria used to select which
entries are yielded by next
calls and which
get removed from the set at the end is unspecified.
Entry
that during the lifetime of the
match set becomes invisible may at the discretion of the
implementation be removed from the match set.
An implementation may decide to remove an Entry
from the set for other reasons. If it does so, however, it
must invalidate the set.
If txn
is non-null
and still
active, any Entry
removed from the match set by
a next
call must be locked as if it had been
returned by a read operation using txn
. An
implementation may establish the read lock on the
Entry
any time between when the
Entry
is added to the match set and when the
Entry
is removed from the match set by an
invocation of next
. These read locks are not
released when the match set reaches either the exhausted
state or the invalidated state. If from the space's
perspective the txn
leaves the active state,
the space must remove from the match set any entries in the
match set that have not yet been read locked. This may
require the match set to be invalidated.
If the match set is leased and leaseDuration
is positive, the initial duration of the lease must be less
than or equal to leaseDuration
. If
leaseDuration
is Lease.ANY
,
the initial duration of the lease can be any positive value
desired by the implementation.
If there are remote
method constraints associated with an invocation of this
method, any remote communications performed by or on behalf
of the match set's next
method will be
performed in compliance with these constraints, not with the
constraints (if any) associated with next
.
tmpls
- a Collection
of Entry
instances, each representing a template. All
the entries added to the resulting match set will
match one or more elements of tmpls
txn
- the Transaction
this operation should be
performed under, may be null
leaseDuration
- the requested initial lease time on
the resulting match setmaxEntries
- the maximum number of entries to remove
from the set via MatchSet.next
callsTransactionException
- if txn
is
non-null
and is not usable by the
spaceRemoteException
- if a communication error occursIllegalArgumentException
- if any non-null
element of tmpls
is not an instance of
Entry
, if tmpls
is empty,
if leaseDuration
is neither positive
nor Lease.ANY
, or if
maxEntries
is non-positiveNullPointerException
- if tmpls
is
null
EventRegistration registerForAvailabilityEvent(Collection tmpls, Transaction txn, boolean visibilityOnly, RemoteEventListener listener, long leaseDuration, MarshalledObject handback) throws TransactionException, RemoteException
Entry
transitions from unavailable to available. The resulting
events will be instances of the AvailabilityEvent
class and the AvailabilityEvent.getEntry
method will return a copy of
the Entry
whose transition triggered the
event.
An Entry
makes a transition from
unavailable to available when it goes from being in
a state where it could not be returned by a JavaSpace.take
using txn
to a
state where it could be returned. An Entry
makes a transition from invisible to visible when
it goes from being in a state where it could not be returned
by a JavaSpace.read
using
txn
to a state where it could be
returned. Note, any transition from invisible to visible is
also a transition from unavailable to available, but an
already visible entry can be unavailable and then make a
transition from unavailable to available. Because the entry
was already visible, this transition would not be a
transition from invisible to visible.
The tmpls
parameter must be a Collection
of Entry
instances to be used as
templates. Events will be generated when an
Entry
that matches one or more of these
templates makes an appropriate transition. A single
transition will generate only one event per registration, in
particular the transition of an Entry
that
matches multiple elements of tmpls
must still
generate exactly one event for this registration. If a given
Entry
undergoes multiple applicable transitions
while the registration is active, each must generate a
separate event.
Events are not generated directly by the transition of matching entries, but instead by an abstract observer set up in the space for each registration. The observer may see the transitions out of order and as a result the order of the events generated for this registration (as determined by the sequence numbers assigned to the events) may be different from the order of the transitions themselves. Additionally, each registration will have its own abstract observer and different observers may see the same sequence of transitions in different orders. As a result, given a set of transitions that trigger events for two different registrations, the order of the events generated for one registration may differ from the order of the events generated for the other.
A non-null
EventRegistration
object
will be returned. Each registration will be assigned an
event ID. The event ID will be unique at least with respect
to all other active event registrations for
AvailabilityEvent
s on this space with a
non-equivalent set of templates, a different transaction,
and/or a different value for the
visibilityOnly
flag. The event ID can be
obtained by calling the EventRegistration.getID
method on the returned
EventRegistration
. The returned
EventRegistration
object's EventRegistration.getSource
method will return a reference to the space.
Registrations are leased. leaseDurations
represents the client's desired initial lease duration. If
leaseDuration
is positive, the initial lease
duration will be a positive value less than or equal to
leaseDuration
. If leaseDuration
is
Lease.ANY
, the space is free to pick any
positive initial lease duration it desires. A proxy for the
lease associated with the registration can be obtained by
calling the returned EventRegistration
's EventRegistration.getLease
method.
A registration made with a non-null
value for
txn
is implicitly dropped when the space
observes txn
has left the active state.
tmpls
- a Collection
of Entry
instances, each representing a
template. Events for this registration will be
generated by the transitions of entries
matching one or more elements of
tmpls
txn
- the Transaction
this operation should be
performed under, may be null
visibilityOnly
- if true
, events will
be generated for this registration only when a
matching Entry
transitions from
invisible to visible, otherwise events will be
generated when a matching Entry
makes any transition from unavailable to
availablelistener
- the object to which events generated for
this registration should be deliveredleaseDuration
- the requested initial lease time on
the resulting event registrationhandback
- the MarshalledObject
to be
returned by the RemoteEvent.getRegistrationObject
method of
the events generated for this registrationEventRegistration
object with
information on this registrationTransactionException
- if txn
is
non-null
and is not usable by the
spaceRemoteException
- if a communication error occursIllegalArgumentException
- if any non-null
element of tmpls
is not an instance of
Entry
, if tmpls
is empty,
or if leaseDuration
is neither
positive nor Lease.ANY
NullPointerException
- if tmpls
or
listener
is null