--- a/ldp-paging.html Wed Jul 09 13:22:55 2014 -0400
+++ b/ldp-paging.html Wed Jul 09 17:33:31 2014 -0400
@@ -394,7 +394,7 @@
<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</sub>, P<sub>2</sub>, ...,P<sub>n</sub></var>,
+ <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
of another resource <var>P</var>, called the <a>paged resource</a>.
For readers
@@ -408,25 +408,43 @@
in cases where both are mentioned in
close proximity.
</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.
+ 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
+ It is not implied by LDP Paging,
+ absent additional concrete assertions like those defined later 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>
- of a <a title="Paged resource">paged resource</a> <var>P</var>. Syntactically, a
+ <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
+ redirects to (<code>303</code> response) or provides the representation of (<code>2NN response</code>) 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>.
+ Syntactically, a
HTTP <code>Link <<var>P<sub>1</sub></var>>; rel='first'</code>
header [[!RFC5988]].
<p></p></dd>
<dt><dfn>next page link</dfn></dt>
- <dd>A link to the next <a title="In-sequence page resource">in-sequence page resource</a>
+ <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
HTTP <code>Link <<var>P<sub>i</sub></var>>; rel='next'</code>
- header [[!RFC5988]][[!HTML5]] where the target URI is <var>P<sub>i=2...n</sub></var>.
+ header [[!RFC5988]][[!HTML5]] where
+ the context URI identifies some <var>P<sub>i=1 (first)...n-1 (next to last)</sub></var> and
+ the target URI identifies <var>P<sub>i+1</sub></var>.
<p></p></dd>
<dt><dfn>last page link</dfn></dt>
- <dd>A link to the last <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
+ <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>.
+ Syntactically, a
HTTP <code>Link <<var>P<sub>n</sub></var>>; rel='last'</code>
header [[!RFC5988]].
<p></p></dd>
@@ -435,7 +453,9 @@
<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
HTTP <code>Link <<var>P<sub>i</sub></var>>; rel='prev'</code>
- header [[!RFC5988]][[!HTML5]] where the target URI is <var>P<sub>i=1...n-1</sub></var>.
+ header [[!RFC5988]][[!HTML5]] where
+ the context URI identifies some <var>P<sub>i=2...n (last)</sub></var> and
+ the target URI identifies <var>P<sub>i-1</sub></var>.
<p></p></dd>
<dt><dfn>paging link</dfn></dt>
@@ -622,7 +642,8 @@
<p>
The new protocol does not solve the problem of migrating existing clients from the old
"all" to the new "first chunk" semantic; neither would a <code>303 See Other</code> redirect
- from the old to the new URI, given the widespread historical client practice of automatically
+ from the old to the new URI, given the
+ <a href="http://www.w3.org/2001/tag/issues.html#httpRange-14">widespread historical client practice</a> of automatically
following <code>303</code> redirects and treating the redirected-to resource as equivalent
to the original. The safe route is to have clients explicitly tell the server that they
are capable of handling the "first chunk" semantic on the redirected-to URI; this is what
@@ -846,7 +867,7 @@
and a representation payload.
</p>
<p>
- As was true in the <a href="#ldpp-ex-paging-303"></a> <code>303 See Other</code> approach</a>,
+ As was true in the <a href="#ldpp-ex-paging-303"><code>303 See Other</code> approach</a>,
the server includes
a <code>Location: http://example.org/customer-relations?page1</code> HTTP response header
identifying the first page as the resource whose representation is enclosed in the response.
@@ -1016,6 +1037,46 @@
</section>
+<section id="ldpp-ex-paging-other-links">
+<h2>Optional paging links</h2>
+
+ <p>
+ The preceding paging examples in this section have all assumed that only <a>forward traversal</a>
+ is supported by the server, to reduce complexity.
+ A server might also support <a>backward traversal</a> through its pages, and/or direct access to the
+ <a title="first page link">first page</a> and/or <a title="last page link">last page</a> from any <a>in-sequence page resource</a>.
+ Those options would be reflected by adding some combination of the links below,
+ or equivalent semantically equivalent syntactic variations of them, to the response messages.
+ </p>
+
+ <ul>
+ <li>
+ The <a title="first page link">first page</a>'s <a href="#ldpp-ex-paging-2nn-resp1">response message</a> might also have the following links:
+<pre class="example">
+Link: <>; rel='first'
+Link: <http://example.org/customer-relations?p=2>; rel='last'
+</pre>
+ </li>
+ <li>
+ Any <a>in-sequence page resource</a>'s response message, including the <a title="first page link">first page</a> and the <a title="last page link">last page</a>,
+ might also have the following links:
+<pre class="example">
+Link: <>; rel='first'
+Link: <http://example.org/customer-relations?p=2>; rel='last'
+</pre>
+ </li>
+ <li>
+ The <a title="last page link">last page</a>'s <a href="#ldpp-ex-paging-2nn-resp2">response message</a> might also have the following links:
+<pre class="example">
+Link: <http://example.org/customer-relations?page1>; rel='first'
+Link: <http://example.org/customer-relations?page1>; rel='prev'
+Link: <>; rel='last'
+</pre>
+ </li>
+ </ul>
+
+</section>
+
</section> <!-- Example message exchanges -->
<section id="ldppclient">
@@ -1384,6 +1445,13 @@
and a corresponding parameter value identical to the ETag [[!RFC7232]]
of the <a>paged resource</a>.
For example: <code>Link: <http://example.org/customer-relations>; rel='canonical'; etag="customer-relations-v1"</code>
+ <blockquote><em>Non-normative note:</em>
+ If the <code>rel='canonical'; etag="..."</code> value changes as the client retrieves pages,
+ for example the value accompanying the first page's representation is <code>rel='canonical'; etag="v1"</code>
+ and the value accompanying the second page's representation is <code>rel='canonical'; etag="v2"</code>,
+ the client can detect that the <a>paged resource</a>'s state has changed.
+ Some clients will ignore such changes, but others may choose to react to them, for example by restarting the traversal.
+ </blockquote>
</h2></section>
<section id="ldpr-pagingGET-sequences-change"><h2 class="normal">
@@ -1894,6 +1962,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-09 - Fix Ashok's emailed comments (JA) </li>
<li>2014-07-09 - Clean up clients chapter, references, non/normative section listing in conformance, kitchen sink (JA) </li>
<li>2014-07-09 - Move paging example into "intro" chapter 4 (JA) </li>
<li>2014-07-08 - Resolve a set of editorial to-dos (JA) </li>