--- a/ldp-paging.html Tue May 20 17:41:18 2014 -0400
+++ b/ldp-paging.html Thu May 22 16:16:14 2014 -0400
@@ -4,12 +4,13 @@
DONE: http://www.w3.org/2013/meeting/ldp/2014-04-15#resolution_7 : At a minimum, on paging, we'll provide a way for clients to detect that a triple fell through the cracks during paging.
DONE: http://www.w3.org/2013/meeting/ldp/2014-04-17 resolution 3: spec sandro's paging proposal
DONE: http://www.w3.org/2012/ldp/track/issues/94 -> http://www.w3.org/2013/meeting/ldp/2014-05-12#resolution_3 2014-04-17 resolution 3: spec sandro's paging proposal
- TODO: http://www.w3.org/2013/meeting/ldp/2014-04-17 resolution 4: page size hint
- TODO: http://www.w3.org/2013/meeting/ldp/2014-04-17 resolution 5: contains+member triple always on same page
+ STARTED: http://www.w3.org/2013/meeting/ldp/2014-04-17 resolution 4: page size hint
+ DONE: http://www.w3.org/2013/meeting/ldp/2014-04-17 resolution 5: contains+member triple always on same page
DONE: http://www.w3.org/2013/meeting/ldp/2014-05-12 resolution 4: ordering undefined when paging non-LDPC LDPRs
DONE: Missing link header for equivalent of ldp:pageOf? Need to verify. Also we have ldp-paging:pageOf in samples
but it doesn't exist in rules or vocabulary doc, oversight?
+ TODO: Mine Jim des Riv May 21 email for more content
TODO: Example 11 is missing ldp:contains, true? Omit due to GET on page resource, should make it more clear.
TODO: Paging intro: add 3rd example showing header link age amongst pages and (HEAD on) the base resource.
Maybe also insert HEAD on base as new first example instead of relying on text alone.
@@ -100,6 +101,16 @@
wgPatentURI: "http://www.w3.org/2004/01/pp-impl/55082/status",
doRDFa: "1.1",
localBiblio: {
+ "HTTPBIS-MESSAGING": {
+ title: "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing"
+ , href: "http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-21"
+ , authors: [
+ "R. Fielding"
+ , "J. Reschke"
+ ]
+ , status: "In Last Call"
+ , publisher: "IETF"
+ },
"READ-COMMITTED": {
title: "Wikipedia: Isolation (database systems)"
, href: "http://en.wikipedia.org/wiki/Isolation_%28database_systems%29#Read_committed"
@@ -118,6 +129,15 @@
, status: "N/A"
, publisher: "Wikipedia"
},
+ "Prefer": {
+ title: "Prefer"
+ , href: "http://tools.ietf.org/html/draft-snell-http-prefer-18"
+ , authors: [
+ "J. Snell"
+ ]
+ , status: "Internet Draft"
+ , publisher: "IETF"
+ },
"RFC5005": {
title: "Feed Paging and Archiving"
, href: "http://tools.ietf.org/html/rfc5005"
@@ -425,15 +445,33 @@
<p><em>TODO</em>: Confirm this client MUST for server-initiated paging</p>
</section>
- <section id="ldpp-server-initiated"><h2 class="normal"><a title="LDP Paging client">LDP Paging clients</a> MUST
+ <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>.
</h2>
</section>
- <section id="ldpp-server-initiated"><h2 class="normal"><a title="LDP Paging client">LDP Paging clients</a> MUST NOT
+ <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. Doing so would
- conflict with a server's ability to <a href="#ldpr-pagingGET-sequences-change">add pages to a sequence</a>, for example.
+ will remain unchanged when the <a>single-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>
+ will always be accessible.
+ <blockquote><em>Non-normative note:</em>
+ Such an assumption would
+ conflict with a server's ability to <a href="#ldpr-pagingGET-sequences-change">remove pages from a sequence</a>
+ as the <a>paged resource</a> changes, for example.
+ One consequence of this is that clients can receive responses with <code>4xx</code> status codes
+ when following page links, purely due to timing issues and without any error on the part of the client
+ 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>.
+ </blockquote>
</h2>
</section>
@@ -496,8 +534,8 @@
a <a>next page link</a> containing the URL for the next page.
Clients inspect each response for the link to see if additional pages
are available; paging does not affect the choice of HTTP status code.
-<!-- TODO: link to formal definition/clauses -->
- Note that paging provides a weak guarantee of completeness: if and only if it is the case
+ 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,
then the client will expect to have a complete picture of the <a>paged resource</a>
@@ -600,8 +638,9 @@
</pre>
<p>
In this example, there are only two customers provided in the
- final page. To indicate this is the last page, the server omits the <code>Link: rel='next'</code>
- header in its response.
+ second page. To indicate this is also the last page, the server omits the <code>Link: rel='next'</code>
+ header in its response. The client combines the representations as appropriate for the media type;
+ in this case, an RDF graph merge is the logical choice.
</p>
<!-- TODO: show it both ways; if a competing change hit the container, or not -->
<p>
@@ -672,16 +711,31 @@
<!-- TODO: remove this clause? see what's still in LDP; as a SHOULD here it seems weird -->
<a title="LDP Paging server">LDP Paging servers</a> SHOULD allow clients to retrieve large LDP-RSs in
pages.
- See <a href="#ldpr-Paging" class="sectionRef"></a> for additional requirements associated with <a title="Paged resource">paged resources</a>.
</h2></section><!-- Was 4.2.14 / #ldpr-4_2_14 -->
- <section id="ldpr-split-any"><h2 class="normal">
- <!-- TODO: I thought we only defined paging for LDP-RS's so is this right? -->
+ <section id="ldpr-split-any-resource"><h2 class="normal">
<a title="LDP Paging server">LDP Paging servers</a> MAY
- treat any resource (LDP-RS or not) as a <a title="Paged resource">paged resource</a>.
- See <a href="#ldpr-Paging" class="sectionRef"></a> for additional details.
+ treat any resource (LDP-RS or not) as a <a>paged resource</a>.
</h2></section><!-- Was 4.2.15 / #ldpr-4_2_15 -->
+ <section id="ldpr-split-any-time"><h2 class="normal">
+ <a title="LDP Paging server">LDP Paging servers</a> MAY
+ vary their treatment of any resource (LDP-RS or not) as a <a>paged resource</a> over time.
+ In other words, given two attempts to retrieve the same resource at different points
+ in time, the server can choose to return a representation of the first page at one time and
+ of the entire resource at a different time. Clients distinguish between these cases based
+ on the <a href="#ldpr-status-code">status code</a>
+ and <a href="#ldpr-pagingGET-page-type-reqd">response headers</a>.
+ </h2></section>
+
+ <section id="ldpp-prefer"><h2 class="normal"><a title="LDP Paging server">LDP Paging servers</a>
+ SHOULD respect all of a client's <a href="#ldpp-hints">LDP-Paging-defined hints</a>, for example
+ <a href="#ldpp-hints-page-size">the largest page size</a>
+ the client is interested in processing,
+ to influence the amount of data returned in representations.
+ </h2></section>
+ <!-- TODO: Need to rework this^ and possibly relocate it ... does not apply only to LDPCs -->
+
<div class="atrisk" id="atrisk-333"><p class="atrisktext">Feature At Risk</p>
<p>The LDP Working Group proposes incorporation of the features described in the next compliance clause.</p>
<ul>
@@ -700,8 +754,9 @@
and its definition is given by
<a href="http://lists.w3.org/Archives/Public/www-tag/2014Jan/0015.html">Henry Thompson's strawman</a>, with the substitution of 333 for 2xx.
Note: nothing prevents servers or clients from using <code>303 See Other</code> responses to
- requests for <a title="Paged resource">paged resources</a>. The only significant difference between 303 and 333 responses
- is the extra round trip required for the client to retrieve the representation of the first page when using 303.
+ requests for <a title="Paged resource">paged resources</a>. The only significant differences between 303 and 333 responses
+ are the extra round trip required for the client to retrieve the representation of the first page when using 303,
+ and the non-cacheable nature of 303 responses.
</p></li>
<li><p>
Once LDP-Paging is a
@@ -717,7 +772,7 @@
<a title="LDP Paging server">LDP Paging servers</a> SHOULD respond
with HTTP status code <code>333 Returning Related</code>
to successful <code>GET</code> requests with any <a title="Paged resource">paged resource</a>
- as the <code>Request-URI</code>, although any appropriate code MAY be used.
+ as the <code>Request-URI</code>, although any appropriate code such as <code>303 See Other</code> MAY be used.
</h2></section>
<section id="ldpr-guarantee-show-unchanged"><h2 class="normal">
@@ -727,7 +782,7 @@
<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>
- <blockquote>Non-normative note:
+ <blockquote><em>Non-normative note:</em>
As a consequence, if the <a>paged resource</a> does not change <em>at all</em> during the traversal,
then the client has a complete view of its state as given by the negotiated response media type
<em>at the point in time when the final page was retrieved</em>.
@@ -735,7 +790,7 @@
were actually updated will differ; the client has no LDP Paging-provided means for knowing in what
way(s) its view differs from that of the server in this case.
</blockquote>
- <blockquote>Non-normative note:
+ <blockquote><em>Non-normative note:</em>
When the <a>paged resource</a> is an LDP-RS,
the expectation is that all triples untouched by changes to the <a>paged resource</a> have been
given to the client during the traversal; it is possible that some subset of the changed triples, including all or none of them,
@@ -743,8 +798,8 @@
</blockquote>
</section>
- <div class="ldp-issue-pending" id="question-link-relation"><p class="ldp-issue-title">Background and feedback requested on the link relation type used below</p>
- <p>Likely suspects from the <a href="http://www.iana.org/assignments/link-relations/link-relations.xml">IANA link relation registry</a> that the editors examined:</p>
+ <div class="ldp-issue-pending" id="question-link-relation"><p class="ldp-issue-title">Feedback requested on the link relation type used below</p>
+ <p>Background: likely suspects from the <a href="http://www.iana.org/assignments/link-relations/link-relations.xml">IANA link relation registry</a> that the editors examined:</p>
<ul>
<li><p>
<a href="http://tools.ietf.org/html/rfc6596">canonical</a> (see section 3, source has no TOC/anchors) may be
@@ -778,32 +833,38 @@
<section id="ldpr-notify-changes"><h2 class="normal">
<a title="LDP Paging server">LDP Paging servers</a> MUST
- enable a client to detect any change to the <a>paged resource</a> that occurs while the client is retrieving pages.
- In order to do so, servers MUST include a HTTP <code>Link</code> header on all
- HTTP <code>GET</code> responses
- whose context URI identifies the <a>single-page resource</a> being retrieved,
- whose target URI identifies the <a>paged resource</a>,
- whose link relation type is <code>canonical</code>,
+ enable a client to detect any change to the <a>paged resource</a> that occurs while the client is retrieving pages
+ by
+ including a HTTP <code>Link</code> header on all successful
+ 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,
+ target URI identifies the <a>paged resource</a>,
+ link relation type is <code>canonical</code>,
and
- whose link extension parameters include the parameter name <code>etag</code>
- and a corresponding parameter value that changes whenever the ETag [[!HTTP11]]
- of the <a>paged resource</a> would change.
- For example: <code>Link: <http://example.org/customer-relations>; rel='canonical'; etag="v1"</code>
+ link extension parameters include the parameter name <code>etag</code>
+ and a corresponding parameter value identical to the ETag [[!HTTP11]]
+ of the <a>paged resource</a>.
+ For example: <code>Link: <http://example.org/customer-relations>; rel='canonical'; etag="customer-relations-v1"</code>
</h2></section><!-- TODO: change http11 to bis -->
<section id="ldpr-pagingGET-sequences-change"><h2 class="normal">
<a title="LDP Paging server">LDP Paging servers</a> MAY
- add <a title="Single-page resource">single-page resources</a> to a
+ add or remove <a title="Single-page resource">single-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>Non-normative note:
+ <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
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 later. Similar situations arise when the page sequence crosses server boundaries;
+ 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;
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
+ part of the <a title="Paged resource">paged resource's</a> content after the client retrieves <var>M</var>.
</blockquote>
</section>
@@ -869,6 +930,94 @@
</section> <!-- h2 -->
+<section id="ldpp-hints">
+<h2>Paging-related client hints</h2>
+ <p>
+ Clients can provide paging-related hints to influence the server's choices.
+ </p>
+
+<section id="ldpp-hints-summary">
+<h3>Summary</h3>
+
+ <p>This specification introduces new ...
+ <!--
+ parameters on the HTTP <code>Prefer</code> request header's
+ <code>return=representation</code> preference [[!Prefer]], used optionally by clients to
+ supply a hint to help the server form a response that is most appropriate to
+ the client's needs. The LDP-defined parameters suggest the portion(s) of a resource's state that the
+ client application is interested in and, if received, is likely to be
+ processed. LDP Containers with large numbers of associated documents
+ and/or members will have large representations, and many client
+ applications may be interested in processing only a subset of the LDPC's
+ information (for example, only membership triples or only containment triples),
+ resulting in a potentially large savings in server, client,
+ and network processing.
+ </p>
+
+ <p>
+ Non-normative note: LDP server implementers should carefully consider the effects of these
+ preferences on caching, as described in section 2 of [[!Prefer]].
+ </p>
+
+ <p>
+ Non-normative note: [[!Prefer]] recommends that server implementers include a
+ <code>Preference-Applied</code> response header when the client cannot otherwise determine the server's
+ behavior with respect to honoring hints from the response content.
+ <a href="#prefer-examples">Examples</a> illustrates some cases where the header is unnecessary.
+ </p>
+ -->
+
+</section> <!-- Prefer summary -->
+
+<section id="prefer-rules">
+<h3>Specification</h3>
+
+ <section id="ldpp-hints-page-size"><h2 class="normal">
+ The <code>page-size</code> hint defines the client's maximum desired size for a response representation.
+ A client communicates its hint to the server by adding a
+ HTTP preference request header with
+ <code>return=representation</code> that includes a
+ <code>page-size</code> parameter whose value adheres to the following syntax:
+ </h2>
+ <pre><code>
+ page-size-parameter = "page-size" *WSP "=" *WSP DQUOTE *WSP 1*DIGIT 1*WSP 1*units *WSP DQUOTE
+ units = rdf-triples / extension-units
+ rdf-triples = "rdf-triples" ; units = RDF triples
+ extension-units = token ; other units allowed for future extensibility
+ </code></pre>
+ <blockquote>
+ <p>
+ Where <code>WSP</code> is whitespace [[!RFC5234]],
+ <code>DIGIT</code> is an integer between zero and nine [[!RFC5234]],
+ <code>DQUOTE</code> is a double quote [[!RFC5234]],
+ and
+ <code>token</code> is as defined in [[!HTTPBIS-MESSAGING]].
+ The generic preference BNF [[!Prefer]] 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>,
+ and process the request as if the hint was absent.
+ </p>
+ </blockquote>
+ </section>
+
+</section> <!-- Prefer specification -->
+
+<section id="prefer-examples" class="informative">
+<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>
+ would use add this HTTP header on a <code>GET</code> request:
+ <code>Prefer: return=representation; page-size="500 rdf-triples"</code>
+ </p>
+
+
+</section> <!-- Prefer examples -->
+
+
+</section> <!-- Paging hints -->
+
+
</section> <!-- h1 -->
<section id="ldpc">
@@ -905,7 +1054,8 @@
paginated. If the server does not respect ordering when constructing
pages, the client would be forced to retrieve all pages before
sorting the members, which would defeat the purpose of pagination.
- <!-- TODO: Not if the purpose of pagination is rate-limiting, as we've said it is. This is about reducing dup work for client, i.e. optimization. -->
+ <!-- TODO: Not if the purpose of pagination is rate-limiting, as we've said it is.
+ This is about reducing dup work for client, i.e. optimization. -->
In cases where ordering is important, an <a>LDP Paging server</a> exposes all the
members on a page with the proper sort order with relation to all
members on the next and previous pages.
@@ -992,20 +1142,13 @@
<!-- TODO: this^ seems like an odd stmt ... if we are only defining page order for LDPCs, why is this relevant? -->
</h2></section>
- <section id="ldpp-prefer"><h2 class="normal">(From [[!LDP]]) <a title="LDP Paging server">LDP Paging servers</a>
- SHOULD respect all of a client's LDP-defined hints, for example
- <a href="#prefer-parameters">which subsets of LDP-defined state</a>
- the client is interested in processing,
- to influence the set of triples returned in representations of an LDPC,
- particularly for large LDPCs [[!LDP]].
- Non-normative note: the LDPC might be paged; <a title="Paged resource">paged resources</a> provide
- no guarantee that all triples of a given subset, for example
- <a title="Containment triples">containment triples</a>,
- are grouped together on one page or on a sequence of consecutive
- <a title="Single-page resource">pages</a>
- (see <a href="#ldpr-Paging" class="sectionRef"></a>).
+ <section id="ldpc-onsamepage"><h2 class="normal">
+ <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
+ for a <a title="paged resource">paged LDPC</a>.
</h2></section>
- <!-- TODO: Need to rework this^ and possibly relocate it ... does not apply only to LDPCs -->
</section>
@@ -1233,6 +1376,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-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>
<li>2014-05-20 - Spec Sandro's proposal, choose link relation for detection of paged resource changes (JA) </li>
<li>2014-05-19 - Rewrote non-normative parts, cleaned up terminology, ordering undefined when paging non-LDPC LDPRs (JA) </li>
<li>2014-05-15 - Fixed Respec messages by adding "terminology from LDP" section (JA) </li>