Subject: [Simple] XCAP Etags: Text Defining Option 3

From: Jonathan Rosenberg <[email-masked]>
Date: Thu, 24 Jun 2004 06:49:44 -0400

[resend]

Please take a look at my email entitled "XCAP Issue 8: Etag Scope"
before reading this.

The following text is what we would need to put into the doc to support
option 3.

<section title="Managing Etags">

<t>
Etags are associated with resources, with each resource being
identified by an HTTP URI. In XCAP, these resources can correspond to
a document, an XML element within a document, or an XML attribute
within an element. Just as the structure of the document creates
relationships between these resources, it also requires a creation of
relationships amongst the Etags associated with those resources.
</t>

<section title="Scopes">

<t>
These relationships are defined using the notion of a scope. A scope
is defined as a collection of resources, each of which shares the same
value of the Etag. When any one of those resources changes, due to a
PUT against that resource, the server assigns a new Etag for that
resource. It will also assign that same Etag to all of the other
resources within the same scope. A resource can only belong to one
scope.
</t>

<t>
A scope is always structured as the set of elements and attributes
that begin with an element in the document, and include all child
elements and their attributes, up to (and not including) any elements
which are members of another scope. As a result, a scope can be
thought of as either a sub-tree in the document, else as the
difference between a sub-tree and sub-trees underneath it.
</t>

<t>
One scope is said to be the parent of another scope if an element in
the parent scope is a parent of an element in the child
scope. Similarly, one scope is said to be the ancestor of another
scope, if an element in the ancestor scope is an ancestor of an
element in the descendant scope.
</t>

<t>
A scope marker is a rule for determining when a scope starts and
stops. It takes the form of a simple Xpath expression identifying a
sequence of elements, by element name only, starting from the root of
the document. For example, the Xpath expression "/foo/bar/baz" is a
scope marker. This means that, within an instance document, all
elements matching that expression represent the beginning of a scope
(and thus possibly the end of another scope). Each application usage
is responsible for identifying
the scope markers for the documents used by that application usage.
</t>

<t>
The scope markers for an application usage form a tree. Scope marker X
is the parent of scope marker Y if the following are both true:
</t>

<list style="numbers">
<t>The expression for X is a prefix
for the expression for Y,</t>

<t>For all other markers Z which are also prefixes for Y, X is not a
prefix for any of those Z.</t>

</list>

<t>It
is important to understand that this tree of scope markers is static;
its associated with the schema for the document, and doesn't change for
different instance documents.
</t>

<t>
An actual scope, however, is based on an instance document. It is
uniquely identified by its root element and the markers that indicate
the end of the scope. The root element is always an element that
matches the Xpath expression corresponding to one of the scope
markers (say, marker X). The markers identifying the end of the scope
are all of the child markers of marker X.
</t>

<t>
Formally, a resource is associated with a scope if that resource is an
element,
and that element is equal to, or a descendant of, the root element of
the scope, and that element is not within the elements selected by
evaluating the Xpath expressions that define the end of the scope. If
the resource is an attribute, the resource is within the scope if the
element containing that attribute is within the scope. Each document
has a special scope, called the document scope, which contains the
resource associated with the document itself, and includes any
resources not otherwise included in a scope based on the above
definitions. The document scope can be considered as the parent of all
other scopes.
</t>

<t>
Consider the following example. Lets say an application usage defines
a schema for a simple document format. This document format has a
single root element, <a>, which can have any number of child elements,
<b>. Each element <b> can have any number of child elements <c>. Each
element <c> can have any number of child elements <d>, and so on, all
the way to <z>. Every element, <a> through <z>, has a single
attribute, id, which is a unique identifier for that element amongst
its siblings.
</t>

<t>
The application usages defines three scope markers. One marker is
called "root", and its identified by the Xpath expression "/a". The
next marker is called "layer 1" and its identified by the Xpath
expression "/a/b/c". The third marker is called "layer 2" and its
identified by the XPath expression "/a/b/c/d". <xref
target="fig:scope"/> depicts an instance document in graphical
form. The dotted lines surround each of the 8 scopes that exist within the
document. The 9th scope, the document scope, is not shown.
</t>

