--- a/ldp-paging.html Tue Jul 29 16:00:27 2014 -0400
+++ b/ldp-paging.html Wed Jul 30 13:20:18 2014 -0400
@@ -380,33 +380,52 @@
<dt><dfn>Paged resource</dfn></dt>
<dd>A LDPR whose representation may be too large for a server to construct in a single HTTP response
(e.g. without running out of memory), for which an
- <a>LDP Paging server</a> offers a sequence of single-page <a title="Linked Data Platform Resource">LDPRs</a>.
+ <a>LDP Paging server</a> offers a <a>page sequence</a> that allows clients to obtain subsets of its state
+ over some period of time by making multiple HTTP requests.
<p>
- When the representations of the sequence's resources
- are combined by a client, the client has a (potentially incomplete or incoherent) copy of the paged resource's
- state. If a paged resource <var>P</var> is a LDP-RS and is broken into a sequence of pages
- (in-sequence page resources) <var>P<sub>1</sub>, P<sub>2</sub>, ...,P<sub>n</sub></var>,
- the representation of each <var>P<sub>i</sub></var> contains
- a subset of the triples in <var>P</var>.
+ For readers
+ familiar with paged feeds [[RFC5005]], a paged resource is similar to a logical feed.
+ Any resource could be considered to be a paged resource consisting of exactly one page,
+ although there is no known advantage in doing so.
+ </p>
+ <p></p></dd>
+
+ <dt><dfn>Page sequence</dfn></dt>
+ <dd>A sequence of related <a title="Linked Data Platform Resource">LDPRs</a>
+ <var>P<sub>1 (first)</sub>, P<sub>2</sub>, ...,P<sub>n (last)</sub></var>,
+ each of which contains a subset of the <a>paged resource</a>'s state.
+ <p>
+ When the representations of the sequence's <a title="In-sequence page resource">resources</a>
+ are combined by a client, the client has a copy of the <a>paged resource</a>'s
+ state; if the <a>paged resource</a> changed while the client was retrieving the sequence's resources,
+ then the client's copy of the <a>paged resource</a>'s state can be incomplete or inconsistent
+ with the state of the <a>paged resource</a> at any single instant in time.
+ Thus, it is impossible to strongly guarantee that the result of this retrieval and combination process is the same state that
+ the client would obtain using a single request (if that were possible), but LDP does provide
+ a way for <a href="#ldpr-notify-changes">clients to detect when the paged resource's state changed</a> during the retrieval process.
+ As long as the <a>paged resource</a>'s state did not change during the retrieval process, the
+ client's copy of the <a>paged resource</a>'s state will be as accurate as the server implementation
+ allows it to be.
+ </p>
+ <p>
+ If a paged resource <var>P</var> is a LDP-RS,
+ the representation of each <a>in-sequence page resource</a> contains
+ a subset of the triples in <var>P</var>, and a client can merge those graphs to combine them.
LDP allows paging of resources other than <a title="Linked Data Platform RDF Source">LDP-RSs</a>,
but does not specify how clients combine
their representations. See <a href="#ldpr" class="sectionRef"></a> for additional details.
</p>
For readers
- familiar with paged feeds [[RFC5005]], a paged resource is similar to a logical feed.
- Any resource could be considered to be a paged resource consisting of exactly one page,
- although there is no known advantage in doing so.
+ familiar with paged feeds [[RFC5005]], a <a>page sequence</a> is similar to a paged feed
+ and many of the same consideration (echoed above) apply.
<p></p></dd>
<dt><dfn>In-sequence page resource</dfn></dt>
- <dd>One of a sequence of related <a title="Linked Data Platform Resource">LDPRs</a>
- <var>P<sub>1 (first)</sub>, P<sub>2</sub>, ...,P<sub>n (last)</sub></var>,
- each of which contains a subset of the state
+ <dd>One LDPR in a <a>page sequence</a>,
+ which contains a subset of the state
of another resource <var>P</var>, called the <a>paged resource</a>.
For readers
- familiar with paged feeds [[RFC5005]], an in-sequence page resource is similar to a feed document and the same
- coherency/completeness considerations apply.
- <a href="#ldpr-pagingGET-sequences-change">LDP provides no guarantees that the sequence of page resources is stable</a>.
+ familiar with paged feeds [[RFC5005]], an in-sequence page resource is similar to a feed document.
<p>
Note: the choice of terms was designed to help authors and readers clearly differentiate between
the <a title="Paged resource"><em>resource being paged</em></a>, and the
@@ -416,20 +435,20 @@
</p>
<p>
Note: page sequences are described and named with respect to how they are traversed starting from the <a>paged resource</a>,
- with "first" being "nearest" to the <a>paged resource</a>, "last" the "furthest" from the <a>paged resource</a> (using only "forward" traversal),
- and so on. This <em>does not</em> imply anything more; the choice is arbitrary.
+ using only <a>forward traversal</a>.
+ This <em>does not</em> imply anything more; the choice is arbitrary.
For example, following forward links does not imply that resources later in the sequence are newer; the forward direction might
- correspond to moving forward or backward in time or along some other dimension, but any such relationship is server-specific
+ correspond to moving forward or backward in time or along some other dimension, but any such relationship is server-specific.
It is not implied by LDP Paging,
- absent additional concrete assertions like those defined later for LDPC representations.
+ absent additional concrete assertions like those <a href="#ldpc-HTTP_GET">defined later</a> for LDPC representations.
</p>
<p></p></dd>
<dt><dfn>first page link</dfn></dt>
<dd>A link to the first <a title="In-sequence page resource">in-sequence page resource</a> <var>P<sub>1 (first)</sub></var>
- of a <a title="Paged resource">paged resource</a> <var>P</var>. The first page is the one that a LDP paging server
+ of a <a>page sequence</a>. The first page is the one that a LDP paging server
redirects to (<code>303</code> response) or provides the representation of (<code>2NN</code> response) in response
- to a retrieval request for the <a>paged resource</a>'s URI; it is, in that sense, nearest to the <a>paged resource</a> <var>P</var>.
+ to a retrieval request for the <a>paged resource</a>'s URI.
Syntactically, a
HTTP <code>Link <<var>P<sub>1</sub></var>>; rel='first'</code>
header [[!RFC5988]].
@@ -437,7 +456,7 @@
<dt><dfn>next page link</dfn></dt>
<dd>A link to the next <a title="In-sequence page resource">in-sequence page resource</a>
- of a <a title="Paged resource">paged resource</a> <var>P</var>. Syntactically, a
+ of a <a>page sequence</a>. Syntactically, a
HTTP <code>Link <<var>P<sub>i</sub></var>>; rel='next'</code>
header [[!RFC5988]] where
the context URI identifies some <var>P<sub>i=1 (first)...n-1 (next to last)</sub></var> and
@@ -446,10 +465,8 @@
<dt><dfn>last page link</dfn></dt>
<dd>A link to the last <a title="In-sequence page resource">in-sequence page resource</a> <var>P<sub>n (last)</sub></var>
- of a <a title="Paged resource">paged resource</a> <var>P</var>.
- The last page is the page that terminates a <a>forward traversal</a> starting from
- the <a>first page link</a> (or from any later point in the sequence) because it contains no <a>next page link</a>;
- it is, in that sense, furthest from the <a>paged resource</a> <var>P</var>.
+ of a <a>page sequence</a>.
+ The last page is the page that terminates a <a>forward traversal</a>, because it contains no <a>next page link</a>.
Syntactically, a
HTTP <code>Link <<var>P<sub>n</sub></var>>; rel='last'</code>
header [[!RFC5988]].
@@ -457,7 +474,7 @@
<dt><dfn>previous page link</dfn></dt>
<dd>A link to the previous <a title="In-sequence page resource">in-sequence page resource</a>
- of a <a title="Paged resource">paged resource</a> <var>P</var>. Syntactically, a
+ of a <a>page sequence</a> Syntactically, a
HTTP <code>Link <<var>P<sub>i</sub></var>>; rel='prev'</code>
header [[!RFC5988]] where
the context URI identifies some <var>P<sub>i=2...n (last)</sub></var> and
@@ -476,10 +493,10 @@
<dd>The process of following <a title="next page link">next page links</a> from
some starting point.
<p>
- Note: "forward" should <i>not</i> be read to mean anything more than a name for one direction through the sequence.
- For example, following forward links does not imply that resources later in the sequence are newer; the forward direction might
+ Note: "forward" should <i>not</i> be read to mean anything more than a name for one direction through the <a>page sequence</a>.
+ For example, following forward links does not imply that resources later in the <a>page sequence</a> are newer; the forward direction might
correspond to moving forward in time, but any such relationship is server-specific not implied by LDP Paging
- absent additional concrete assertions like those defined later for LDPC representations.
+ absent additional concrete assertions like those <a href="#ldpc-HTTP_GET">defined later</a> for LDPC representations.
</p>
<p></p></dd>
@@ -487,7 +504,7 @@
<dd>The process of following <a title="previous page link">previous page links</a> from
some starting point.
<p>
- Note: "backward" should <i>not</i> be read to mean anything more than a name for one direction through the sequence.
+ Note: "backward" should <i>not</i> be read to mean anything more than a name for one direction through the <a>page sequence</a>.
</p>
<p></p></dd>
@@ -830,7 +847,7 @@
</li>
<li>
Since the <code>etag="customer-relations-v1"</code> parameter value of the canonical <a>paged resource</a>
- did not change across the client's process of retrieving the entire page sequence, it is assured that
+ did not change across the client's process of retrieving the entire <a>page sequence</a>, it is assured that
the merged response representations are equivalent to what it would have received had the server
provided the entire representation of the <a>paged resource</a> in a single <code>200 OK</code> response.
The client has <em>no assurance</em> that the current state of the <a>paged resource</a> remains unchanged
@@ -1029,7 +1046,7 @@
</li>
<li>
Since the <code>etag="customer-relations-v1"</code> parameter value of the canonical <a>paged resource</a>
- did not change across the client's process of retrieving the entire page sequence, it is assured that
+ did not change across the client's process of retrieving the entire <a>page sequence</a>, it is assured that
the merged response representations are equivalent to what it would have received had the server
provided the entire representation of the <a>paged resource</a> in a single <code>200 OK</code> response.
The client has <em>no assurance</em> that the current state of the <a>paged resource</a> remains unchanged
@@ -1121,7 +1138,7 @@
if the response also indicates that the <a title="Paged resource">paged resource's</a>
<a href="#ldpr-notify-changes">state has <i>not</i> changed</a>
while the client was traversing its <a title="In-sequence page resource">pages</a>.
- Servers might also limit the lifetime of a particular page sequence, and client requests after the server has
+ Servers might also limit the lifetime of a particular <a>page sequence</a>, and client requests after the server has
abandoned that sequence are likely to result in <code>410 Gone</code> or other <code>4xx</code> status codes.
</blockquote>
@@ -1478,11 +1495,11 @@
<a title="LDP Paging server">LDP Paging servers</a> MAY
add or remove <a title="in-sequence page resource">in-sequence page resources</a> to a
<a title="Paged resource">paged resource's</a> sequence over time.
- If the page sequence is <a href="#ldpc-HTTP_GET">ordered</a>, then the ordering communicated by the server MUST be maintained;
+ If the <a>page sequence</a> is <a href="#ldpc-HTTP_GET">ordered</a>, then the ordering communicated by the server MUST be maintained;
the server SHOULD only add pages to the end of an unordered sequence.
</h2><!-- Was 4.10.2.1 / #ldpr-pagingGET-sequences-change -->
<blockquote><em>Non-normative note:</em>
- Servers might abandon an ordered page sequence, resulting in <code>4xx</code> status codes to subsequent requests,
+ Servers might abandon an ordered <a>page sequence</a>, resulting in <code>4xx</code> status codes to subsequent requests,
although it will be less disruptive to clients if the server either adds content to the appropriate existing page or
adds new pages at the proper point in the sequence. Clients have no more efficient means than a conditional retrieval
request on existing pages to detect the changed/added pages.
@@ -1492,7 +1509,7 @@
change as the state of the <a>paged resource</a> changes.
For example, a nominally last page's server might provide a
<a>next page link</a> when the page is retrieved again later.
- Similar situations arise when the page sequence crosses server boundaries;
+ Similar situations arise when the <a>page sequence</a> crosses server boundaries;
server A might host the initial portion of a sequence that links to the last page server A is aware of,
hosted on server B, and server B might extend the sequence of pages.
A nominally middle page <var>M</var> can become the last (or a non-existent) page if a competing request deletes
@@ -1527,7 +1544,7 @@
provide a <a>next page link</a>
in responses to <code>GET</code> requests with the final <a title="in-sequence page resource">in-sequence page resource</a>
as the <code>Request-URI</code>.
- This is the mechanism by which clients can discover the end of the page sequence
+ This is the mechanism by which clients can discover the end of the <a>page sequence</a>
as currently known by the server.
</h2></section><!-- Was 4.10.2.2.1 / #ldpr-pagingGET-lastnext-prohibited -->
@@ -1545,7 +1562,7 @@
provide a <a>previous page link</a>
in responses to <code>GET</code> requests with the <em>first</em> <a title="in-sequence page resource">in-sequence page resource</a>
as the <code>Request-URI</code>.
- This is one mechanism by which clients can discover the beginning of the page sequence
+ This is one mechanism by which clients can discover the beginning of the <a>page sequence</a>
as currently known by the server.
</h2></section><!-- Was 4.10.2.2.3 / #ldpr-pagingGET-firstprev-prohibited -->
@@ -1602,7 +1619,7 @@
<a title="LDP Paging server">LDP Paging servers</a> MUST
ensure that the <a title="membership triples">membership triple</a> and
<a title="containment triples">containment triple</a> for each member are part of the
- same <a>in-sequence page resource</a>, whenever both triples are present in the page sequence
+ same <a>in-sequence page resource</a>, whenever both triples are present in the <a>page sequence</a>
for a <a title="paged resource">paged LDPC</a>.
</h2></section>
@@ -2138,6 +2155,7 @@
<!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-paging-20140930/">Candidate Recommendation Draft</a></em></blockquote> wah -->
<!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-paging-20140730/">Last Call Draft</a></em></blockquote> -->
<ul>
+ <li>2014-07-30 - Rewording based on SS's 7/17 email comments (JA) </li>
<li>2014-07-29 - Fully specify 303+location's URI (JA) </li>
<li>2014-07-29 - Fuss with SortValueAscending value for Sandro (JA) </li>
<li>2014-07-29 - Update 6.2.9 to resolve the "add only at the end"/sorted container conflict (JA) </li>