Network Working Group M.T. Rose
Internet-Draft Invisible Worlds, Inc.
Expires: September 7, 2000 March 9, 2000
The Blocks Simple Exchange Profile
draft-mrose-blocks-exchange-01
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026 except that the right to
produce derivative works is not granted. (If this document becomes
part of an IETF working group activity, then it will be brought into
full compliance with Section 10 of RFC2026.)
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other documents
at any time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on September 7, 2000.
Copyright Notice
Copyright (C) The Internet Society (2000). All Rights Reserved.
Abstract
Blocks[1] is an architecture for managing metadata. The architecture
supports two models: the Blocks exchange model organizes information
into navigation spaces, whilst the Blocks convergence model allows
for bulk synchronization and knowledge management.
This memo describes the Simple Exchange Profile (SEP) used to
exchange objects, termed blocks, residing in an SEP datastore.
To subscribe to the Blocks discussion list, send e-mail[5]; there is
also a developers' site[6].
Rose Expires September 7, 2000 [Page 1]
Internet-Draft The Blocks Simple Exchange Profile March 2000
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. The SEP Datastore . . . . . . . . . . . . . . . . . . . . . 4
2.1 Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Data types . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3 Entities . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.4 The Top-Level . . . . . . . . . . . . . . . . . . . . . . . 6
3. Profile Identification and Initialization . . . . . . . . . 8
4. Request and Response Messages . . . . . . . . . . . . . . . 10
5. Message Semantics . . . . . . . . . . . . . . . . . . . . . 11
5.1 The Fetch Operation . . . . . . . . . . . . . . . . . . . . 12
5.1.1 The Related and MaxNum Attribute . . . . . . . . . . . . . . 18
5.1.2 The Ordering Element . . . . . . . . . . . . . . . . . . . . 19
5.1.3 The Notification, PrevStamp, and ReqStamp Attributes . . . . 20
5.2 The Notify Operation . . . . . . . . . . . . . . . . . . . . 21
5.3 The Store Operation . . . . . . . . . . . . . . . . . . . . 23
5.4 The Lock Operation . . . . . . . . . . . . . . . . . . . . . 24
5.5 The Release Operation . . . . . . . . . . . . . . . . . . . 25
5.6 Other Operations . . . . . . . . . . . . . . . . . . . . . . 25
6. Simple Exchange Profile Registration . . . . . . . . . . . . 26
7. The SEP datastore DTD . . . . . . . . . . . . . . . . . . . 27
8. The Simple Exchange Profile DTD . . . . . . . . . . . . . . 30
9. Security Considerations . . . . . . . . . . . . . . . . . . 33
References . . . . . . . . . . . . . . . . . . . . . . . . . 34
Author's Address . . . . . . . . . . . . . . . . . . . . . . 34
A. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 35
B. Changes from draft-mrose-blocks-exchange-00 . . . . . . . . 36
Full Copyright Statement . . . . . . . . . . . . . . . . . . 37
Rose Expires September 7, 2000 [Page 2]
Internet-Draft The Blocks Simple Exchange Profile March 2000
1. Introduction
In the Blocks Architecture[1], the Simple Exchange Profile (SEP) is
used to exchange objects, termed blocks, residing in an SEP
datastore.
Rose Expires September 7, 2000 [Page 3]
Internet-Draft The Blocks Simple Exchange Profile March 2000
2. The SEP Datastore
An SEP datastore is a collection of blocks. A block can be viewed
from two perspectives:
semantic: a block is simply metadata about an external object; in
this sense, an SEP datastore is not unlike a shared, distributed
management system for documents;
syntactic: a block is a unit of retrieval; in this sense, an SEP
datastore is a collection of related XML documents[2].
The SEP is concerned with the latter perspective.
A block is a well-formed XML document that satisfies four
constraints:
o the root element of each block must contain a "name" attribute;
o each XML element in the block, termed a property, contains either
character data or subordinate elements, but not both;
o if there is a DTD that describes the validity of the XML
document, then any implicit values must be populated in the
block; and,
o a block may contain no entities other than "&", "<",
"'" and """.
The first constraint allows each block to be unambiguously
identified, whilst the remaining constraints make query optimization
considerably easier to implement.
Blocks are expressed using either:
the generic syntax: in which each property of the block is
explicitly tagged using a "property" element; or,
the specific syntax: in which a syntactic minimization technique is
used to increase readability and reduce size.
Section 7 defines the XML DTD used for the generic syntax of blocks
stored in an SEP datastore. Note that although each block consists
of a collection of structured properties, the unit of retrieval for
the SEP is at the block-level. Applications making use of the SEP
are free to further decompose the blocks exchanged.
Rose Expires September 7, 2000 [Page 4]
Internet-Draft The Blocks Simple Exchange Profile March 2000
2.1 Naming
Naming of blocks in an SEP datastore is hierarchical, with labels
separated by dots, and read left-to-right, e.g.,
net.ipv4.207.67.199.3
doc.rfc.2629
A naming scope refers to the collection of blocks whose names are
contained with a proper subtree, e.g.,
doc.rfc.1006
doc.rfc.2629
are both contained within the naming scope of "doc.rfc".
2.2 Data types
The SEP datastore DTD begins by specifying several data types for
use when defining a block:
NAME: Each block has a unique name. This datatype is used wherever
the syntax of a name is required.
TYPE: Each block consists of one or more properties. This datatype
is used wherever the syntax for a property's type is required.
TYPES: Sometimes it is convenient to refer to the types associated
with a list of properties. This datatype is used for that purpose.
URI: Although the attribute values associated with a property are
textual, it is often useful to treat the character string as a
higher-level construct. This datatype is used wherever the syntax
for a URI[3] is required.
UINT16: This data type is used wherever the syntax for a 16-bit
unsigned integer value is required.
UINT32: This data type is used wherever the syntax for a 32-bit
unsigned integer value is required.
ATEXT: This data type is used wherever the syntax for unstructured
text in an attribute value is required.
CTEXT: This data type is used wherever the syntax for single line,
unstructured text is required.
TEXT: This data type is used wherever the syntax for (potentially
multiline) unstructured text is required.
Rose Expires September 7, 2000 [Page 5]
Internet-Draft The Blocks Simple Exchange Profile March 2000
2.3 Entities
At a minimum, each block must have a "name" attribute in its root
element. In addition, each block may also have three optional
attributes present in its root element:
serial: an integer that is increased each time the block is updated;
ttl: an integer, in seconds, that indicates how long this copy of
the block should be considered authoritative; and,
creator: a URI identifying the process that created or last updated
this block.
Normally, these three attributes are supplied by the SEP datastore
containing the block. The "%block.implied;" entity is used to denote
these three optional attributes.
The "%block.attrs;" entity is used to denote the mandatory "name"
attribute and these three optional attributes.
2.4 The Top-Level
Each block consists of the four attributes defined by
"%block.attrs;", and zero or more "property" elements.
Each "property" element consists of:
o zero or more uniquely named "attribute" elements (each
"attribute" element is simply a key/value pairing); and,
o either:
* one or more "property" elements; or,
* character data consisting of zero or more characters.
Note that the ordering of "property" and "attribute" elements is not
significant.
Rose Expires September 7, 2000 [Page 6]
Internet-Draft The Blocks Simple Exchange Profile March 2000
For example, consider:
<block name="example.1">
<property type="remote.props">
<attribute key="uri"
value="http://example.com/scripts/1.tcl" />
<attribute key="language" value="tcl" />
<property type="title">An Example Script</property>
</property>
</block>
which is a block containing one property, called "remote.props".
That property contains two attributes (one called "uri" and the
other "language") and a subordinate property. The subordinate
property, called "title", contains character data.
This example shows a block expressed using the generic syntax.
Because XML elements may contain uniquely-named attributes, we can
minimize the syntax:
<xscript name="example.1">
<remote.props uri="http://example.com/scripts/1.tcl"
language="tcl">
<title>An Example Script</title>
</remote.props>
</xscript>
The rules to convert from the generic to the specific syntax are
simple:
1. Change the name of the top-level element from "block" to
something else.
2. For each "attribute" element subordinate to any "property"
element: add the corresponding name/value pair as an attribute
to that "property" element and remove the "attribute" element.
3. For each "property" element contained within the block, change
the name of that "property" element to the value of its
corresponding "type" attribute and remove the "type" attribute
from that element.
Rose Expires September 7, 2000 [Page 7]
Internet-Draft The Blocks Simple Exchange Profile March 2000
3. Profile Identification and Initialization
Section 6 contains the registration for this profile.
The SEP is identified as
http://xml.resource.org/profiles/SEP
Refer to [4]'s Section 2.1 for a discussion of the roles that a BXXP
peer may perform, i.e., initiator ("I:") or listener ("L:"), and
client ("C:") or server ("S:").
During channel creation, the corresponding "profile" element in the
BXXP "start" element may contain a "request" element. If channel
creation is successful, then before sending the corresponding "RSP"
message, the BXXP peer processes the "request" element and includes
the resulting "response" element in the "RSP" message, e.g.,
C: REQ . 1 0 546 0
C:
C: <start number='1'>
C: <profile uri='http://xml.resource.org/profiles/SEP'>
C: <request reqno='1'>
C: <fetch>
C: <union><intersect>
C: <compare subtree='doc.rfc.2629'>
C: <path attribute='name'>
C: <element property='rfc' />
C: </path>
C: <value>doc.rfc.2629</value>
C: </compare>
C: </intersect></union>
C: </fetch>
C: </request>
C: </profile>
C: </start>
C: END
S: RSP . 1 284 261 +
S:
S: <profile uri='http://xml.resource.org/profiles/SEP'>
S: <response reqno='1' serial='10' ttl='86400'
S: creator='bxxp://example.com/'>
S: <answers>
S: <rfc name='doc.rfc.2629' ... />
S: </answers>
S: </response>
S: </profile>
S: END
Rose Expires September 7, 2000 [Page 8]
Internet-Draft The Blocks Simple Exchange Profile March 2000
Note that it is possible for the channel to be created, but for the
encapsulated operation to fail, e.g.,
C: REQ . 1 0 531 0
C:
C: <start number='1'>
C: <profile uri='http://xml.resource.org/profiles/SEP'>
C: <request reqno='1'>
C: <fetch>
C: <union><intersect>
C: <compare subtree='doc.rfc.2629'>
C: <path attribute='name'>
C: <element />
C: </path>
C: <value>doc.rfc.2629</value>
C: </compare>
C: </intersect></union>
C: </fetch>
C: </request>
C: </profile>
C: </start>
C: END
S: RSP . 1 284 267 +
S:
S: <profile uri='http://xml.resource.org/profiles/SEP'>
S: <response reqno='1' serial='10' ttl='86400'
S: creator='bxxp://example.com/'>
S: <error code='501'>property attribute
S: missing in <element> element</error>
S: </response>
S: </profile>
S: END
In this case, a positive "RSP" message is returned (as channel
creation succeeded), but the encapsulated response contains an
indication as to why the operation failed.
Rose Expires September 7, 2000 [Page 9]
Internet-Draft The Blocks Simple Exchange Profile March 2000
4. Request and Response Messages
Section 8 defines the messages that are used in the SEP:
o "REQ" messages carry only the "request" element as data;
o positive "RSP" messages carry only the "response" element
(containing an "answers" element and, optionally, an "additional"
element) as data; and,
o negative "RSP" messages carry only the "response" element
(containing an "error" element) as data.
Rose Expires September 7, 2000 [Page 10]
Internet-Draft The Blocks Simple Exchange Profile March 2000
5. Message Semantics
The "request" element contains a "reqno" attribute and one of: a
"fetch" element, a "notify" element, a "store" element, a "lock"
element, or, a "release" element.
The "reqno" attribute (an integer in the range 0..4294967295) is
used to correlate "request" elements sent by a BXXP peer acting in
the client role with the "response" elements sent by a BXXP peer
acting in the server role.
Rose Expires September 7, 2000 [Page 11]
Internet-Draft The Blocks Simple Exchange Profile March 2000
5.1 The Fetch Operation
The "fetch" element contains four attributes, a "union" element,
and, optionally, an "ordering" element:
o the "related" attribute, if present, contains a space-separated
list of property names that cause similar blocks to be returned
in the "additional" element of the response (c.f., Section 5.1.1);
o the "offset" attribute, if present, contains a non-negative
integer (in the range 0..32767) indicates the starting position
for the blocks to be returned;
o the "maxNum" attribute, if present, contains a positive integer
(in the range 1..32767) indicates the maximum number of blocks
allowed to be returned;
o the "notification" attribute, if present, is either "true" or
"false" (the default) to indicate whether the BXXP peer acting in
the server role should periodically check for changes to the
blocks returned in the "answers" element of the response (c.f.,
Section 5.1.3);
o the "union" element defines the set-union of one or more
"intersect" elements, each of which define the set-intersection
of one or more "union" or "compare" elements, each of latter
describing an containment/value assertion; and,
o the "ordering" element, if present, defines the order in which
matches are returned (c.f., Section 5.1.2).
Each "compare" element contains three attributes, a "path" element,
and a "value" element:
o the "subtree" attribute identifies the naming scope for the
comparison;
o the "operator" attribute, if present, identifies the comparison
to be made between the "path" element and the "value" element,
one of: "eq" (equals, the default), "ne" (not equals),
"contains", or "excludes";
o the "caseSensitive" attribute, if present, is either "true" (the
default) or "false" to indicate whether the comparison should
consider textual case significant;
o the "approximate" attribute, if present, is either "true" or
"false" (the default) to indicate whether the comparison should
be approximate (e.g., through the use of stemming);
Rose Expires September 7, 2000 [Page 12]
Internet-Draft The Blocks Simple Exchange Profile March 2000
o the "path" element identifies a partial containment hierarchy for
the comparison; and,
o the "value" element contains the text to compare against.
If the fetch operation is successful, then a "response" element
containing an "answers" element, and optionally an "additional"
element is returned as data in a positive "RSP" message; otherwise,
a "response" element containing a BXXP "error" element (c.f., [4]'s
Section 2.3.1.3) is returned as data in a negative "RSP" message.
If a "response" element is returned, then the order of blocks in the
"answers" element are ordered from "most relevant" to "least
relevant" (c.f., Section 5.1.2). Accordingly, if all blocks
satisfying the set-union are enumerated as a list starting at
position 0, then the block at the position corresponding to the
"offset" attribute is the first block returned in the "answers"
element.
If a "response" element is returned, then the optional "actualNum"
attribute may be present in the "answers" element. This attribute
indicates the total number of matches for the corresponding "fetch"
operation. If absent, the value of this attribute defaults to the
number of blocks present in the "answers" element.
At the core of the fetch operation is the notion of a
containment/value assertion. Each assertion identifies a comparison
between a partial containment hierarchy and a textual value.
Several examples serve to illustrate these relationships.
Rose Expires September 7, 2000 [Page 13]
Internet-Draft The Blocks Simple Exchange Profile March 2000
First, consider:
C: REQ . 1 546 345 1
C:
C: <request reqno='3'><fetch>
C: <union>
C: <intersect>
C: <compare subtree='doc.rfc' operator='contains'
C: caseSensitive='false'>
C: <path><element property='email' /></path>
C: <value>mrose@</value>
C: </compare>
C: </intersect>
C: </union>
C: </fetch></request>
C: END
which looks for blocks satisfying several criteria: first, the block
is named under "doc.rfc"; second, the block has at least one
property called "email"; and, third, any of those properties
contains the string "mrose@" somewhere within it, according to a
case-insensitive comparison. Note that in this example, the "email"
property may occur at any level of nesting within a block.
Second, a similar example:
C: REQ . 2 891 266 1
C:
C: <request reqno='5'><fetch>
C: <union>
C: <intersect>
C: <compare subtree='doc.rfc'>
C: <path attribute='surname' />
C: <value>Rose</value>
C: </compare>
C: </intersect>
C: </union>
C: </fetch></request>
C: END
which looks for blocks in the same subtree, but is concerned only
with attribute, not property, values. That is, if any property with
a block has attribute called "surname" and the value of that
attribute precisely matches the string "Rose", then this assertion
succeeds. (Recall that the default value for "operator" is "eq" and
the default value for "caseSensitive" is "true".)
Rose Expires September 7, 2000 [Page 14]
Internet-Draft The Blocks Simple Exchange Profile March 2000
Of course, if we wanted to limit containment of the attribute:
C: REQ . 3 1157 344 1
C:
C: <request reqno='7'><fetch>
C: <union>
C: <intersect>
C: <compare subtree='doc.rfc'>
C: <path attribute='surname'>
C: <element property='doc.author' />
C: </path>
C: <value>Rose</value>
C: </compare>
C: </intersect>
C: </union>
C: </fetch></request>
C: END
which looks for blocks in the same subtree, but performs comparisons
only on attributes called "surname" within a "doc.author" property.
In addition, if we wanted to further contain the attribute's
property:
C: REQ . 4 1501 501 1
C:
C: <request reqno='11'><fetch>
C: <union>
C: <intersect>
C: <compare subtree='doc.rfc'>
C: <path attribute='surname'>
C: <element property='rfc' />
C: <element property='doc.props' />
C: <element property='doc.front' />
C: <element property='doc.author' />
C: </path>
C: <value>Rose</value>
C: </compare>
C: </intersect>
C: </union>
C: </fetch></request>
C: END
which looks for "doc.author" properties contained within a
"doc.front" property contained within a "doc.props" property
contained within a "rfc" property before looking at the "surname"
attribute. Note however, that there is no concept of "rooting" in a
containment hierarchy, e.g., in this example, the "rfc" property
needn't be the top-level property of the block (i.e., the root
Rose Expires September 7, 2000 [Page 15]
Internet-Draft The Blocks Simple Exchange Profile March 2000
element of the corresponding XML document).
Of course, an empty containment hierarchy is also possible, e.g.,
C: REQ . 5 2002 247 1
C:
C: <request reqno='13'><fetch>
C: <union>
C: <intersect>
C: <compare subtree='doc.rfc'>
C: <path />
C: <value>Rose</value>
C: </compare>
C: </intersect>
C: </union>
C: </fetch></request>
C: END
which looks for the string "Rose" in any property. Similarly, to
look for the string "Rose" in any attribute value, the containment
"<path attribute='*' />" is used.
Note that in all the preceding examples, both the "union" and
"intersect" elements had only one immediate subordinate, rendering
each as the identity function. However, the presence of the elements
is always required, regardless of whether their functionality is
needed. To set-intersect the results of multiple assertions, the
"intersect" element is given multiple subordinates, e.g.,
C: REQ . 6 2249 494 1
C:
C: <request reqno='17'><fetch>
C: <union>
C: <intersect>
C: <compare subtree='doc.rfc' operator='contains'
C: caseSensitive='false'>
C: <path><element property='email' /></path>
C: <value>mrose@</value>
C: </compare>
C: <compare subtree='doc.rfc'>
C: <path attribute='surname' />
C: <value>Rose</value>
C: </compare>
C: </intersect>
C: </union>
C: </fetch></request>
C: END
which evaluates two assertions and returns only those blocks
Rose Expires September 7, 2000 [Page 16]
Internet-Draft The Blocks Simple Exchange Profile March 2000
satisfying both.
Similarly, to set-union the results of multiple intersections, the
"union" element is given multiple subordinates, e.g.,
C: REQ . 7 2743 537 1
C:
C: <request reqno='19'><fetch>
C: <union>
C: <intersect>
C: <compare subtree='doc.rfc' operator='contains'
C: caseSensitive='false'>
C: <path><element property='email' /></path>
C: <value>mrose@</value>
C: </compare>
C: </intersect>
C: <intersect>
C: <compare subtree='doc.rfc'>
C: <path attribute='surname' />
C: <value>Rose</value>
C: </compare>
C: </intersect>
C: </union>
C: </fetch></request>
C: END
which evaluates two assertions and returns blocks that satisfy
either. Of course, recursion is permissible between "union" and
"intersect" elements, owing to their defintion.
Rose Expires September 7, 2000 [Page 17]
Internet-Draft The Blocks Simple Exchange Profile March 2000
5.1.1 The Related and MaxNum Attribute
Blocks satisfying the constraints of the "union" element are
returned in the "response" element's "answers" element. These are
termed satisfying blocks.
The "related" attribute, if present, causes blocks similar to the
satisfying blocks to be returned in the "response" element's
"additional" element. These are termed similar blocks.
A similar block is one that has the same value for any of related
properties as any of the satisfying blocks. Note that when
determining if a block is similar, the BXXP peer acting in the
server role consults its entire SEP datastore -- a similar block may
belong to an entirely different naming scope than any corresponding
satisfying block.
Regardless, note that the "maxNum" attribute limits the actual
number of blocks returned. As many satisfying blocks as possible
must be returned; if the "maxNum" limit is not yet reached, then as
many similar blocks within the limit may be returned. No additional
constraints are placed on implementations if the value of the
"maxNum" attribute is less than the number of satisfying and similar
blocks.
Rose Expires September 7, 2000 [Page 18]
Internet-Draft The Blocks Simple Exchange Profile March 2000
5.1.2 The Ordering Element
If the "ordering" element is present in the "fetch" element, then
this provides guidelines as to how blocks should be ordered in the
"answers" element.
The "ordering" element contains one or more "path" elements, ordered
as sort keys (i.e., the first "path" element is the primary sort
key, the second "path" element, if any, is the secondary sort key,
and so on). Each "path" element contains an "order" attribute
indicating whether relevance is in ascending (the default) or
descending order.
For example, to look for blocks containing a "surname" attribute of
"Rose", and then order the blocks according to the value of their
"doc.title" element:
C: REQ . 8 3280 341 1
C:
C: <request reqno='21'><fetch>
C: <union>
C: <intersect>
C: <compare subtree='doc.rfc'>
C: <path attribute='surname' />
C: <value>Rose</value>
C: </compare>
C: </intersect>
C: </union>
C: <ordering>
C: <path><element property='doc.title' /></path>
C: </ordering>
C: </fetch></request>
C: END
Rose Expires September 7, 2000 [Page 19]
Internet-Draft The Blocks Simple Exchange Profile March 2000
5.1.3 The Notification, PrevStamp, and ReqStamp Attributes
If a fetch operation is successful and the "notification" attribute
is "true", then it is referred to as a persistent fetch operation.
When performing the fetch operation, if the "notification" attribute
is true, then the "prevStamp" attribute is also consulted. If empty,
this indicates that the fetch operation is performed against the
entire SEP datastore; otherwise, the value is identical to a
previously returned value of the "reqStamp" in an "answers" element.
In this latter case, the fetch operation returns an empty "answer"
element with a "reqStamp" attribute value equal to the "prevStamp"
attribute value, and all corresponding notify operations (Section
5.2) for this persistent fetch will contain information about
changes that occurred after the "reqStamp" attribute value.
The fetch operation persists until either:
o a corresponding release operation (Section 5.5) is successful;
o a corresponding notify operation (Section 5.2) fails;
o the BXXP session is released; or,
o the underlying transport service indicates that the connection
has been reset.
In the interim:
1. The BXXP peer acting in the client role may not use the value of
"reqno" in other requests.
2. The BXXP peer acting in the server role periodically checks for
changes to the blocks returned in the "answers" element in the
original response. If so, a notify operation is generated.
Every "answers" element generated for a persistent fetch (contained
in either a "response" or "notify" element) has a non-empty
"reqStamp" attribute. This provides a mechanism to restart a
persistent fetch operation after a connection loss: the BXXP peer
acting in the client role records the most recent "reqStamp"
attribute value whenever it sees an "answer" element corresponding
to a persistent fetch. If the connection is lost (or the SEP channel
is closed), then after re-establishing the connection and starting
an SEP channel, the BXXP peer acting in the client role initiates a
new persistent fetch by setting the "notification" attribute to true
and the "prevStamp" attribute to the most recent "reqStamp"
attribute value.
Rose Expires September 7, 2000 [Page 20]
Internet-Draft The Blocks Simple Exchange Profile March 2000
5.2 The Notify Operation
For each persistent fetch operation known to a BXXP acting in the
server role, a periodic check is made for changes to the blocks
returned in the "answers" element in the original response. If any
of the blocks are changed or deleted, or, if new blocks are created
that qualify as satisfying blocks for the original request, then a
notify operation is sent.
The "notify" element consists of a "prevno" attribute, an "answers"
element, and, optionally, either or both of a "additional" element
and a "deletions" element:
o the "prevno" attribute (an integer in the range 0..4294967295) is
used to correlate this operation with the corresponding
persistent fetch operation;
o the "answers" element contains both newly-changed blocks
previously returned in an "answers" element for this persistent
fetch operation, along with newly-created blocks that qualify as
satisfying blocks for the original request;
o the "additional" element, if present, contains similar blocks to
the newly-created blocks, if any, in the "answers" element of
this operation; and,
o the "deletions" element, if present, contains newly-deleted
blocks previously returned in an "answers" element for this
persistent fetch operation.
Note that when constructing the "deletions" element, the blocks
generic syntax may be used, e.g.,
<notify prevno='45'>
<answers reqStamp='3' ... />
<deletions>
<block name="doc.rfc.2629" />
</deletions>
</notify>
This strategy is useful if a server knows that a block was deleted,
but the actual block is no longer available.
If the notify operation is successful, then a "response" element
containing an empty "answers" element is returned as data in a
positive "RSP" message; otherwise, a "response" element containing a
BXXP "error" element (c.f., [4]'s Section 2.3.1.3) is returned as
data in a negative "RSP" message. In the latter case, the fetch
operation is no longer considered persistent.
Rose Expires September 7, 2000 [Page 21]
Internet-Draft The Blocks Simple Exchange Profile March 2000
Note that the BXXP peers switch server and client roles when going
from a fetch operation to a notify operation, e.g.,
I: REQ . 1 3280 88 1
I:
I: <request reqno='23'><fetch notification='true'>
I: <union ... />
I: </fetch></request>
I: END
L: RSP . 1 284 57 +
L:
L: <response reqno='23'>
L: <answers reqStamp='1' ... />
L: </response>
... time elapses ...
L: REQ . 1 341 83 1
L:
L: <request reqno='1'><notify prevno='23'>
L: <answers reqStamp='2' ... />
L: </notify></request>
L: END
I: RSP . 1 3368 52 +
I:
I: <response reqno='1'>
I: <answers />
I: </response>
I: END
Rose Expires September 7, 2000 [Page 22]
Internet-Draft The Blocks Simple Exchange Profile March 2000
5.3 The Store Operation
The store operation contains one attribute and one or more blocks to
store.
o the "action" attribute, if present, is one of:
create: verifies that the blocks do not exist in the SEP
datastore before creating them;
write: creates or overwrites the blocks in the SEP datastore (the
default);
update: verifies that the blocks exist in the SEP datastore
before overwriting them; or,
delete: removes the blocks from the SEP datastore.
In order to provide coordination between independent BXXP peers
acting in the client role, a lock operation (Section 5.4) must be
successfully performed before the store operation.
If the store operation is successful, then a "response" element
containing an empty "answers" element is returned as data in a
positive "RSP" message; otherwise, a "response" element containing a
BXXP "error" element (c.f., [4]'s Section 2.3.1.3) is returned as
data in a negative "RSP" message.
Rose Expires September 7, 2000 [Page 23]
Internet-Draft The Blocks Simple Exchange Profile March 2000
5.4 The Lock Operation
The lock operation contains one attribute:
o the "subtree" attribute that identifies the naming scope to lock.
If a lock operation is successful, then it is referred to as a
persistent lock operation. It remains so until either:
o a corresponding release operation (Section 5.5) is successful;
o the BXXP session is released;
o the underlying transport service indicates that the connection
has been reset; or,
o an implementation-specific inactivity timer expires in the BXXP
peer acting in the server role.
In the last three cases, the BXXP peer acting in the server role
should discard any journaled store operations for this channel.
(Further, in the final case, the BXXP peer acting in the server role
should also release the BXXP session with prejudice.)
In the interim:
1. No other connection or channel may successfully lock within the
subtree.
2. No other connection or channel may successfully store within the
subtree.
3. Any store operations on this channel are journaled until a
subsequent release operation.
If the lock operation is successful, then a "response" element
containing an empty "answers" element is returned as data in a
positive "RSP" message; otherwise, a "response" element containing a
BXXP "error" element (c.f., [4]'s Section 2.3.1.3) is returned as
data in a negative "RSP" message.
Rose Expires September 7, 2000 [Page 24]
Internet-Draft The Blocks Simple Exchange Profile March 2000
5.5 The Release Operation
The "release" element contains two attributes:
o the "prevno" attribute (an integer in the range 0..4294967295) is
used to correlate this operation with a persistent fetch (Section
5.1.3) or lock (Section 5.4) operation; and,
o the "action" attribute, if present, is either "commit" (the
default) or "rollback".
If the previous operation refers to a persistent lock operation,
then the "action" attribute indicates whether the BXXP peer acting
in the server role should either:
commit: perform any journaled store operations for this channel; or,
rollback: discard any journaled store operations for this channel.
Regardless, upon successful completion of the release operation, the
corresponding fetch or lock operation is completed and no longer
considered persistent.
If the release operation is successful, then a "response" element
containing an empty "answers" element is returned as data in a
positive "RSP" message; otherwise, a "response" element containing a
BXXP "error" element (c.f., [4]'s Section 2.3.1.3) is returned as
data in a negative "RSP" message.
5.6 Other Operations
If the BXXP peer receives a "request" element containing any other
element, a "response" element containing a BXXP "error" element
(c.f., [4]'s Section 2.3.1.3) is returned as data in a negative
"RSP" message.
Rose Expires September 7, 2000 [Page 25]
Internet-Draft The Blocks Simple Exchange Profile March 2000
6. Simple Exchange Profile Registration
Profile Identification: http://xml.resource.org/profiles/SEP
Messages in Profile Initialization: request
Messages in "REQ" frames: request
Messages in positive "RSP" frames: response
Messages in negative "RSP" frames: error
Message Syntax: c.f., Section 8
Message Semantics: c.f., Section 5
Rose Expires September 7, 2000 [Page 26]
Internet-Draft The Blocks Simple Exchange Profile March 2000
7. The SEP datastore DTD
<!--
DTD for SEP datastore, as of 2000-03-03
Copyright 1999, 2000 Invisible Worlds, Inc.
This document is a DTD and is in full conformance with all
provisions of Section 10 of RFC2026 except that the right to
produce derivative works is not granted.
Refer to this DTD as:
<!ENTITY % DATASTORE PUBLIC "-//Blocks//DTD SEP DATASTORE//EN"
"http://xml.resource.org/blocks/datastore.dtd">
%DATASTORE;
-->
<!--
Contents
Data types
Entities
Top-Level
-->
Rose Expires September 7, 2000 [Page 27]
Internet-Draft The Blocks Simple Exchange Profile March 2000
<!--
Data types:
entity syntax/reference example
====== ================ =======
the name of a block
NAME ([A-Za-z0-9][-_A-Za-z0-9]*)
("." ([A-Za-z0-9][-_A-Za-z0-9]*))*
net.ipv4.207.67.199.3
the name(s) of a property
TYPE [A-Za-z_][A-Za-z0-9_.]*
ip.props
TYPES TYPE *(" " TYPE) ip.props tcp.props
pointers to resources
URI c.f., [RFC-2396] http://invisible.net/
integers
UINT16 0..32767 42
UINT32 0..4294967295 17
unstructured text
ATEXT "hello"
CTEXT "Blocks server good to go"
multiline character data
TEXT
-->
<!ENTITY % NAME "NMTOKEN">
<!ENTITY % TYPE "NMTOKEN">
<!ENTITY % TYPES "NMTOKENS">
<!ENTITY % URI "CDATA">
<!ENTITY % UINT32 "CDATA">
<!ENTITY % UINT16 "CDATA">
<!ENTITY % ATEXT "CDATA">
<!ENTITY % CTEXT "#PCDATA">
<!ENTITY % TEXT "#PCDATA">
Rose Expires September 7, 2000 [Page 28]
Internet-Draft The Blocks Simple Exchange Profile March 2000
<!--
Entities
entity use
====== ===
block.attrs all blocks have these attributes
block.implied the subset of block.attrs that is usually
supplied in a containing element, e.g., SEP's
response element
-->
<!ENTITY % block.implied "
serial %UINT32; #IMPLIED
ttl %UINT32; #IMPLIED
creator %URI; #IMPLIED">
<!ENTITY % block.attrs "
name %NAME; #REQUIRED
%block.implied;">
<!--
Top-Level
-->
<!ELEMENT block (property*)>
<!ATTLIST block
%block.attrs;>
<!ELEMENT attribute EMPTY>
<!ATTLIST attribute
key %ATEXT; #REQUIRED
value %ATEXT; #REQUIRED>
<!--
The content model defined below is a bit too general for us. The
preferred content model is:
(attribute*,(%TEXT;*|property*))
-->
<!ELEMENT property (%TEXT;|attribute|property)*>
<!ATTLIST property
type %TYPE; #REQUIRED>
Rose Expires September 7, 2000 [Page 29]
Internet-Draft The Blocks Simple Exchange Profile March 2000
8. The Simple Exchange Profile DTD
<!--
DTD for Simple Exchange Profile, as of 2000-03-03
Copyright 1999, 2000 Invisible Worlds, Inc.
This document is a DTD and is in full conformance with all
provisions of Section 10 of RFC2026 except that the right to
produce derivative works is not granted.
Refer to this DTD as:
<!ENTITY % SEP PUBLIC "-//Blocks//DTD SEP//EN"
"http://xml.resource.org/profiles/SEP/sep.dtd">
%SEP;
-->
<!--
Contents
DTD inclusion
SEP messages
The fetch operation
The notify operation
The store operation
The lock operation
The release operation
-->
<!--
DTD inclusion
Caller should already have included the SEP datastore DTD.
Caller should already have included the BXXP Channel Management
DTD.
Caller should already have defined %BLOCK; and %block.implied;
-->
Rose Expires September 7, 2000 [Page 30]
Internet-Draft The Blocks Simple Exchange Profile March 2000
<!--
SEP messages
role REQ RSP
====== === ===
I or L request response
+: (answers, additional?)
-: error
-->
<!ELEMENT request (fetch|notify|store|lock|release)>
<!ATTLIST request
reqno %UINT32; #REQUIRED>
<!ELEMENT response ((answers,additional?)|error)>
<!ATTLIST response
reqno %UINT32; #REQUIRED
%block.implied;>
<!ELEMENT answers (%BLOCK;)*>
<!ATTLIST answers
actualNum %UINT16; #IMPLIED
reqStamp %ATEXT; "">
<!ELEMENT additional (%BLOCK;)+>
<!ELEMENT fetch (union,ordering?)>
<!ATTLIST fetch
related %TYPES; #IMPLIED
offset %UINT16; "0"
maxNum %UINT16; #IMPLIED
notification
(true|false) "false"
prevStamp %ATEXT; "">
<!ELEMENT union (intersect+)>
<!ELEMENT intersect ((union|compare)+)>
<!-- order attribute of path element is ignored -->
<!ELEMENT compare (path, value)>
<!ATTLIST compare
subtree %NAME; #REQUIRED
operator (eq|ne|contains|excludes)
"eq"
caseSensitive
(true|false) "true"
approximate (true|false) "false">
<!ELEMENT ordering (path+)>
Rose Expires September 7, 2000 [Page 31]
Internet-Draft The Blocks Simple Exchange Profile March 2000
<!ELEMENT path (element*)>
<!ATTLIST path
attribute %ATEXT; ""
order (ascending|descending)
"ascending">
<!ELEMENT element EMPTY>
<!ATTLIST element
property %TYPE; #REQUIRED>
<!ELEMENT value (%TEXT;)>
<!ELEMENT notify ((answers,additional?,deletions?))>
<!ATTLIST notify
prevno %UINT32; #REQUIRED>
<!ELEMENT deletions (%BLOCK;)+>
<!ELEMENT store (%BLOCK;)+>
<!ATTLIST store
action (create|write|update|delete)
"write">
<!ELEMENT lock EMPTY>
<!ATTLIST lock
subtree %NAME; #REQUIRED>
<!ELEMENT release EMPTY>
<!ATTLIST release
prevno %UINT32; #REQUIRED
action (commit|rollback) "commit">
Rose Expires September 7, 2000 [Page 32]
Internet-Draft The Blocks Simple Exchange Profile March 2000
9. Security Considerations
The SEP is a profile of BXXP. In BXXP, transport security, user
authentication, and data exchange are entirely orthogonal. Refer to
[4]'s Section 8 for a discussion of these issues.
Rose Expires September 7, 2000 [Page 33]
Internet-Draft The Blocks Simple Exchange Profile March 2000
References
[1] Rose, M.T. and C. Malamud, "Blocks: Architectural Precepts",
draft-mrose-blocks-architecture-01 (work in progress), March
2000.
[2] World Wide Web Consortium, "Extensible Markup Language (XML)
1.0", W3C XML, February 1998,
<http://www.w3.org/TR/1998/REC-xml-19980210>.
[3] Berners-Lee, T., Fielding, R.T. and L. Masinter, "Uniform
Resource Identifiers (URI): Generic Syntax", RFC 2396, August
1998.
[4] Rose, M.T., "The Blocks eXtensible eXchange Protocol",
draft-mrose-blocks-protocol-01 (work in progress), March 2000.
[5] mailto:blocks-request@invisible.net
[6] http://mappa.mundi.net/
[11] mailto:dnew@invisible.net
Author's Address
Marshall T. Rose
Invisible Worlds, Inc.
1179 North McDowell Boulevard
Petaluma, CA 94954-6559
US
Phone: +1 707 789 3700
EMail: mrose@invisible.net
URI: http://invisible.net/
Rose Expires September 7, 2000 [Page 34]
Internet-Draft The Blocks Simple Exchange Profile March 2000
Appendix A. Acknowledgements
The author gratefully acknowledges the contributions of: Darren
New[11].
Rose Expires September 7, 2000 [Page 35]
Internet-Draft The Blocks Simple Exchange Profile March 2000
Appendix B. Changes from draft-mrose-blocks-exchange-00
o The profile is now identified as
http://xml.resource.org/profiles/SEP
o In Section 5.1.2, an XML nesting error was corrected.
o In Section 5.1.3, the behavior of connection re-establishment was
clarified.
o In Section 8, the correct URI is used to reflect the location of
the DTD.
Rose Expires September 7, 2000 [Page 36]
Internet-Draft The Blocks Simple Exchange Profile March 2000
Full Copyright Statement
Copyright (C) The Internet Society (2000). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph
are included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Invisible Worlds expressly disclaims any and all warranties
regarding this contribution including any warranty that (a) this
contribution does not violate the rights of others, (b) the owners,
if any, of other rights in this contribution have been informed of
the rights and permissions granted to IETF herein, and (c) any
required authorizations from such owners have been obtained. This
document and the information contained herein is provided on an "AS
IS" basis and INVISIBLE WORLDS DISCLAIMS ALL WARRANTIES, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE
OFTHE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
IN NO EVENT WILL INVISIBLE WORLDS BE LIABLE TO ANY OTHER PARTY
INCLUDING THE IETF AND ITS MEMBERS FOR THE COST OF PROCURING
SUBSTITUTE GOODS OR SERVICES, LOST PROFITS, LOSS OF USE, LOSS OF
DATA, OR ANY INCIDENTAL, CONSEQUENTIAL, INDIRECT, OR SPECIAL DAMAGES
WHETHER UNDER CONTRACT, TORT, WARRANTY, OR OTHERWISE, ARISING IN ANY
WAY OUT OF THIS OR ANY OTHER AGREEMENT RELATING TO THIS DOCUMENT,
WHETHER OR NOT SUCH PARTY HAD ADVANCE NOTICE OF THE POSSIBILITY OF
SUCH DAMAGES.
Rose Expires September 7, 2000 [Page 37]
Internet-Draft The Blocks Simple Exchange Profile March 2000
Acknowledgement
Funding for the RFC editor function is currently provided by the
Internet Society.
Rose Expires September 7, 2000 [Page 38]