AdminIterator that will iterate over all the entries in the space that match the given template and are visible under the given transaction. The interactions between other operations on the space and the returned iterator are undefined
@param tmpl The iterator should return only entries that matchtmpl
@param txn The iterator should return only entries that matchthis transaction
@throws RemoteException if communications with theserver is necessary and it can not be completed.
@throws TransactionException if there is a problem withtxn.
@throws SecurityException If the space is performing access control and it can not be confirmed that the subject making this call has permission to create an AdminIterator with the specified template and transaction.
The tmpls parameter must be a {@link Collection} of {@link Entry} instances to be used astemplates. 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 {@link JavaSpace#read JavaSpace.read} using the sametransaction.
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 {@linkplain MatchSet 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 {@link MatchSet#next MatchSet.next} method on the matchset (either as the return value of a successful call or embedded in an {@link 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 {@linkplain MatchSet 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 {@link Lease#ANY Lease.ANY}, the initial duration of the lease can be any positive value desired by the implementation.
If there are {@linkplain net.jini.core.constraint remotemethod constraints} associated with an invocation of thismethod, 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.
@param tmpls a {@link Collection} of {@link Entry}instances, each representing a template. All the entries added to the resulting match set will match one or more elements of tmpls
@param txn the {@link Transaction} this operation should beperformed under, may be null
@param leaseDuration the requested initial lease time onthe resulting match set
@param maxEntries the maximum number of entries to removefrom the set via {@link MatchSet#next MatchSet.next} calls
@return A proxy to the newly created {@linkplain MatchSet match set}
@throws TransactionException if txn isnon-null and is not usable by the space
@throws RemoteException if a communication error occurs
@throws IllegalArgumentException if any non-nullelement of tmpls is not an instance of Entry, if tmpls is empty, if leaseDuration is neither positive nor {@link Lease#ANY Lease.ANY}, or if maxEntries is non-positive
@throws NullPointerException if tmpls isnull
| |
| |
| |
| |