<figure anchor="fig:scope"><artwork>
<![CDATA[
                    ...............................
                    ............................... Document Scope (1)

                    ...............................
                    .            a                .
                    .                             .
                    .           / \               .
                    .          /   \              .
                    .         /     \             .  (2)
                    .        /       \            .
                    .       /         \           .
                    .      /           \          .
                    .                             .
                    .  b id="1"      b id="2"     .
                    ...............................
                         / \             \
                        /   \             \
                       /     \             \
                      /       \             \
                     /         \             \
                    /           \             \
              ............  ............     .....
           (3). c id="1" .  . c id="2" .(4)  . c . (5)
              ............  ............     .....
                  / \                         / \
                 /   \                       /   \
                /     \                     /     \
               /       \                   /       \
              /         \                 /         \
             /           \               /           \
     ...........  .................  ..........      ..........
     . d id="1".  .   d id="2"    .  .d id="1".      .d id="2".
     .         .  .               .  .        .      ..........
     .    |    .  .      / \      .  .   |    .          (9)
     .    |    .  .     /   \     .  .   |    .
     .    |    .  .    /     \    .  .   |    .
     .    |    .  .   /       \   .  .   |    .
     .    |    .  .  /         \  .  .   |    .           .
     .    |    .  . /           \ .  .   |    .
     .    e    .  .e             e.  .   e    .
     ...........  .................  ..........
         (6)             (7)            (8)
]]></artwork></figure>
</section>

<section title="Server Processing of Etags">

<t>
With this notion of scopes concretely defined, the rules for server
processing of Etags can be defined.
</t>

<t>
When a client modifies a resource, the server updates the etag for
that resource. Call this new etag value "e-new". Furthermore, the
server MUST set the etag for all other resources in the same scope to
"e-new". The server then identifies all resources that belong in
ancestor scopes to the one that was just modified, and it MUST modify
their etags as well, setting them to "e-new". The etags in all other
scopes MUST remain unchanged.
</t>

<t>
The sharing of etags amongst resources is mandatory here in order to
allow the client to maintain a synchronized view with the server on
the etag structure.
</t>

</section>

<section title="Client Processing of Etags">

<t>
Client processing of etags follows the HTTP
specifications. Furthermore, because XCAP imposes additional
requirements on how etags are shared amongst other resources, a client
can implement the same algorithm as the server does, and keep track of
the etags associated with each element, attribute and document stored
on the server. It is useful to keep track of these when the client
wants to perform conditional modifications to various places in the
document. The client and server will remain in synchronization as long as no
errors occur, or no other clients attempt to make a change to the same
document.
</t>

<t>
In the latter case, when the client performs a conditional PUT (using
the If-Match or If-None-Match header fields), it will get a 412 error
response. When that happens, the client cannot assume that any of the
etags it currently possesses for the document in question are still
valid. To re-syncrhonize, it can optionally perform a series of GET
operations, which will return the current etags. The set of GET
operations to perform is purely a local choice. What follows is an
example algorithm which works well.
</t>

<t>
If a PUT against a resource fails, the client looks at its local copy
of the document, and figures out what scope its in. It then performs a
GET against the root element in that scope. The result of this GET
will update that section of the document tree. That will provide
sufficient information (the content of the scope and its etag) for the
client to re-do the request which just failed.
</t>

<t>
To determine the etags and content for the other scopes, the client
can perform the following steps. For each scope that is a sibling of
the scope which was just fetched, the client performs a HEAD operation
against the root element of that scope. The result of this HEAD
operation will indicate the etags for each of those scopes. If the
etag is unchanged from the one cached by the client, it knows that all
elements within this scope, and their children, are unchanged
(including their etags). If the HEAD operation indicates that the etag
has changed, it applies the algorithm described in this paragraph to
that scope as well. In addition to checking the etags of the siblings
of the current scope, the client also performs a HEAD against all
child scopes, in order to obtain their etags. The content of those
scopes is already known, only their etags need to be determined.
</t>

</section>

</section>

-- 
Jonathan D. Rosenberg, Ph.D.                600 Lanidex Plaza
Chief Technology Officer                    Parsippany, NJ 07054-2711
dynamicsoft
[email-masked]                     FAX:   (973) 952-5050
http://www.jdrosen.net                      PHONE: (973) 952-5000
http://www.dynamicsoft.com

_______________________________________________
Simple mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/simple

---

From: [email-masked]
Date: Mon, 28 Jun 2004 11:57:19 +0300

I like this approach. Probably need to indicate that a scope is defined by XPATH expressions pointing to MANDATORY elements.

Thanks,
Hisham

> -----Original Message-----
> From: [email-masked] 
> [mailto:[email-masked]]On Behalf
> Of ext Jonathan Rosenberg
> Sent: 24.June.2004 05:43
> To: Simple WG
> Subject: [Simple] XCAP Etags: Text Defining Option 3
> 
>