--- a/ldp-paging.html Mon Jul 07 13:00:12 2014 +0200
+++ b/ldp-paging.html Mon Jul 07 11:27:00 2014 -0400
@@ -268,7 +268,7 @@
<h1>Introduction</h1>
<p>This specification provides a widely re-usable pattern to deal with large resources.
Depending on the server’s capabilities, a GET request on a <a title="Paged resource">resource</a> can
- be redirected to a <a title="Single-page resource">subset of the resource (one page)</a>, that provides access to subsequent pages
+ be redirected to a <a title="In-Sequence Page resource">subset of the resource (one page)</a>, that provides access to subsequent pages
(see <a href="#ldpr-Paging" class="sectionRef"></a>).
</p>
<p>For context and background, it could be useful to read <a href="#bib-LDP-UCR">Linked Data Platform Use Case and Requirements</a> [[LDP-UCR]]
@@ -336,7 +336,7 @@
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
- (single-page resources) <var>P<sub>1</sub>, P<sub>2</sub>, ...,P<sub>n</sub></var>,
+ (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>.
LDP allows paging of resources other than <a title="Linked Data Platform RDF Source">LDP-RSs</a>,
@@ -349,47 +349,47 @@
although there is no known advantage in doing so.
<p></p></dd>
- <dt><dfn>Single-page resource</dfn></dt>
+ <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>,
each of which contains a subset of the state
of another resource <var>P</var>. <var>P</var> is called the paged resource.
For readers
- familiar with paged feeds [[RFC5005]], a single-page resource is similar to a feed document and the same
+ 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>.
<!-- TODO: check link target ^ -->
<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
- <a title="Single-page resource"><em>individual page resources</em></a>,
+ <a title="In-sequence page resource"><em>individual page resources</em></a>,
in cases where both are mentioned in
close proximity.
<p></p></dd>
<dt><dfn>first page link</dfn></dt>
- <dd>A link to the first <a title="Single-page resource">single-page resource</a>
+ <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
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="Single-page resource">single-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>.
<p></p></dd>
<dt><dfn>last page link</dfn></dt>
- <dd>A link to the last <a title="Single-page resource">single-page resource</a>
+ <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
HTTP <code>Link <<var>P<sub>n</sub></var>>; rel='last'</code>
header [[!RFC5988]].
<p></p></dd>
<dt><dfn>previous page link</dfn></dt>
- <dd>A link to the previous <a title="Single-page resource">single-page resource</a>
+ <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>.
@@ -468,12 +468,6 @@
</p>
<section><h2>General</h2>
- <section id="ldpp-server-initiated"><h2 class="normal"><a title="LDP Paging client">LDP Paging clients</a> MUST
- be paging-aware in cases where LDP Paging servers initiate paging.
- </h2>
- <p><em>TODO</em>: Confirm this client MUST for server-initiated paging</p>
- </section>
-
<section id="ldpp-client-traversal"><h2 class="normal"><a title="LDP Paging client">LDP Paging clients</a> MUST
be capable of <a>forward traversal</a> and/or <a>backward traversal</a>.
<!-- TODO: and/or is meaningless, must be at least one -->
@@ -481,15 +475,16 @@
</section>
<section id="ldpp-client-linkschg"><h2 class="normal"><a title="LDP Paging client">LDP Paging clients</a> MUST NOT
- assume that any <a title="single-page resource">single-page resource's</a> <a title="paging link">paging links</a>
- will remain unchanged when the <a>single-page resource</a> is retrieved more than once. Such an assumption would
+ assume that any <a title="In-sequence page resource">in-sequence page resource's</a> <a title="paging link">paging links</a>
+ will remain unchanged when the <a title="In-sequence page resource">in-sequence page resource</a>
+ is retrieved more than once. Such an assumption would
conflict with a server's ability to
<a href="#ldpr-pagingGET-sequences-change">add pages to a sequence</a> as the <a>paged resource</a> changes, for example.
</h2>
</section>
<section id="ldpp-client-4xxok"><h2 class="normal"><a title="LDP Paging client">LDP Paging clients</a> MUST NOT
- assume that any <a title="single-page resource">single-page resource's</a> <a title="paging link">paging links</a>
+ assume that any <a title="In-sequence page resource">in-sequence page resource's</a> <a title="paging link">paging links</a>
will always be accessible.
<blockquote><em>Non-normative note:</em>
Such an assumption would
@@ -500,7 +495,7 @@
or the server. Such a response would be unusual, and would likely signal an error,
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="single-page resource">pages</a>.
+ while the client was traversing its <a title="In-sequence page resource">pages</a>.
</blockquote>
</h2>
</section>
@@ -519,18 +514,18 @@
To address this problem, <a title="LDP Paging server">LDP Paging servers</a> can support a technique called Paging.
When a client retrieves such a resource, the server redirects the client to a "first page" resource, and includes in its response
a link to the next part of the resource's state, all at URLs of the server's choosing.
- The representation of <a title="Single-page resource">each page of an LDPR</a>
+ The representation of <a title="In-sequence page resource">each page of an LDPR</a>
is typically a subset of the <a title="Paged resource">paged resource</a>.
Any LDPR can be paged, but certain aspects of paging like ordering are only well-defined for LDP-RS's or LDPCs.
</p>
<p>
Logically, paging breaks up the <a>paged resource</a>
- into a list of <a title="Single-page resource">single-page resources</a> (chunks) whose representations the client can retrieve.
+ into a list of <a title="In-sequence page resource">in-sequence page resources</a> (chunks) whose representations the client can retrieve.
A server can offer links that support forward and/or backward traversal of
the pages, but it has to offer at least one.
Likewise, some clients will be interested in knowing whether or not competing requests altered the
<a>paged resource</a> while the client was retrieving pages, since LDP paging does not guarantee
- that those alterations were reflected in any <a>single-page resource</a> received by the client.
+ that those alterations were reflected in any <a>in-sequence page resource</a> received by the client.
Regardless of the server implementation, LDP only guarantees that while traversing a series of pages that
the client observes data that is equivalent to a database that uses
read committed isolation [[READ-COMMITTED]];
@@ -539,12 +534,12 @@
<a title="LDP Paging server">LDP Paging servers</a>.
LDP Paging does guarantee, however, that any information in the LDPR continuously present (neither added nor deleted) in the
<a title="Paged resource">paged resource</a> across the entire period of time when the client is retrieving pages will
- be present in at least one <a>single-page resource</a>.
+ be present in at least one <a>in-sequence page resource</a>.
LDP Paging defines a mechanism for informing clients that the <a>paged resource</a> has been changed so that they can, for example,
abandon a page traversal as early as possible.
</p>
<p>
- A list of <a title="Single-page resource">single-page resources</a> is inherently ordered by the links
+ A list of <a title="In-sequence page resource">in-sequence page resources</a> is inherently ordered by the links
that a <a>LDP Paging server</a> exposes on any <a>paged resource</a>. LDP Paging defines
a vocabulary for communicating the ordering algorithm used by the <a>LDP Paging server</a>
only in the case where the <a>paged resource</a> is an LDPC; other specifications or future
@@ -567,14 +562,14 @@
Note that paging provides a
<a href="#ldpr-guarantee-show-unchanged">weak guarantee of completeness</a>: if and only if it is the case
that no changes to the <a>paged resource</a> are made while
- a client retrieves every <a>single-page resource</a> logically comprising it,
+ a client retrieves every <a>in-sequence page resource</a> logically comprising it,
then the client will expect to have a complete picture of the <a>paged resource</a>
at a point in time. Since LDP Paging ensures that clients have a way to find
out when the <a>paged resource</a> has changed, this is a stronger guarantee
than the one described for paged feeds [[RFC5005]], but it does require the client
to detect when the condition holds.
Paging <i>does not guarantee</i> that it will ever be possible to successfully
- retrieve all the <a>single-page resource</a>s without the <a>paged resource</a>
+ retrieve all the <a>in-sequence page resource</a>s without the <a>paged resource</a>
being added to or changed, so clients requiring such a guarantee
may not find all <a>paged resource</a>s usable in practice.
</p>
@@ -707,7 +702,7 @@
<code>o:client</code> representations in the order
<code>#JohnZSmith, #BettyASmith, #JoanRSmith, #GlenWSmith, #AlfredESmith</code> (or indeed,
in <i>any</i> predictable order), then it can put the "last seen" identifier in the <a>next page link</a>
- of each <a>single-page resource</a> as it is retrieved <em>by each client</em>. The "session state"
+ of each <a>in-sequence page resource</a> as it is retrieved <em>by each client</em>. The "session state"
is, in effect, kept by the client.
In this case, the <a>next page link</a> in the first page might be:
</p>
@@ -733,7 +728,7 @@
<p>In addition to the requirements set forth in <a href="#ldpr-HTTP_GET" class="sectionRef"></a> on HTTP <code>GET</code>,
<a title="LDP Paging server">LDP Paging servers</a> must
also follow the requirements in this section for all <a title="Paged resource">paged resources</a>
- and their associated <a title="Single-page resource">single-page resources</a>.
+ and their associated <a title="in-sequence page resource">in-sequence page resources</a>.
<!-- TODO: remove this clause? circular ref -->
</p>
@@ -810,7 +805,7 @@
<section id="ldpr-guarantee-show-unchanged"><h2 class="normal">
<a title="LDP Paging server">LDP Paging servers</a> MUST
ensure that all state present in the <a>paged resource</a> throughout a client's <em>entire</em> traversal operation
- is represented in at least one <a>single-page resource</a>. In other words, whatever subset of the
+ is represented in at least one <a>in-sequence page resource</a>. In other words, whatever subset of the
<a>paged resource</a> that is <em>not added, updated, or removed during the client's traversal</em>
of its pages has to be present in one of the pages.
</h2>
@@ -871,7 +866,7 @@
HTTP <code>GET</code> responses, and SHOULD include the same header on all <code>4xx</code>
status code responses.
The link's
- context URI identifies the <a>single-page resource</a> being retrieved,
+ context URI identifies the <a>in-sequence page resource</a> being retrieved,
target URI identifies the <a>paged resource</a>,
link relation type is <code>canonical</code>,
and
@@ -883,12 +878,12 @@
<section id="ldpr-pagingGET-sequences-change"><h2 class="normal">
<a title="LDP Paging server">LDP Paging servers</a> MAY
- add or remove <a title="Single-page resource">single-page resources</a> to a
+ 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,
but SHOULD only add pages to the end of a sequence.
</h2><!-- Was 4.10.2.1 / #ldpr-pagingGET-sequences-change -->
<blockquote><em>Non-normative note:</em>
- As a result, clients retrieving any <a>single-page resource</a> several times can observe its place in the sequence
+ As a result, clients retrieving any <a>in-sequence page resource</a> several times can observe its place in the sequence
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.
@@ -903,19 +898,19 @@
<section id="ldpr-pagingGET-first-allowed-onpages"><h2 class="normal">
<a title="LDP Paging server">LDP Paging servers</a> MAY provide
a <a>first page link</a> when responding to
- requests with any <a title="Single-page resource">single-page resource</a> as the <code>Request-URI</code>.
+ requests with any <a title="in-sequence page resource">in-sequence page resource</a> as the <code>Request-URI</code>.
</h2></section><!-- Was 4.10.2.1.1 / #ldpr-pagingGET-sequences-change -->
<section id="ldpr-pagingGET-last-allowed-onpages"><h2 class="normal">
<a title="LDP Paging server">LDP Paging servers</a> MAY
provide a <a>last page link</a>
- in responses to <code>GET</code> requests with any <a title="Single-page resource">single-page resource</a> as the <code>Request-URI</code>.
+ in responses to <code>GET</code> requests with any <a title="in-sequence page resource">in-sequence page resource</a> as the <code>Request-URI</code>.
</h2></section><!-- Was 4.10.2.1.3 / #ldpr-pagingGET-last-allowed-onpages -->
<section id="ldpr-pagingGET-next-reqd"><h2 class="normal">
<a title="LDP Paging server">LDP Paging servers</a> MUST
provide a <a>next page link</a>
- in responses to <code>GET</code> requests with any <a title="Single-page resource">single-page resource</a>
+ in responses to <code>GET</code> requests with any <a title="in-sequence page resource">in-sequence page resource</a>
<em>other than the final page</em>
as the <code>Request-URI</code>.
This is the mechanism by which clients can discover the URL of the next page.
@@ -925,7 +920,7 @@
<section id="ldpr-pagingGET-lastnext-prohibited"><h2 class="normal">
<a title="LDP Paging server">LDP Paging servers</a> MUST NOT
provide a <a>next page link</a>
- in responses to <code>GET</code> requests with the final <a title="Single-page resource">single-page resource</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
as currently known by the server.
@@ -934,7 +929,7 @@
<section id="ldpr-pagingGET-prev-allowed"><h2 class="normal">
<a title="LDP Paging server">LDP Paging servers</a> MAY
provide a <a>previous page link</a>
- in responses to <code>GET</code> requests with any <a title="Single-page resource">single-page resource</a>
+ in responses to <code>GET</code> requests with any <a title="in-sequence page resource">in-sequence page resource</a>
<em>other than the first page</em>
as the <code>Request-URI</code>.
This is one mechanism by which clients can discover the URL of the previous page.
@@ -943,20 +938,28 @@
<section id="ldpr-pagingGET-firstprev-prohibited"><h2 class="normal">
<a title="LDP Paging server">LDP Paging servers</a> MUST NOT
provide a <a>previous page link</a>
- in responses to <code>GET</code> requests with the <em>first</em> <a title="Single-page resource">single-page resource</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
as currently known by the server.
</h2></section><!-- Was 4.10.2.2.3 / #ldpr-pagingGET-firstprev-prohibited -->
- <section id="ldpr-pagingGET-page-type-reqd"><h2 class="normal">
- <a title="LDP Paging server">LDP Paging servers</a> MUST
- provide an HTTP <code>Link</code>
- header whose target URI is <code>http://www.w3.org/ns/ldp#Page</code>, and whose link relation type is <code>type</code> [[!RFC5988]]
- in responses to <code>GET</code> requests with any <a title="Single-page resource">single-page resource</a>
- as the <code>Request-URI</code>.
- This is one mechanism by which clients know that the resource is one of a sequence of pages.
- </h2></section><!-- Was 4.10.2.4 / #ldpr-pagingGET-page-type-reqd -->
+ <section id="ldpr-pagingGET-page-type-reqd"><h2 class="normal">
+ <a title="LDP Paging server">LDP Paging servers</a> MUST
+ provide an HTTP <code>Link</code>
+ header whose target URI is <code>http://www.w3.org/ns/ldp#Page</code>, and whose link relation type is <code>type</code> [[!RFC5988]]
+ in responses to <code>GET</code> requests with any <a title="in-sequence page resource">in-sequence page resource</a>
+ as the <code>Request-URI</code>.
+ This is one mechanism by which clients know that the resource is one of a sequence of pages.
+ </h2></section><!-- Was 4.10.2.4 / #ldpr-pagingGET-page-type-reqd -->
+
+ <section id="ldpr-pagingGET-only-paging-clients"><h2 class="normal">
+ <a title="LDP Paging server">LDP Paging servers</a> MUST NOT
+ initiate paging unless the client has indicated it understands paging.
+ The only standard means defined by LDP paging for a client to signal a server that the client
+ understands paging is via the <a href="#ldpp-hints-page-size">client hint</a> defined below;
+ other implementation-specific means could also be used.
+ </h2></section>
</section>
@@ -972,6 +975,7 @@
<h3>Summary</h3>
<p>This specification introduces new ...
+ <!-- TODO: fill in summary -->
<!--
parameters on the HTTP <code>Prefer</code> request header's
<code>return=representation</code> preference [[!RFC7240]], used optionally by clients to
@@ -1026,7 +1030,8 @@
<code>token</code> is as defined in [[!RFC7230]].
The generic preference BNF [[!RFC7240]] allows either a quoted string or a token as the value of a
preference parameter; LDP Paging assigns a meaning to the value only when it is a quoted string.
- Servers MAY ignore a page size of zero, or unrecognized <code>units</code>,
+ <a title="LDP Paging server">LDP Paging servers</a> MAY
+ ignore a page size of zero, or unrecognized <code>units</code>,
and process the request as if the hint was absent.
</p>
</blockquote>
@@ -1038,7 +1043,7 @@
<h3>Examples</h3>
<p id="prefer-examples-direct-minimal-container-only1">
- Clients interested in receiving at most 500 RDF triples per <a title="single-page resource">page</a>
+ Clients interested in receiving at most 500 RDF triples per <a title="in-sequence page resource">page</a>
would use add this HTTP header on a <code>GET</code> request:
<code>Prefer: return=representation; page-size="500 rdf-triples"</code>
</p>
@@ -1178,7 +1183,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 on the
- same <a>single-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 page sequence
for a <a title="paged resource">paged LDPC</a>.
</h2></section>
@@ -1408,6 +1413,8 @@
<!-- <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-07 - Clients must consent to/invite paging per 20140630 resolution 2 (JA) </li>
+ <li>2014-07-07 - Rename single-page resource to in-sequence page resource per 20140630 resolution 3 (JA) </li>
<li>2014-06-10 - Use http-bis and Prefer RFC numbers, adjust BNF to match bis changes (JA) </li>
<li>2014-05-22 - Spec membership & containment triples on same page (JA) </li>
<li>2014-05-22 - Spec syntax for page size hint; still need to wrap more text and examples around it (JA) </li>