content/release-doc/current/internals/net/jini/space/MatchSet.html - river-site - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <!-- NewPage -->
 <html lang="en">
 <head>
 <!-- Generated by javadoc (1.8.0) on Sun Aug 28 20:42:13 EST 2016 -->
 <title>MatchSet (Apache River v3.0.0 API Documentation (internals))</title>
 <meta name="date" content="2016-08-28">
 <link rel="stylesheet" type="text/css" href="../../../stylesheet.css" title="Style">
 <script type="text/javascript" src="../../../script.js"></script>
 </head>
 <body>
 <script type="text/javascript"><!--
     try {
         if (location.href.indexOf('is-external=true') == -1) {
             parent.document.title="MatchSet (Apache River v3.0.0 API Documentation (internals))";
         }
     }
     catch(err) {
     }
 //-->
 var methods = {"i0":6,"i1":6,"i2":6};
 var tabs = {65535:["t0","All Methods"],2:["t2","Instance Methods"],4:["t3","Abstract Methods"]};
 var altColor = "altColor";
 var rowColor = "rowColor";
 var tableTab = "tableTab";
 var activeTableTab = "activeTableTab";
 </script>
 <noscript>
 <div>JavaScript is disabled on your browser.</div>
 </noscript>
 <!-- ========= START OF TOP NAVBAR ======= -->
 <div class="topNav"><a name="navbar.top">
 <!--   -->
 </a>
 <div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
 <a name="navbar.top.firstrow">
 <!--   -->
 </a>
 <ul class="navList" title="Navigation">
 <li><a href="../../../overview-summary.html">Overview</a></li>
 <li><a href="package-summary.html">Package</a></li>
 <li class="navBarCell1Rev">Class</li>
 <li><a href="class-use/MatchSet.html">Use</a></li>
 <li><a href="package-tree.html">Tree</a></li>
 <li><a href="../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../index-all.html">Index</a></li>
 <li><a href="../../../help-doc.html">Help</a></li>
 </ul>
 </div>
 <div class="subNav">
 <ul class="navList">
 <li><a href="../../../net/jini/space/JavaSpace05.html" title="interface in net.jini.space"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
 <li>Next&nbsp;Class</li>
 </ul>
 <ul class="navList">
 <li><a href="../../../index.html?net/jini/space/MatchSet.html" target="_top">Frames</a></li>
 <li><a href="MatchSet.html" target="_top">No&nbsp;Frames</a></li>
 </ul>
 <ul class="navList" id="allclasses_navbar_top">
 <li><a href="../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
 </ul>
 <div>
 <script type="text/javascript"><!--
   allClassesLink = document.getElementById("allclasses_navbar_top");
   if(window==top) {
     allClassesLink.style.display = "block";
   }
   else {
     allClassesLink.style.display = "none";
   }
   //-->
 </script>
 </div>
 <div>
 <ul class="subNavList">
 <li>Summary:&nbsp;</li>
 <li>Nested&nbsp;|&nbsp;</li>
 <li>Field&nbsp;|&nbsp;</li>
 <li>Constr&nbsp;|&nbsp;</li>
 <li><a href="#method.summary">Method</a></li>
 </ul>
 <ul class="subNavList">
 <li>Detail:&nbsp;</li>
 <li>Field&nbsp;|&nbsp;</li>
 <li>Constr&nbsp;|&nbsp;</li>
 <li><a href="#method.detail">Method</a></li>
 </ul>
 </div>
 <a name="skip.navbar.top">
 <!--   -->
 </a></div>
 <!-- ========= END OF TOP NAVBAR ========= -->
 <!-- ======== START OF CLASS DATA ======== -->
 <div class="header">
 <div class="subTitle">net.jini.space</div>
 <h2 title="Interface MatchSet" class="title">Interface MatchSet</h2>
 </div>
 <div class="contentContainer">
 <div class="description">
 <ul class="blockList">
 <li class="blockList">
 <dl>
 <dt>All Known Implementing Classes:</dt>
 <dd><a href="../../../org/apache/river/outrigger/MatchSetProxy.html" title="class in org.apache.river.outrigger">MatchSetProxy</a></dd>
 </dl>
 <hr>
 <br>
 <pre>public interface <span class="typeNameLabel">MatchSet</span></pre>
 <div class="block">A collection of <a href="../../../net/jini/core/entry/Entry.html" title="interface in net.jini.core.entry"><code>Entry</code></a> instances to be incrementally
  returned from a JavaSpaces service. Some operations on a
  space must return more entries than can be conveniently
  returned by a single call, generally because returning all the
  entries in one result would consume too many resources in the
  client or introduce too much latency before the first entry
  could be processed. In these cases, match sets are returned to
  incrementally return the necessary entries. A
  <code>MatchSet</code> instance is a proxy object that can be
  used to access a match set created by a space.<p>

  Typically match sets are created by some factory method on the
  space (for example, <a href="../../../net/jini/space/JavaSpace05.html#contents-java.util.Collection-net.jini.core.transaction.Transaction-long-long-"><code>JavaSpace05.contents</code></a>) which returns a <code>MatchSet</code>
  instance that will serve as a proxy to the match set. The match
  set will initially contain some population of entries specified
  by the operation that created it. These entries can be
  retrieved by calling <a href="../../../net/jini/space/MatchSet.html#next--"><code>next</code></a>. A successful call to
  <code>next</code> will remove the returned <code>Entry</code>
  from the match set.  Match sets can end up in one of two
  terminal states, <em>exhausted</em> or <em>invalidated</em>.
  Under what conditions a match set enters one of these states is
  specified by the operation that created it. An exhausted match
  set is empty and will have no more entries added. Calling
  <code>next</code> on an exhausted match set must always return
  <code>null</code>. Calling <code>next</code> on an invalidated
  match set may return a non-<code>null</code> value, or it may
  throw one of the allowed exceptions.  In particular it may
  throw <a href="http://docs.oracle.com/javase/6/docs/api/java/rmi/NoSuchObjectException.html?is-external=true" title="class or interface in java.rmi"><code>NoSuchObjectException</code></a> to indicate that the match
  set has been invalidated. Once <code>next</code> throws a
  <code>NoSuchObjectException</code>, all future
  <code>next</code> calls on that instance must also throw
  <code>NoSuchObjectException</code>. Calling <code>next</code>
  on an invalidated match set must never return
  <code>null</code>. Implementations must not add entries to an
  invalidated match set. <p>

  Between the time a match set is created and the time it reaches a
  terminal state, entries may be added by the space. However, an
  <code>Entry</code> that is removed by a <code>next</code> call
  must not be added back to a match set (though if there is a
  distinct but equivalent entry in the space it may be
  added). The space may also remove entries independent of
  <code>next</code> calls. The conditions under which entries
  will be removed independent of <code>next</code> calls or added
  after the initial creation of the match set are specified by
  the operation that created the match set. <p>

  If there is a possibility that a match set may become
  invalidated, it must be leased and an appropriate proxy must be
  returned by the <a href="../../../net/jini/space/MatchSet.html#getLease--"><code>getLease</code></a> method. If there is
  no possibility that the match set will become invalidated,
  implementations should not lease the match set. If a match set
  is not leased, then <code>getLease</code> must return
  <code>null</code>. <p>

  An active lease on a match set serves as a hint to the space
  that the client is still interested in the match set, and as a
  hint to the client that the match set is still functioning.
  However, implementations are allowed to invalidate match sets
  associated with active leases and to unilaterally cancel leases
  associated with functioning match sets. If a match set is
  leased and the lease is active, implementations should, to the
  best of their ability, maintain the match set and not invalidate
  it. There are cases, however, where this may not be possible in
  particular, it is not expected that implementations will
  maintain match sets across crashes. If the lease expires or is
  canceled, an implementation should invalidate the match
  set. An implementation must unilaterally cancel a match set's
  lease if the match set is invalidated. An implementation may
  unilaterally cancel the lease at other times without necessarily
  invalidating the match set. Clients should <em>not</em> assume
  that the resources associated with a leased match set will be
  freed if the match set reaches the exhausted state, and should
  instead cancel the lease.

  This interface is not a remote interface; though in general a
  <code>MatchSet</code> is a proxy for some remote match set,
  only the <code>next</code> method is considered to be a remote
  method, and as outlined in its <a href="../../../net/jini/space/MatchSet.html#next--">description</a>
  it deviates in a number of ways from normal Java(TM) Remote
  Method Invocation remote method semantics.</div>
 <dl>
 <dt><span class="simpleTagLabel">Since:</span></dt>
 <dd>2.1</dd>
 </dl>
 </li>
 </ul>
 </div>
 <div class="summary">
 <ul class="blockList">
 <li class="blockList">
 <!-- ========== METHOD SUMMARY =========== -->
 <ul class="blockList">
 <li class="blockList"><a name="method.summary">
 <!--   -->
 </a>
 <h3>Method Summary</h3>
 <table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Method Summary table, listing methods, and an explanation">
 <caption><span id="t0" class="activeTableTab"><span>All Methods</span><span class="tabEnd">&nbsp;</span></span><span id="t2" class="tableTab"><span><a href="javascript:show(2);">Instance Methods</a></span><span class="tabEnd">&nbsp;</span></span><span id="t3" class="tableTab"><span><a href="javascript:show(4);">Abstract Methods</a></span><span class="tabEnd">&nbsp;</span></span></caption>
 <tr>
 <th class="colFirst" scope="col">Modifier and Type</th>
 <th class="colLast" scope="col">Method and Description</th>
 </tr>
 <tr id="i0" class="altColor">
 <td class="colFirst"><code><a href="../../../net/jini/core/lease/Lease.html" title="interface in net.jini.core.lease">Lease</a></code></td>
 <td class="colLast"><code><span class="memberNameLink"><a href="../../../net/jini/space/MatchSet.html#getLease--">getLease</a></span>()</code>
 <div class="block">Returns a proxy to the <a href="../../../net/jini/core/lease/Lease.html" title="interface in net.jini.core.lease"><code>Lease</code></a> associated with this
  match set, or <code>null</code> if this match set is not
  leased.</div>
 </td>
 </tr>
 <tr id="i1" class="rowColor">
 <td class="colFirst"><code><a href="../../../net/jini/core/entry/Entry.html" title="interface in net.jini.core.entry">Entry</a></code></td>
 <td class="colLast"><code><span class="memberNameLink"><a href="../../../net/jini/space/MatchSet.html#getSnapshot--">getSnapshot</a></span>()</code>
 <div class="block">Returns a <em>snapshot</em> of the <a href="../../../net/jini/core/entry/Entry.html" title="interface in net.jini.core.entry"><code>Entry</code></a> removed by
  the last call to <a href="../../../net/jini/space/MatchSet.html#next--"><code>next</code></a>.</div>
 </td>
 </tr>
 <tr id="i2" class="altColor">
 <td class="colFirst"><code><a href="../../../net/jini/core/entry/Entry.html" title="interface in net.jini.core.entry">Entry</a></code></td>
 <td class="colLast"><code><span class="memberNameLink"><a href="../../../net/jini/space/MatchSet.html#next--">next</a></span>()</code>
 <div class="block">Removes one <code>Entry</code> from the match set and
  returns a copy to the caller.</div>
 </td>
 </tr>
 </table>
 </li>
 </ul>
 </li>
 </ul>
 </div>
 <div class="details">
 <ul class="blockList">
 <li class="blockList">
 <!-- ============ METHOD DETAIL ========== -->
 <ul class="blockList">
 <li class="blockList"><a name="method.detail">
 <!--   -->
 </a>
 <h3>Method Detail</h3>
 <a name="next--">
 <!--   -->
 </a>
 <ul class="blockList">
 <li class="blockList">
 <h4>next</h4>
 <pre><a href="../../../net/jini/core/entry/Entry.html" title="interface in net.jini.core.entry">Entry</a>&nbsp;next()
     throws <a href="http://docs.oracle.com/javase/6/docs/api/java/rmi/RemoteException.html?is-external=true" title="class or interface in java.rmi">RemoteException</a>,
            <a href="../../../net/jini/core/entry/UnusableEntryException.html" title="class in net.jini.core.entry">UnusableEntryException</a></pre>
 <div class="block">Removes one <code>Entry</code> from the match set and
  returns a copy to the caller. Returns <code>null</code> if
  the match set is empty. The returned <code>Entry</code>
  must be unmarshalled in accordance with the <a
  href=http://www.jini.org/standards/index.html>Jini Entry
  Specification</a>.<p>

  A given invocation of this method may perform remote
  communications, but generally the <code>next</code> method
  is not expected to have <a href="../../../net/jini/core/constraint/package-summary.html">remote method constraints</a> that
  can vary from invocation to invocation. Instead the set of
  constraints associated with the <code>next</code> method
  will be fixed at the time the match set was created, even
  if this object implements an interface like <a href="../../../net/jini/core/constraint/RemoteMethodControl.html" title="interface in net.jini.core.constraint"><code>RemoteMethodControl</code></a> that would otherwise allow the set of
  constraints associated with the <code>next</code> method to
  be altered.<p></div>
 <dl>
 <dt><span class="returnLabel">Returns:</span></dt>
 <dd>an <code>Entry</code> from the match set, or
          <code>null</code> if the match set is empty</dd>
 <dt><span class="throwsLabel">Throws:</span></dt>
 <dd><code><a href="../../../net/jini/core/entry/UnusableEntryException.html" title="class in net.jini.core.entry">UnusableEntryException</a></code> - if the entry removed from
          the match set could not be unmarshalled</dd>
 <dd><code><a href="http://docs.oracle.com/javase/6/docs/api/java/rmi/RemoteException.html?is-external=true" title="class or interface in java.rmi">RemoteException</a></code> - if a communication error occurs. If a
          <code>RemoteException</code> is thrown, no
          <code>Entry</code> was removed from the match set
          because of this call</dd>
 </dl>
 </li>
 </ul>
 <a name="getLease--">
 <!--   -->
 </a>
 <ul class="blockList">
 <li class="blockList">
 <h4>getLease</h4>
 <pre><a href="../../../net/jini/core/lease/Lease.html" title="interface in net.jini.core.lease">Lease</a>&nbsp;getLease()</pre>
 <div class="block">Returns a proxy to the <a href="../../../net/jini/core/lease/Lease.html" title="interface in net.jini.core.lease"><code>Lease</code></a> associated with this
  match set, or <code>null</code> if this match set is not
  leased.</div>
 <dl>
 <dt><span class="returnLabel">Returns:</span></dt>
 <dd>a proxy for the match set's lease, or
  <code>null</code> if there is no lease associated with this
  match set</dd>
 </dl>
 </li>
 </ul>
 <a name="getSnapshot--">
 <!--   -->
 </a>
 <ul class="blockListLast">
 <li class="blockList">
 <h4>getSnapshot</h4>
 <pre><a href="../../../net/jini/core/entry/Entry.html" title="interface in net.jini.core.entry">Entry</a>&nbsp;getSnapshot()</pre>
 <div class="block">Returns a <em>snapshot</em> of the <a href="../../../net/jini/core/entry/Entry.html" title="interface in net.jini.core.entry"><code>Entry</code></a> removed by
  the last call to <a href="../../../net/jini/space/MatchSet.html#next--"><code>next</code></a>. Snapshots are defined
  in section JS.2.6 of the <a
  href=http://www.jini.org/standards/index.html>
  JavaSpaces Service Specification</a> and are an
  alternative representation of a given <code>Entry</code>
  produced by a particular space for use with that same
  space. Passing a snapshot to a space is generally more
  efficient than passing the original representation.<p>

  Any snapshot returned by this method will meet the same
  contract as the object returned by passing the result of
  the last <code>next</code> invocation to <a href="../../../net/jini/space/JavaSpace.html#snapshot-net.jini.core.entry.Entry-"><code>JavaSpace.snapshot</code></a>.<p>

  Generally there is a cost associated with calling the
  <code>JavaSpace.snapshot</code> method. Thus creating a
  snapshot using that method is usually only worthwhile if
  the resulting snapshot is used more than once. The cost of
  invoking this method should be low and should be worthwhile
  even if the resulting snapshot is used only once. <p></div>
 <dl>
 <dt><span class="returnLabel">Returns:</span></dt>
 <dd>a <em>snapshot</em> of the <a href="../../../net/jini/core/entry/Entry.html" title="interface in net.jini.core.entry"><code>Entry</code></a> removed
          from the match set by the last call to <a href="../../../net/jini/space/MatchSet.html#next--"><code>next</code></a></dd>
 <dt><span class="throwsLabel">Throws:</span></dt>
 <dd><code><a href="http://docs.oracle.com/javase/6/docs/api/java/lang/IllegalStateException.html?is-external=true" title="class or interface in java.lang">IllegalStateException</a></code> - if the last call to
          <code>next</code> did not remove an
          <code>Entry</code> from the match set, or no call
          to <code>next</code> has been made</dd>
 </dl>
 </li>
 </ul>
 </li>
 </ul>
 </li>
 </ul>
 </div>
 </div>
 <!-- ========= END OF CLASS DATA ========= -->
 <!-- ======= START OF BOTTOM NAVBAR ====== -->
 <div class="bottomNav"><a name="navbar.bottom">
 <!--   -->
 </a>
 <div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
 <a name="navbar.bottom.firstrow">
 <!--   -->
 </a>
 <ul class="navList" title="Navigation">
 <li><a href="../../../overview-summary.html">Overview</a></li>
 <li><a href="package-summary.html">Package</a></li>
 <li class="navBarCell1Rev">Class</li>
 <li><a href="class-use/MatchSet.html">Use</a></li>
 <li><a href="package-tree.html">Tree</a></li>
 <li><a href="../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../index-all.html">Index</a></li>
 <li><a href="../../../help-doc.html">Help</a></li>
 </ul>
 </div>
 <div class="subNav">
 <ul class="navList">
 <li><a href="../../../net/jini/space/JavaSpace05.html" title="interface in net.jini.space"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
 <li>Next&nbsp;Class</li>
 </ul>
 <ul class="navList">
 <li><a href="../../../index.html?net/jini/space/MatchSet.html" target="_top">Frames</a></li>
 <li><a href="MatchSet.html" target="_top">No&nbsp;Frames</a></li>
 </ul>
 <ul class="navList" id="allclasses_navbar_bottom">
 <li><a href="../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
 </ul>
 <div>
 <script type="text/javascript"><!--
   allClassesLink = document.getElementById("allclasses_navbar_bottom");
   if(window==top) {
     allClassesLink.style.display = "block";
   }
   else {
     allClassesLink.style.display = "none";
   }
   //-->
 </script>
 </div>
 <div>
 <ul class="subNavList">
 <li>Summary:&nbsp;</li>
 <li>Nested&nbsp;|&nbsp;</li>
 <li>Field&nbsp;|&nbsp;</li>
 <li>Constr&nbsp;|&nbsp;</li>
 <li><a href="#method.summary">Method</a></li>
 </ul>
 <ul class="subNavList">
 <li>Detail:&nbsp;</li>
 <li>Field&nbsp;|&nbsp;</li>
 <li>Constr&nbsp;|&nbsp;</li>
 <li><a href="#method.detail">Method</a></li>
 </ul>
 </div>
 <a name="skip.navbar.bottom">
 <!--   -->
 </a></div>
 <!-- ======== END OF BOTTOM NAVBAR ======= -->
 <p class="legalCopy"><small>Copyright 2007-2013, multiple authors.<br>Licensed under the <a href=http://www.apache.org/licenses/LICENSE-2.0 target=child >Apache License, Version 2.0</a>, see the <a href=../../../doc-files/NOTICE target=child >NOTICE</a> file for attributions.</small></p>
 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	<!-- NewPage -->
	<html lang="en">
	<head>
	<!-- Generated by javadoc (1.8.0) on Sun Aug 28 20:42:13 EST 2016 -->
	<title>MatchSet (Apache River v3.0.0 API Documentation (internals))</title>
	<meta name="date" content="2016-08-28">
	<link rel="stylesheet" type="text/css" href="../../../stylesheet.css" title="Style">
	<script type="text/javascript" src="../../../script.js"></script>
	</head>
	<body>
	<script type="text/javascript"><!--
	try {
	if (location.href.indexOf('is-external=true') == -1) {
	parent.document.title="MatchSet (Apache River v3.0.0 API Documentation (internals))";
	}
	}
	catch(err) {
	}
	//-->
	var methods = {"i0":6,"i1":6,"i2":6};
	var tabs = {65535:["t0","All Methods"],2:["t2","Instance Methods"],4:["t3","Abstract Methods"]};
	var altColor = "altColor";
	var rowColor = "rowColor";
	var tableTab = "tableTab";
	var activeTableTab = "activeTableTab";
	</script>
	<noscript>
	<div>JavaScript is disabled on your browser.</div>
	</noscript>
	<!-- ========= START OF TOP NAVBAR ======= -->
	<div class="topNav"><a name="navbar.top">
	<!-- -->
	</a>
	<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
	<a name="navbar.top.firstrow">
	<!-- -->
	</a>
	<ul class="navList" title="Navigation">
	<li><a href="../../../overview-summary.html">Overview</a></li>
	<li><a href="package-summary.html">Package</a></li>
	<li class="navBarCell1Rev">Class</li>
	<li><a href="class-use/MatchSet.html">Use</a></li>
	<li><a href="package-tree.html">Tree</a></li>
	<li><a href="../../../deprecated-list.html">Deprecated</a></li>
	<li><a href="../../../index-all.html">Index</a></li>
	<li><a href="../../../help-doc.html">Help</a></li>
	</ul>
	</div>
	<div class="subNav">
	<ul class="navList">
	<li><a href="../../../net/jini/space/JavaSpace05.html" title="interface in net.jini.space"><span class="typeNameLink">Prev Class</span></a></li>
	<li>Next Class</li>
	</ul>
	<ul class="navList">
	<li><a href="../../../index.html?net/jini/space/MatchSet.html" target="_top">Frames</a></li>
	<li><a href="MatchSet.html" target="_top">No Frames</a></li>
	</ul>
	<ul class="navList" id="allclasses_navbar_top">
	<li><a href="../../../allclasses-noframe.html">All Classes</a></li>
	</ul>
	<div>
	<script type="text/javascript"><!--
	allClassesLink = document.getElementById("allclasses_navbar_top");
	if(window==top) {
	allClassesLink.style.display = "block";
	}
	else {
	allClassesLink.style.display = "none";
	}
	//-->
	</script>
	</div>
	<div>
	<ul class="subNavList">
	<li>Summary: </li>
	<li>Nested \| </li>
	<li>Field \| </li>
	<li>Constr \| </li>
	<li><a href="#method.summary">Method</a></li>
	</ul>
	<ul class="subNavList">
	<li>Detail: </li>
	<li>Field \| </li>
	<li>Constr \| </li>
	<li><a href="#method.detail">Method</a></li>
	</ul>
	</div>
	<a name="skip.navbar.top">
	<!-- -->
	</a></div>
	<!-- ========= END OF TOP NAVBAR ========= -->
	<!-- ======== START OF CLASS DATA ======== -->
	<div class="header">
	<div class="subTitle">net.jini.space</div>
	<h2 title="Interface MatchSet" class="title">Interface MatchSet</h2>
	</div>
	<div class="contentContainer">
	<div class="description">
	<ul class="blockList">
	<li class="blockList">
	<dl>
	<dt>All Known Implementing Classes:</dt>
	<dd><a href="../../../org/apache/river/outrigger/MatchSetProxy.html" title="class in org.apache.river.outrigger">MatchSetProxy</a></dd>
	</dl>
	<hr>
	<br>
	<pre>public interface <span class="typeNameLabel">MatchSet</span></pre>
	<div class="block">A collection of <a href="../../../net/jini/core/entry/Entry.html" title="interface in net.jini.core.entry"><code>Entry</code></a> instances to be incrementally
	returned from a JavaSpaces service. Some operations on a
	space must return more entries than can be conveniently
	returned by a single call, generally because returning all the
	entries in one result would consume too many resources in the
	client or introduce too much latency before the first entry
	could be processed. In these cases, match sets are returned to
	incrementally return the necessary entries. A
	<code>MatchSet</code> instance is a proxy object that can be
	used to access a match set created by a space.<p>

	Typically match sets are created by some factory method on the
	space (for example, <a href="../../../net/jini/space/JavaSpace05.html#contents-java.util.Collection-net.jini.core.transaction.Transaction-long-long-"><code>JavaSpace05.contents</code></a>) which returns a <code>MatchSet</code>
	instance that will serve as a proxy to the match set. The match
	set will initially contain some population of entries specified
	by the operation that created it. These entries can be
	retrieved by calling <a href="../../../net/jini/space/MatchSet.html#next--"><code>next</code></a>. A successful call to
	<code>next</code> will remove the returned <code>Entry</code>
	from the match set. Match sets can end up in one of two
	terminal states, <em>exhausted</em> or <em>invalidated</em>.
	Under what conditions a match set enters one of these states is
	specified by the operation that created it. An exhausted match
	set is empty and will have no more entries added. Calling
	<code>next</code> on an exhausted match set must always return
	<code>null</code>. Calling <code>next</code> on an invalidated
	match set may return a non-<code>null</code> value, or it may
	throw one of the allowed exceptions. In particular it may
	throw <a href="http://docs.oracle.com/javase/6/docs/api/java/rmi/NoSuchObjectException.html?is-external=true" title="class or interface in java.rmi"><code>NoSuchObjectException</code></a> to indicate that the match
	set has been invalidated. Once <code>next</code> throws a
	<code>NoSuchObjectException</code>, all future
	<code>next</code> calls on that instance must also throw
	<code>NoSuchObjectException</code>. Calling <code>next</code>
	on an invalidated match set must never return
	<code>null</code>. Implementations must not add entries to an
	invalidated match set. <p>

	Between the time a match set is created and the time it reaches a
	terminal state, entries may be added by the space. However, an
	<code>Entry</code> that is removed by a <code>next</code> call
	must not be added back to a match set (though if there is a
	distinct but equivalent entry in the space it may be
	added). The space may also remove entries independent of
	<code>next</code> calls. The conditions under which entries
	will be removed independent of <code>next</code> calls or added
	after the initial creation of the match set are specified by
	the operation that created the match set. <p>

	If there is a possibility that a match set may become
	invalidated, it must be leased and an appropriate proxy must be
	returned by the <a href="../../../net/jini/space/MatchSet.html#getLease--"><code>getLease</code></a> method. If there is
	no possibility that the match set will become invalidated,
	implementations should not lease the match set. If a match set
	is not leased, then <code>getLease</code> must return
	<code>null</code>. <p>

	An active lease on a match set serves as a hint to the space
	that the client is still interested in the match set, and as a
	hint to the client that the match set is still functioning.
	However, implementations are allowed to invalidate match sets
	associated with active leases and to unilaterally cancel leases
	associated with functioning match sets. If a match set is
	leased and the lease is active, implementations should, to the
	best of their ability, maintain the match set and not invalidate
	it. There are cases, however, where this may not be possible in
	particular, it is not expected that implementations will
	maintain match sets across crashes. If the lease expires or is
	canceled, an implementation should invalidate the match
	set. An implementation must unilaterally cancel a match set's
	lease if the match set is invalidated. An implementation may
	unilaterally cancel the lease at other times without necessarily
	invalidating the match set. Clients should <em>not</em> assume
	that the resources associated with a leased match set will be
	freed if the match set reaches the exhausted state, and should
	instead cancel the lease.

	This interface is not a remote interface; though in general a
	<code>MatchSet</code> is a proxy for some remote match set,
	only the <code>next</code> method is considered to be a remote
	method, and as outlined in its <a href="../../../net/jini/space/MatchSet.html#next--">description</a>
	it deviates in a number of ways from normal Java(TM) Remote
	Method Invocation remote method semantics.</div>
	<dl>
	<dt><span class="simpleTagLabel">Since:</span></dt>
	<dd>2.1</dd>
	</dl>
	</li>
	</ul>
	</div>
	<div class="summary">
	<ul class="blockList">
	<li class="blockList">
	<!-- ========== METHOD SUMMARY =========== -->
	<ul class="blockList">
	<li class="blockList"><a name="method.summary">
	<!-- -->
	</a>
	<h3>Method Summary</h3>
	<table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Method Summary table, listing methods, and an explanation">
	<caption><span id="t0" class="activeTableTab"><span>All Methods</span><span class="tabEnd"> </span></span><span id="t2" class="tableTab"><span><a href="javascript:show(2);">Instance Methods</a></span><span class="tabEnd"> </span></span><span id="t3" class="tableTab"><span><a href="javascript:show(4);">Abstract Methods</a></span><span class="tabEnd"> </span></span></caption>
	<tr>
	<th class="colFirst" scope="col">Modifier and Type</th>
	<th class="colLast" scope="col">Method and Description</th>
	</tr>
	<tr id="i0" class="altColor">
	<td class="colFirst"><code><a href="../../../net/jini/core/lease/Lease.html" title="interface in net.jini.core.lease">Lease</a></code></td>
	<td class="colLast"><code><span class="memberNameLink"><a href="../../../net/jini/space/MatchSet.html#getLease--">getLease</a></span>()</code>
	<div class="block">Returns a proxy to the <a href="../../../net/jini/core/lease/Lease.html" title="interface in net.jini.core.lease"><code>Lease</code></a> associated with this
	match set, or <code>null</code> if this match set is not
	leased.</div>
	</td>
	</tr>
	<tr id="i1" class="rowColor">
	<td class="colFirst"><code><a href="../../../net/jini/core/entry/Entry.html" title="interface in net.jini.core.entry">Entry</a></code></td>
	<td class="colLast"><code><span class="memberNameLink"><a href="../../../net/jini/space/MatchSet.html#getSnapshot--">getSnapshot</a></span>()</code>
	<div class="block">Returns a <em>snapshot</em> of the <a href="../../../net/jini/core/entry/Entry.html" title="interface in net.jini.core.entry"><code>Entry</code></a> removed by
	the last call to <a href="../../../net/jini/space/MatchSet.html#next--"><code>next</code></a>.</div>
	</td>
	</tr>
	<tr id="i2" class="altColor">
	<td class="colFirst"><code><a href="../../../net/jini/core/entry/Entry.html" title="interface in net.jini.core.entry">Entry</a></code></td>
	<td class="colLast"><code><span class="memberNameLink"><a href="../../../net/jini/space/MatchSet.html#next--">next</a></span>()</code>
	<div class="block">Removes one <code>Entry</code> from the match set and
	returns a copy to the caller.</div>
	</td>
	</tr>
	</table>
	</li>
	</ul>
	</li>
	</ul>
	</div>
	<div class="details">
	<ul class="blockList">
	<li class="blockList">
	<!-- ============ METHOD DETAIL ========== -->
	<ul class="blockList">
	<li class="blockList"><a name="method.detail">
	<!-- -->
	</a>
	<h3>Method Detail</h3>
	<a name="next--">
	<!-- -->
	</a>
	<ul class="blockList">
	<li class="blockList">
	<h4>next</h4>
	<pre><a href="../../../net/jini/core/entry/Entry.html" title="interface in net.jini.core.entry">Entry</a> next()
	throws <a href="http://docs.oracle.com/javase/6/docs/api/java/rmi/RemoteException.html?is-external=true" title="class or interface in java.rmi">RemoteException</a>,
	<a href="../../../net/jini/core/entry/UnusableEntryException.html" title="class in net.jini.core.entry">UnusableEntryException</a></pre>
	<div class="block">Removes one <code>Entry</code> from the match set and
	returns a copy to the caller. Returns <code>null</code> if
	the match set is empty. The returned <code>Entry</code>
	must be unmarshalled in accordance with the <a
	href=http://www.jini.org/standards/index.html>Jini Entry
	Specification</a>.<p>

	A given invocation of this method may perform remote
	communications, but generally the <code>next</code> method
	is not expected to have <a href="../../../net/jini/core/constraint/package-summary.html">remote method constraints</a> that
	can vary from invocation to invocation. Instead the set of
	constraints associated with the <code>next</code> method
	will be fixed at the time the match set was created, even
	if this object implements an interface like <a href="../../../net/jini/core/constraint/RemoteMethodControl.html" title="interface in net.jini.core.constraint"><code>RemoteMethodControl</code></a> that would otherwise allow the set of
	constraints associated with the <code>next</code> method to
	be altered.<p></div>
	<dl>
	<dt><span class="returnLabel">Returns:</span></dt>
	<dd>an <code>Entry</code> from the match set, or
	<code>null</code> if the match set is empty</dd>
	<dt><span class="throwsLabel">Throws:</span></dt>
	<dd><code><a href="../../../net/jini/core/entry/UnusableEntryException.html" title="class in net.jini.core.entry">UnusableEntryException</a></code> - if the entry removed from
	the match set could not be unmarshalled</dd>
	<dd><code><a href="http://docs.oracle.com/javase/6/docs/api/java/rmi/RemoteException.html?is-external=true" title="class or interface in java.rmi">RemoteException</a></code> - if a communication error occurs. If a
	<code>RemoteException</code> is thrown, no
	<code>Entry</code> was removed from the match set
	because of this call</dd>
	</dl>
	</li>
	</ul>
	<a name="getLease--">
	<!-- -->
	</a>
	<ul class="blockList">
	<li class="blockList">
	<h4>getLease</h4>
	<pre><a href="../../../net/jini/core/lease/Lease.html" title="interface in net.jini.core.lease">Lease</a> getLease()</pre>
	<div class="block">Returns a proxy to the <a href="../../../net/jini/core/lease/Lease.html" title="interface in net.jini.core.lease"><code>Lease</code></a> associated with this
	match set, or <code>null</code> if this match set is not
	leased.</div>
	<dl>
	<dt><span class="returnLabel">Returns:</span></dt>
	<dd>a proxy for the match set's lease, or
	<code>null</code> if there is no lease associated with this
	match set</dd>
	</dl>
	</li>
	</ul>
	<a name="getSnapshot--">
	<!-- -->
	</a>
	<ul class="blockListLast">
	<li class="blockList">
	<h4>getSnapshot</h4>
	<pre><a href="../../../net/jini/core/entry/Entry.html" title="interface in net.jini.core.entry">Entry</a> getSnapshot()</pre>
	<div class="block">Returns a <em>snapshot</em> of the <a href="../../../net/jini/core/entry/Entry.html" title="interface in net.jini.core.entry"><code>Entry</code></a> removed by
	the last call to <a href="../../../net/jini/space/MatchSet.html#next--"><code>next</code></a>. Snapshots are defined
	in section JS.2.6 of the <a
	href=http://www.jini.org/standards/index.html>
	JavaSpaces Service Specification</a> and are an
	alternative representation of a given <code>Entry</code>
	produced by a particular space for use with that same
	space. Passing a snapshot to a space is generally more
	efficient than passing the original representation.<p>

	Any snapshot returned by this method will meet the same
	contract as the object returned by passing the result of
	the last <code>next</code> invocation to <a href="../../../net/jini/space/JavaSpace.html#snapshot-net.jini.core.entry.Entry-"><code>JavaSpace.snapshot</code></a>.<p>

	Generally there is a cost associated with calling the
	<code>JavaSpace.snapshot</code> method. Thus creating a
	snapshot using that method is usually only worthwhile if
	the resulting snapshot is used more than once. The cost of
	invoking this method should be low and should be worthwhile
	even if the resulting snapshot is used only once. <p></div>
	<dl>
	<dt><span class="returnLabel">Returns:</span></dt>
	<dd>a <em>snapshot</em> of the <a href="../../../net/jini/core/entry/Entry.html" title="interface in net.jini.core.entry"><code>Entry</code></a> removed
	from the match set by the last call to <a href="../../../net/jini/space/MatchSet.html#next--"><code>next</code></a></dd>
	<dt><span class="throwsLabel">Throws:</span></dt>
	<dd><code><a href="http://docs.oracle.com/javase/6/docs/api/java/lang/IllegalStateException.html?is-external=true" title="class or interface in java.lang">IllegalStateException</a></code> - if the last call to
	<code>next</code> did not remove an
	<code>Entry</code> from the match set, or no call
	to <code>next</code> has been made</dd>
	</dl>
	</li>
	</ul>
	</li>
	</ul>
	</li>
	</ul>
	</div>
	</div>
	<!-- ========= END OF CLASS DATA ========= -->
	<!-- ======= START OF BOTTOM NAVBAR ====== -->
	<div class="bottomNav"><a name="navbar.bottom">
	<!-- -->
	</a>
	<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
	<a name="navbar.bottom.firstrow">
	<!-- -->
	</a>
	<ul class="navList" title="Navigation">
	<li><a href="../../../overview-summary.html">Overview</a></li>
	<li><a href="package-summary.html">Package</a></li>
	<li class="navBarCell1Rev">Class</li>
	<li><a href="class-use/MatchSet.html">Use</a></li>
	<li><a href="package-tree.html">Tree</a></li>
	<li><a href="../../../deprecated-list.html">Deprecated</a></li>
	<li><a href="../../../index-all.html">Index</a></li>
	<li><a href="../../../help-doc.html">Help</a></li>
	</ul>
	</div>
	<div class="subNav">
	<ul class="navList">
	<li><a href="../../../net/jini/space/JavaSpace05.html" title="interface in net.jini.space"><span class="typeNameLink">Prev Class</span></a></li>
	<li>Next Class</li>
	</ul>
	<ul class="navList">
	<li><a href="../../../index.html?net/jini/space/MatchSet.html" target="_top">Frames</a></li>
	<li><a href="MatchSet.html" target="_top">No Frames</a></li>
	</ul>
	<ul class="navList" id="allclasses_navbar_bottom">
	<li><a href="../../../allclasses-noframe.html">All Classes</a></li>
	</ul>
	<div>
	<script type="text/javascript"><!--
	allClassesLink = document.getElementById("allclasses_navbar_bottom");
	if(window==top) {
	allClassesLink.style.display = "block";
	}
	else {
	allClassesLink.style.display = "none";
	}
	//-->
	</script>
	</div>
	<div>
	<ul class="subNavList">
	<li>Summary: </li>
	<li>Nested \| </li>
	<li>Field \| </li>
	<li>Constr \| </li>
	<li><a href="#method.summary">Method</a></li>
	</ul>
	<ul class="subNavList">
	<li>Detail: </li>
	<li>Field \| </li>
	<li>Constr \| </li>
	<li><a href="#method.detail">Method</a></li>
	</ul>
	</div>
	<a name="skip.navbar.bottom">
	<!-- -->
	</a></div>
	<!-- ======== END OF BOTTOM NAVBAR ======= -->
	<p class="legalCopy"><small>Copyright 2007-2013, multiple authors.<br>Licensed under the <a href=http://www.apache.org/licenses/LICENSE-2.0 target=child >Apache License, Version 2.0</a>, see the <a href=../../../doc-files/NOTICE target=child >NOTICE</a> file for attributions.</small></p>
	</body>
	</html>