This document is a submission to the World Wide Web Consortium (see Submission Request, W3C Staff Comment). It is intended for review and comment by W3C members and other interested parties.
This document is a NOTE made available by the W3 Consortium for discussion only. This indicates no endorsement of its content, nor that the Consortium has, is, or will be allocating any resources to the issues addressed by this NOTE.
This document describes the Information and Content Exchange protocol for use by content syndicators and their subscribers. The ICE protocol defines the roles and responsibilities of syndicators and subscribers, defines the format and method of content exchange, and provides support for management and control of syndication relationships. We expect ICE to be useful in automating content exchange and reuse, both in traditional publishing contexts and in business-to-business relationships.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
In the HTML version of this specification, those key words are CAPITALIZED BOLD. Capitalization is significant; uncapitalized uses of the key words are intended to be interpreted in their normal, informal, English language way. Bold face is not significant, and is used to aid comprehension, but the bold font is non-normative and the absence of a bold font MUST NOT be given any semantic interpretation.
Reusing and redistributing information and content from one web site to another is an ad hoc and expensive process. The expense derives from two different types of problem:
Successful content syndication requires solving both halves of this puzzle. Fortunately, industry specific efforts already exist for solving the vocabulary problems. For example, Ontology.org (http://www.ontology.org) is an organization devoted to fostering development of industry specific XML DTDs. Other examples of this type of effort include HL7 for the health care industry, or recent W3C XML efforts for mathematics. Although many industries have yet to establish efforts in this area, more will do so as XML and the Web continue to create opportunities for economic gain via on-line applications.
ICE completes the picture by providing the solution for the other half of the puzzle. Specifically, ICE manages and automates establishment of syndication relationships, data transfer, and results analysis. When combined with an industry-specific vocabulary, ICE provides a complete solution for syndicating any type of information between information providers and their subscribers.
The authoring group defined a number of design goals for ICE based on requirements analysis and much thought and discussion. Some of the most important design goals for ICE are included here for reference:
Note: These goals are non-normative. They are included here for historical purposes only.
Many other standards describe how to transmit data of one form or another between systems. This section briefly discusses some of these protocols and describes their relationship to ICE.
ICE is an application of the Extensible Markup Language (XML). Basic concepts in ICE are represented using the element/attribute markup model of XML. Note, however, that ICE is a protocol, not just a DTD, and so in that way differs fundamentally from other pure-document applications of XML such as MathML (mathematical formula markup language), PGML (Precision Graphics Markup Language), etc.
Channel Definition Format (CDF) specifies the operation of push channels. Like ICE, it defines a mechanism for scheduling delivery of encapsulated content. ICE builds on some of the concepts of CDF, such as delivery schedules. Note that ICE goes well beyond what CDF can do; CDF has no notion of explicit subscription relationship management, asset management, reliable sequenced package delivery, asset repair operations, constraints, etc.
We expect ICE will be useful for server-to-server syndication to distribute and/or aggregate content to/from various push servers, whereas CDF is useful for server-to-browser applications.
The Open Software Description (OSD) Format automates distribution of software packages. OSD focuses on concepts such as package dependencies, OS requirements, environmental requirements (such as: how much disk space does a software package require), etc. ICE has very little overlap or relationship to OSD.
We expect ICE to be useful for server-to-server syndication to distribute and/or aggregate content to/from one OSD server to another, whereas OSD continues to be useful for its intended domain of distributing and installing software directly to target desktop and workgroup server machines.
Quoting from [P3P-arch]: The Platform for Privacy Preferences (P3P) protocol addresses the twin goals of meeting the data privacy expectations of consumers on the Web while assuring that the medium remains available and productive for electronic commerce. When ICE is being used to share user profile information from one business to another, it is the responsibility of the applications on both sides of such a relationship to enforce the appropriate privacy policies in accord with the principles described in P3P, as well as in accord with any governing laws. ICE is merely the transport mechanism for those profiles and is not involved in the enforcement of user profile privacy principles.
Quoting from [WebDAV]: WebDAV (Distributed Authoring and Versioning) specifies a set of methods, headers, and content-types ancillary to HTTP/1.1 for the management of resource properties, creation and management of resource collections, namespace manipulation, and resource locking (collision avoidance).
WebDAV addresses a collaborative authoring environment and has very little overlap with ICE.
Quoting from [NOTE-DRP]: The HTTP Distribution and Replication Protocol was designed to efficiently replicate a hierarchical set of files to a large number of clients. No assumption is made about the content or type of the files; they are simply files in some hierarchical organization.
DRP focuses on the differential-update of information organized as a hierarchy of files. As such, it could be used to solve a portion of the data transfer problems addressed by ICE, but only for those content syndication situations that are file-centric. ICE solves a more general problem of asset exchange, where assets may not necessarily be files in a hierarchy. ICE also addresses explicit subscription relationship management, asset management, reliable sequenced package delivery, asset repair operations, constraints, etc. whereas DRP addresses none of those.
These definitions are used throughout this document. Readers will most likely not fully understand these definitions without also reading through the specification.
The Authoring Group went through several major topics of discussion while designing ICE, and some of the decisions reached are of sufficient interest to warrant recording the thought processes that led to them.
The ICE Authoring Group searched for an existing schema and constraint definition language that would meet the ICE requirements. As an example of these requirements, consider banner ads. A desirable constraint mechanism could represent the rule "banner ads are GIFs and are no larger than X pixels by Y pixels." None of the existing or planned schema and constraint languages can express the "ad banner" constraint.
The ICE Authoring Group felt strongly that:
Therefore, ICE V1.0 defines a constraint reference and transport mechanism, and does not define an actual constraint language. Specifically, this means:
This approach allows constraints to be specified and managed by ICE, without regard to a specific constraint implementation. Indeed, the Authoring Group concluded that having the constraint mechanism defined separately from the transport protocol had additional value in that it provided a natural and flexible way to accommodate a variety of constraint languages, which might develop to address industry-specific requirements.
The Authoring Group intends to go one step further and define an interim constraint language, tentatively named ICE-Constraints. The ICE-Constraints language will suffice to meet the basic requirements of content syndicators and their subscribers, while allowing time for general and more complete solutions to develop. We expect the ICE-Constraints language will also be a useful source of requirements for future general-purpose constraint language designers.
Note that a conforming ICE implementation need not implement any constraint processing at all; like DTD validation and a number of other ICE features, constraint processing is entirely a quality of implementation issue. Its presence or absence has no effect whatsoever on the interoperability of two ICE implementations, because nothing in the protocol state machine flow depends on constraint processing.
This specification uses DTD syntax to define the format of the ICE protocol. The question of why this was done occasionally comes up, given that XML allows for DTDs but does not require them, and given that there are a number of other mechanisms (XML-Data, XSchema, DCD etc.) for defining XML document structure.
Inherently, because ICE is built using well-formed XML documents,
many different methods could have been used to specify syntax.
For example, BNF can be used to define the protocol format as
a grammar, complete with '<' and '/>'
as literal elements in the productions. The authors of CDF in
fact did this (albeit probably for historical reasons).
The use of a DTD mechanism implies very little about interoperability among implementations and about the ability to use other mechanisms in the future. The important question to ask is: what is the format of the pattern of bits exchanged over the wire. Whether specified using a DTD, XML-Data, BNF, a lex/yacc grammar, or lisp program, the "instance" (pattern of bits in the ICE document) is the same. This is the important point.
There are two places where a DTD is implied. One is in the following requirements:
Note, however, that "validation" could in principle be implemented in a variety of ways. A Receiver MAY use any alternate representation of ICE syntax, and perform some alternate form of validation against that representation, as long as the results are AS-IF the governing ICE DTD had been used.
The second place where a DTD is implied is in the DOCTYPE declaration of an ICE packet. A Receiver MAY simply ignore this declaration if the Receiver is not using a DTD. A Sender MUST supply this declaration, but this presents no particular burden to Sender implementations that function without DTDs; they can simply point to a publicly available known ICE DTD for the purposes of meeting this requirement.
One of the requirements identified early in the design process for ICE was to design a protocol that was transport-independent, so that the concepts and development work done for ICE can be leveraged in a variety of situations. Therefore, the ICE protocol has been designed based on the concept of XML document exchange: each protocol message consists of a valid XML document, and the protocol involves sending such documents back and forth between syndicator and subscriber.
This specification explicitly discusses the binding of the generic ICE protocol to the HTTP transport mechanism. This specification uses the term ICE/HTTP where necessary to specifically refer to the concept of ICE bound to an HTTP transport mechanism.
To preserve the goal of being transport independent, and also to enable ICE to operate within existing network infrastructures, ICE/HTTP transmits payloads using the HTTP POST/Response mechanism. ICE/HTTP does not define any new HTTP headers or modify the HTTP protocol in any way; rather, the entire ICE request/response exchange is contained in the body of the HTTP POST and its associated HTTP Response.
The ICE protocol itself deliberately does not address security, because the required levels of security can be achieved via existing and emerging Internet/Web security mechanisms.
In the specific case of digital signatures, non-repudiation, and similar concepts, two things have happened that have steered the Authoring Group away from the notion of having digital signatures inside ICE itself:
Independent of any future XML digital signing standards, ICE implementations can achieve necessary security using a variety of methods, including:
Also, for interoperability, syndicators and subscribers need to agree on how they will negotiate the security parameters for a given relationship. This is done outside of ICE; e.g., by an agreement to use SSL at a certain level of encryption, etc.
Few internationalization issues occur at the protocol level at which ICE operates, but four specific issues are worthy of note:
ice-code (see 3.3)
include both a numeric error code and a short phrase,
such as "OK" or "Not found". As is described in detail in 3.3.4,
the phrase is intended for informational purposes only; it
is the numeric error code itself that defines the semantics of the
error message. Internationalized implementations of ICE are expected
to convert the numeric ICE error code into an appropriate
presentation string in the local language. Thus, there
is no requirement for ICE to support multi-lingual versions
of the error code phrase, such as "Mahalo" instead of "OK"
in the 200 code.
ice-sender (see 3.5.1) encodes the sender's
role as either "subscriber" or "syndicator". These textual strings
are intended as arbitrary tokens representing a specific concept;
they are not intended for presentation and thus have no impact
on internationalization issues.
ice-business-term element (see 4.3.1). ICE provides
a lang attribute in all places where human-readable text
is being transported and might require an identification of its specific
language encoding. When used, the lang attribute SHOULD
be filled in according to standards RFC-1766 (Tags for the
Identification of Languages) and ISO-639 (Code for the representation
of names of languages).
The remainder of this document is organized as follows:
Two entities are involved in forming a business relationship where ICE is used. The Syndicator produces content that is consumed by Subscribers. The Syndicator produces a subscription offer from input from various departments in an organization. Decisions are made about how to make these goods available to prospects. The subscription offer includes terms such as delivery policy, usage reporting, presentation constraints, etc. An organization's sales team engages prospects and reaches a business agreement typically involving legal or contract departments. Once the legal and contractual discussions are concluded, the technical team is provided with the subscription offer details and information regarding the Subscriber. The subscription offer is expressed in terms that a web application can manage (this could be database records, an XML file, a plain text file, and so on). In addition, the technical team may have to set up an account for the subscriber entity, so that the web site can identify who it is accessing the syndication application.
The Subscriber receives the information regarding their account (their subscriber identification and location to request their catalog) and how to obtain a catalog of subscription offers. At this point actual ICE operation can begin. The important point to understand is that ICE starts after the two parties have already agreed to have a relationship, and have already worked out the contractual, monetary, and business implications of that relationship.
The ICE protocol covers four general types of operations:
From the ICE perspective, a relationship between a Syndicator and a Subscriber starts off with some form of Subscription Establishment. In ICE, the subscriber typically begins by obtaining a catalog of possible subscriptions (really, subscription offers) from the Syndicator. The Subscriber then subscribes to particular subscriptions, possibly engaging in protocol parameter negotiation to arrive at mutually agreeable delivery methods and schedules.
The relationship then moves on to the steady state, where the primary message exchanges center on data delivery. ICE uses a package concept as a container mechanism for generic data items. ICE defines a sequenced package model allowing syndicators to support both incremental and full update models. ICE also defines push and pull data transfer models.
Managing exceptional conditions and being able to diagnose problems is an important part of syndication management; accordingly, ICE defines a mechanism by which event logs can be automatically exchanged between (consenting) Subscribers and Syndicators.
Finally, ICE provides a number of mechanisms for supporting miscellaneous operations, such as the ability to renegotiate protocol parameters in an established relationship, the ability to send unsolicited ad-hoc notifications (i.e., textual messages) between systems (presumably ultimately targeted at administrators), the ability to query and ascertain the state of the relationship, etc.
Two simple scenarios are used throughout this specification as the source for examples: syndication of news headlines from an online publisher to other online services, and syndication of a parts catalog from a manufacturer to its distributors.
An online content provider, Headlines.com, allows other online sites to subscribe to their headline service. Headlines.com updates headlines three times a day during weekdays, and once each on Saturday and Sunday. A headline consists of four fields: the headline text, a small thumbnail GIF image, a date, and a URL link that points back to the main story on Headlines.com.
Subscribers who sign up for the headline service can collect these headlines and use them on their own site. They display the headlines on their own site, with the URL links pointing back to Headlines.com. For an extra fee, subscribers may harvest the actual story bodies from Headlines.com and thus keep the traffic on their own site instead of linking back to Headlines.com.
A jet-powered pencil sharpener manufacturer, JetSharp.com, wants to keep its distributors up-to-date with the latest parts and optional accessories catalog at all times. It is very important to JetSharp that its distributors always have easy access to the latest service bulletins, and also that they have the latest information about optional accessories and the corresponding price lists.
Each item in the JetSharp parts catalog consists of some structured data, such as price, shipping weight, and size, and also contains unstructured data consisting of a set of HTML files and GIF images describing the product.
The JetSharp catalog is huge, but, fortunately, changes fairly slowly over time.
The ICE protocol is a request/reply protocol that allows for fully symmetric implementations, where both the Syndicator and Subscriber can initiate requests, and also allowing for a Minimal Subscriber implementation where only the Subscriber can initiate requests (i.e., no agent that would be considered a "server" resides on the Subscriber machine).
There are several key concepts that form the foundation of the ICE protocol. They are introduced here, without regard to their spelling (i.e., how they appear in the protocol). The next chapter (3.0 Protocol Infrastructure) revisits these concepts, and more, with a complete description of the protocol format. But first it is important to understand the basic concepts.
ICE uses payload exchange as its fundamental protocol model, where a payload is defined for the purposes of this specification to be a single instance of an XML document formatted according to the ICE protocol definition. The word payload was chosen simply because it is unusual and does not occur in ordinary casual writing; therefore, it can be carefully and unambiguously used throughout a specification.
Payloads can contain requests, responses or unsolicited messages. The unsolicited messages are used to support Minimal Subscriber implementations and will be explained in that context, later (see 2.2.4). A request is a message asking for the performance of an operation, and a payload is used to transmit the request. For example, when a Subscriber wishes to initiate a relationship by obtaining a catalog from a Syndicator, the Subscriber sends the Syndicator a payload containing a "get catalog" request. Similarly, a response is a message containing the results of an operation and a payload is also used to transmit responses.
Every logical operation in ICE is described by a request/response pair. All operations are forced to fit this model; thus, a valid ICE protocol session always comprises an even number of messages when it is in the idle state (i.e., there is a matching response for every request).
There are a few operations in ICE that have no logical requirement for a response. Nevertheless, to preserve the nature of the request/response protocol, responses are returned anyway.
The Subscriber and Syndicator assume several different roles during ICE protocol operations: Subscriber vs. Syndicator, Requestor vs. Responder, and Sender vs. Receiver.
The definition of Subscriber and Syndicator is based on the business relationships: the Syndicator distributes content to the Subscriber. These terms are capitalized throughout this specification wherever they refer specifically to the roles of the parties in an ICE relationship, as opposed to the general concepts of subscribing and syndicating.
The definition of Requestor/Responder is based on who initiates the ICE operation. The initiator is the Requestor, and the other party, who performs the operation, is the Responder. It is possible for a Syndicator to be either a Requestor or a Responder, depending on the particular operation. The same is true for a Subscriber. For example, when a Subscriber initiates a "get catalog" request to a Syndicator, the Subscriber is the Requestor. When a Syndicator initiates a "push package update" request to a Subscriber, the Syndicator is the Requestor.
Finally, the concept of Sender and Receiver are used in this specification to describe the relationship with respect to the transmission of a single payload. A payload travels from Sender to Receiver (and this thus forms the definition of Sender and Receiver).
Note that an ICE operation inherently consists of a Request/Response pair. Thus, the Requestor starts out being a Sender, sending a payload, containing a request, to the Receiver. The Receiver of this first payload is the Responder. When the Responder has performed the operation and wishes to return the results, the Responder becomes the Sender of a payload containing the response, and the initial Requester is now the Receiver.
Due to the nature of the content syndication business, it is important for ICE to support Subscriber implementations of varying levels of sophistication. In the most general case, a Subscriber is a sophisticated server implementation capable of not only sending ICE requests, but also receiving communications initiated by the Syndicator at any time, such as the "push" of new content. That is, a "full" Subscriber has an ICE server running at all times. ICE also supports the concept of a Minimal Subscriber implementation. This is a Subscriber that can initiate communicates (e.g. polling for updates) but does not have a persistent server available to receive requests. A Minimal Subscriber is expected to be run on demand, either by a user or by an automated script.
Thus, in a Minimal Subscriber implementation, the Subscriber always initiates any communication, and therefore the Syndicator cannot initiate any communication to the Subscriber. In that case the Subscriber is always the Requestor, and never the Responder. However, sometimes a Syndicator needs to initiate a message to a Subscriber. For example, the Syndicator might wish to send a "notify" message containing warning that the system will be down next week.
To support Minimal Subscribers and yet still allow Syndicators to initiate requests, ICE defines a mechanism called the Unsolicited Message mechanism. This mechanism supports sending ICE requests from a Syndicator to the Subscriber in a protocol communication initiated by the Subscriber.
As will be seen later when unsolicited messages are explained in detail, the unsolicited message mechanism is largely orthogonal to the primary ICE request/response protocol mechanism. It is defined as an additional set of message types that can be carried by payloads, and as such can be understood separately. See section 3.9, Unsolicited Message Operation for more details. For explanatory purposes, most of this specification ignores the implication of the unsolicited message mechanism when explaining how ICE works; section 3.9 then describes in detail how the unsolicited message mechanism interacts with the rest of ICE. It is important to note, however, that support for unsolicited messages is not optional; all ICE Subscribers and Syndicators MUST implement the unsolicited message mechanism as described in this specification.
ICE uses XML document exchange as its fundamental protocol
model. ICE messages are valid XML documents, with a single ice-payload
root element (defined in detail later) and a structured hierarchy
of tags describing the ICE operations and data.
This section describes the specifics of how ICE payload exchange is performed using HTTP.
To send an ICE/HTTP payload, the Sender performs an HTTP POST to a URL provided by the Receiver. ICE does not define the mechanism by which the Sender first obtains this URL; typically it will be communicated during a phone call, e-mail, or contract exchange when the two parties are establishing their initial relationship. It is expected that conventions for this URL will develop over time, in much the same way the convention of "http://www.domain-name" has developed for web sites.
Every ICE logical operation begins with a Sender sending a request; typically this is the Subscriber initiating an operation to the Syndicator. In some cases, such as push delivery of packages, the Syndicator initiates the operation and is the Sender.
As will be shown in detail later, ICE requests are specified
using an ice-request XML element, and ICE responses
are specified using an ice-response element. For
ICE/HTTP, the ice-request MUST be sent in
an HTTP POST, and the ice-response to that request
MUST be sent in the HTTP Response to that POST. Thus, a
single ICE request/response pair always maps directly to a single
HTTP POST/Response pair.
Operations involving package transmission can ask for an additional
confirmation, i.e., a third message (request/response/confirmation).
In that case the confirmation message is actually a separate request
with its own response, so the physical realization of (request/response/confirmation)
is actually (request/response/request/response). This will be
explained in more detail in the confirmation section, for now
it suffices to understand that a confirmation message is simply
POSTed as another ice-request.
An example will help illustrate this. Consider package update: the Subscriber makes a "get package" request to the Syndicator, the Syndicator sends a "package" response, and if the Syndicator asks for confirmation then the Subscriber sends a second "confirmation" request.. In a pseudo-code representation of the protocol, the exchanges look like this: (this is pseudo-code, it does not represent the actual protocol format):
(1) SUBSCRIBER ==> SYNDICATOR:
HTTP POST:
<ice-payload>
<ice-request>
Get Package
</ice-request>
</ice-payload>
(2) SUBSCRIBER <== SYNDICATOR:
HTTP Response to the POST:
<ice-payload>
<ice-response>
Package: X
Confirmation Required
</ice-response>
</ice-payload>
Note that this exchange of an ice-request and
an ice-response occurs entirely within a single HTTP
POST/Response transport level transaction.
(3) SUBSCRIBER ==> SYNDICATOR:
HTTP POST:
<ice-payload>
<ice-request>
Confirmation of Package X
</ice-request>
</ice-payload>
(4) SUBSCRIBER <== SYNDICATOR:
HTTP Response to the POST:
<ice-payload>
<ice-response>
</ice-response>
</ice-payload>
A confirmation message is a request that (logically) needs no response, other than the "ack" necessary to maintain the request/response nature of the ICE protocol.
ICE allows multiple requests or responses to be sent in a single
ice-payload. This allows round-trips to be minimized
whenever possible. For example, a Subscriber with ten subscriptions
to a single Syndicator can send all ten "get package"
requests and receive all ten updates in a single HTTP POST/Response
communication.
Four key restrictions about the multiple request/response model must be clearly understood:
ice-request elements in a single
ice-payload does not imply any ordering or transactional
semantics. A Sender MUST assume the Receiver processes
the requests in an arbitrary order, AS-IF each request had been
sent separately in its own payload.
ice-request elements
and ice-response elements within a single ice-payload.
ice-response elements in a response
payload MUST be the same as the number of ice-request
elements in the initiating payload, with the sole exception to
this rule being errors and conditions related to the entire payload,
as explained in the discussion of 3xx Payload-Level Status Codes
in section 3.3.4 (Defined Status Codes).
ice-response element in a response payload
MUST be a response to an ice-request element
in the initiating payload.
Package update responses can potentially be quite large; the
above rules provide no relief from the possibility that asking
for ten package updates would result in a response that is 900MB
in length (or longer). This problem can be called the Huge
Response problem. ICE provides Syndicators with two mechanisms
by which they can avoid causing the Huge Response problem: the
use of external XML entities and/or the use of an ice-item-ref
mechanism for transmitting package content external to the actual
response. Whether or not a Syndicator chooses to use these mechanisms
(and thus avoid causing the Huge Response problem) is a quality
of implementation issue.
| Informational Note | |
| for historical reference | |
|
As already noted, a single A more general model would allow arbitrary packing and piggybacking of requests and responses into the HTTP POST/Response stream. This design was explicitly rejected because it imposes complexity on ICE implementations and makes it impossible to implement simple programs that create ICE/HTTP connections and perform simple operations. To see why this is so, consider an "ICE Ping" utility:
If arbitrary piggybacking were permitted, the Ping utility might get a 900MB package pushed at it when all it was expecting was a simple reply. The implication of the arbitrary piggybacking model on implementations is profound: all communication would have to be mediated through a message queue multiplexor/demultiplexor agent that can appropriately dispatch any piggybacked messages. In such an environment it becomes impossible to simply write a perl script (for example) that creates a direct HTTP connection, sends a preformatted packet, and simply prints the response. The restrictions on requests and responses in single payloads in ICE were chosen to avoid this complexity. The ability to create simple implementations was considered more compelling than the ability to further optimize HTTP communication via arbitrary piggybacking. |
When ICE payloads are transmitted via HTTP, the Content-Type MUST be application/x-ice.
This section describes aspects of the ICE protocol that are common across all types of operations, whereas later sections of the document describe the specific operations themselves.
ICE uses XML as the format for its payloads, and all ICE payloads MUST be formatted in accordance with the XML 1.0 specification [W3C-WD-xml]. Furthermore, ICE payloads MUST be well-formed and MUST be valid according to the ICE DTD.
This document does not repeat the general rules for proper XML encoding; readers are expected to refer to the XML specification.
ICE makes extensive use of XML attributes for representing values. The following requirements apply to the interpretation of attribute values:
"equivalent" |
" equivalent " |
ICE uses globally unique identifiers for identifying Subscribers and Syndicators. The globally unique identifier for the Subscriber and Syndicator MUST conform to the Universal Unique Identifier defined by the Open Group [OG-UUID]. Note that if a given installation sometimes functions as a Subscriber and sometimes functions as a Syndicator then it MAY use the same UUID as its identification in both roles.
The UUID format as specified consists of 32 hexadecimal digits, with optional embedded hyphen characters. Per the requirements in the Universal Unique Identifier specification, ICE implementations MUST ignore all hyphens when comparing UUID values for equality, regardless of where the hyphens occur. Also, note that comparisons MUST be case insensitive.
Aside from the Subscriber UUID and the Syndicator UUID, no other identifiers required by ICE are defined by the ICE protocol. All other identifiers function as being unique only within a certain scope. For example, a subscription identifier is generated by a Syndicator when the relationship between a Subscriber and a Syndicator is first established. The identification string used for the subscription ID need only be unique within the domain of all subscription identifiers generated by that Syndicator.
This section describes the date and time format used by ICE in all contexts where a parseable date is required. The format shown here is a selected profile of options from ISO8601:1988 (with Technical Corrigendum 1 applied), hereinafter referred to as [ISO8601].
The format for a date string in ICE Date Format is:
CCYY-MM-DD
where CCYY is the four-digit year (century and
year, as described in [ISO8601]), MM is a two-digit
month number, DD is the two-digit ordinal number
of the day within the calendar month, and the separator character
is a "-" (hyphen). This format is the Extended
Format described in [ISO8601] section 5.2.1.1, with the separator
as described in [ISO8601] section 4.4, and ICE implementations
MUST use this format for all date strings specified as
being in ICE Date Format.
Note that specifying a Date without a time rarely makes sense; see 3.2.5 for how to specify both.
The format for a time string in ICE Time Format is:
hh:mm:ss
where hh is the two-digit hour in 24 hour notation
ranging from 00 to 24 (this is not a typo), mm is
the two-digit minute ranging from 00 to 59, ss is
the two-digit seconds ranging from 00 to 59, and the separator
character is a ":" (colon). This format
is the Extended Format described in [ISO8601] section 5.3.1.1,
with the separator as described in [ISO8601] section 4.4, and
ICE implementations MUST use this format for all time strings
specified as being in ICE Time Format.
Note that midnight has two representations:
00:00:00
24:00:00
This is deliberate, and in accordance with [ISO8601] section 5.3.2.
ICE Time Format for representing subsecond granularity follows
[ISO8601] section 5.3.1.3, and thus uses a ","
(comma) separator and an arbitrary number of digits representing
the fraction down to whatever level of precision is appropriate.
Thus, the format for time with subsecond resolution is:
hh:mm:ss,s
where the "," (comma) is a literal character
([ISO8601] separator) and s after the comma is "to
the right of the decimal mark" and indicates the subsecond
value. The number of digits in the subsecond value, and the precision
of the subsecond value, and the ability of a given implementation
to honor that precision, are quality of implementation issues
and are not specified by ICE. Implementations MUST properly
parse subsecond values up to at least 9 digits. Note that this
does not imply the ability to actually resolve time down to the
nanosecond; it merely implies the ability to read such a timestamp
and then process it as best as the implementation can. Implementations
SHOULD properly parse fractions with an arbitrary number
of digits in the subsecond value.
All times specified within ICE MUST be specified using GMT (UTC). Implementations are expected to translate these times into the appropriate local time presentation format before interacting with users.
When a Date and Time need to be specified in a single string, the ICE Date and Time format is:
CCYY-MM-DDThh:mm:ss,s
where "T" (upper case letter T) is a
literal character ([ISO8601] designator). This format is the Extended
Format of calendar date and time of day as described in
[ISO8601] section 5.4.1 clause (a).
Senders MUST NOT specify invalid combinations of fields, such as February 31. Receivers SHOULD reject invalid combinations of fields, rather than trying to interpret them.
When a period of time needs to be specified, the ICE Duration format is:
PnS
where the "P" (upper case letter P) is a literal character ([ISO8601] designator), "n" is an arbitrarily large integer value, and "S" (upper case letter S) is a literal character. This format denotes a number of seconds. It is a specific profile of the choices available in [ISO8601] section 5.5.3.2; note that the alternative format restrictions (5.5.3.2.1) are not used by ICE. Implementations are expected to translate this representation into a more appropriate form before interacting with users.
To describe a period of time with subsecond granularity, the format is:
Pn,nS
i.e., using the same subsecond granularity syntax as described in 3.2.3 above.
All periods of time described as being in ICE Duration Format
in ICE MUST be specified in either the PnS
or Pn,nS format.
Note that long periods of time are represented by large quantities
of seconds in the above formats. For example, a period of one
day is P86400S. It is expected that implementations
will translate these time periods into a more familiar form as
part of their user interfaces.
ICE uses the familiar Internet protocol paradigm of three-digit status values in responses to protocol operations. This paradigm was chosen because it is well understood and is suited to both machine-to-machine communication and human interpretation.
There is no relationship between the status codes in ICE and the status codes at the HTTP transport level. As already described above, HTTP is merely the transport mechanism for ICE payloads, and any ICE implementation MUST appropriately handle HTTP status or error conditions at the transport level. For example, if a Subscriber encounters an HTTP-level redirect (3XX code), the Subscriber MUST honor it. The semantics of completing the HTTP transport operation do not affect the semantics of the ICE operations, as defined by the exchange of payloads, in any way.
Throughout the rest of this discussion, an HTTP status of "200 OK" is implicit for the transport of the ICE payloads.
The format of status codes is described by the following DTD fragment:
|
Status Code and Error Code Structure |
<!ELEMENT ice-code (#PCDATA) >
<!ATTLIST ice-code
numeric CDATA #REQUIRED
phrase CDATA #REQUIRED
payload-id CDATA #IMPLIED
message-id CDATA #IMPLIED
package-id CDATA #IMPLIED
lang CDATA #IMPLIED
>
|
and an example would be:
<ice-code
numeric="402"
phrase="Not well formed XML"
message-id="1998-07-01T11:34:10@nr3.com-1"
>
Your XML contained overlapping elements.
Here is the offending fragment:
<a><b>cdefg</a></b>
</ice-code>
The attributes are:
payload-id
of the payload referenced by this code. A Sender SHOULD
supply this when reporting a payload-level (3xx) code, and MUST
NOT supply it any other time. See further discussion of payload
errors.
request-id
of the request referenced by this code, or, in some cases, the
response-id of the response referenced by this code.
A Sender MUST supply this in all cases except when reporting
a payload-level (3xx) code.
package-id
of the package referenced by this code. A Sender MUST
supply this when issuing a confirmation or a surprise code (see 3.7)
that refers to a package.
ice-code.
The body of the ice-code element is free-form
text (#PCDATA) and can be used by implementations
to report human-readable descriptions. It has no semantics in
ICE.
Implementation note: it is very important to properly escape
any fragments reported in the body of the ice-code.
See, for example, the example shown in 3.3.2. Note in particular
that XML and HTML (and, more generally, any text containing angle
brackets and other syntactically significant characters) must be
properly escaped.
The defined status codes are shown below. Each bullet item
contains the three-digit numeric value, the corresponding
phrase, and a description in italics. Note that the
description in italics is part of the explanation and not part
of the status message.
When generating codes:
numeric
value from the set defined here.
phrase field
(enforced by the DTD).
phrase shown
in the list below.
When receiving codes:
phrase data
for any purpose other than as informational data with no defined
semantics. A typical use for the text string is to display it
on a console, or put it into a log file for later analysis by
humans.
ice-code
element for any purpose other than as informational data with
no defined semantics.
The status values defined by ICE are:
2xx: Success
3xx: Payload-level Status Codes
These indicate something about the ice-payload
itself, as opposed to the individual requests and responses within
the payload. These codes have one very explicit and important
semantic: they are used when the payload could not be properly
interpreted, meaning that even if there were multiple requests
in the payload, there will be only one ice-code in
the response. For example, if the payload had been corrupted,
it might be so corrupted that it isn't even possible to determine
how many requests it contains, let alone respond to them individually.
The specific codes are:
4xx: Request-level Status Codes
These indicate errors caused by an inability to carry out an individual request. Note that in some cases there are similar errors between the 3xx and 4xx class; the difference is whether or not the error is supplied as a single, payload-level error code (3xx) or whether it is supplied as a per-request code.
5xx: Implementation errors and operational failures
These indicate errors caused by internal or operational problems, rather than by incorrect requests. Note that, like all other codes except for the 3xx series, these must be sent individually with each response; if the error condition or operational problem prevents the Responder from resolving the original payload down to the request level, use a 3xx code instead.
6xx: Pending State
These codes indicate a state condition where the Subscriber is expected to send something to the Syndicator, or vice-versa.
ice-unsolicited-now but the Syndicator has
no unsolicited messages to send.
7xx: Local Use Codes
These codes are reserved for use by the local ICE implementation
and MUST NOT ever be sent over the wire. The intent is
that this range of codes can be used by the local ICE implementation
software to communicate transport-level error conditions, or other
specific local conditions, using the ice-code mechanism
in a way guaranteed to not collide with any other usage of ice-code
values.
9xx: Experimental Codes
ICE implementations MUST NOT use any codes not listed in this specification, unless those codes are in the 9xx range. The 9xx range allows implementations to experiment with new codes and new facilities without fear of collision with future versions of ICE.
How a given system treats any 9xx code is a quality of implementation issue.
Two special codes have been defined explicitly to support the concept of redirection at the ICE level: 390 for temporary redirection, and 391 for permanent redirection.
When performing a redirection, the Responder sends the appropriate
ice-code and an ice-location structure,
shown here:
|
ICE location element |
<!ELEMENT ice-location EMPTY>
<!ATTLIST ice-location
target CDATA #REQUIRED
>
|
The target attribute MUST be filled in
with the correct new transport communication endpoint. In ICE/HTTP,
this means that target is filled in with a new URL.
Redirection applies at the payload level, and not individually to the requests within the payload.
Each message in ICE is encapsulated in a single top-level structure
known as an ice-payload, or just "payload"
for short. This payload is a well-formed XML document that is
also valid according to the ICE DTD.
ICE messages MUST begin with a suitable XML document type declaration such as:
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.iceag.org/ICE.dtd" [
] >
Any alternate form of the above declaration is acceptable; the requirement is simply that a DTD MUST be specified somehow.
This declares the message to be valid XML according to the supplied DTD. The specific URL MUST be a functional URL that will return the DTD defining the version of the ICE protocol used to create this message.
The root node of the payload is the ice-payload
element as shown here:
|
Payload structure |
<!ELEMENT ice-payload (ice-header,
(ice-request+ |
ice-response+ |
ice-unsolicited-now |
ice-unsolicited-request+ |
ice-unsolicited-response+
)
)
>
<!ATTLIST ice-payload
payload-id CDATA #REQUIRED
timestamp CDATA #REQUIRED
ice.version CDATA #REQUIRED
>
|
A single ICE payload contains a header and either:
ice-request elements, or
ice-response elements, or
ice-unsolicited-now element, or
ice-unsolicited-request elements,
or
ice-unsolicited-response elements
Note that payloads are homogeneous, in the sense that elements
from the above list MUST NOT be mixed together in a single
payload. For example, a single payload can contain multiple ice-request
elements, but it cannot contain ice-request elements
and ice-response elements. The DTD representation
shown above enforces this constraint.
The semantics of the unsolicited elements are described in section 3.9 and will not be discussed further until then.
There are several attributes:
ice-payload
element. It provides a handle for error reporting and traffic
monitoring. This id is assigned by the Sender and MUST
be unique across all ICE payloads that a Sender sends to a particular
Receiver. ICE does not define the format of this identifier in
any way.
ice-payload element
and is provided for debugging and analysis purposes only. It
MUST be formatted according to the ICE DateTime format
with full resolution down to the seconds; it SHOULD be
formatted with finer resolution if possible.
| Informational Note | |
| for historical reference | |
| The ICE Authoring Group wishes to acknowledge the authors of the XML specification, from whom we copied (and adapted) our description of the semantics of the ice.version attribute. |
The ice-header is common among all ICE payloads
and contains a consistent structure for both syndicators and subscribers.
The following DTD fragment describes the header structure. The
basic data captured in the ice-header element is
the Sender identification. The Sender of the ICE message can either
be a syndicator or a subscriber.
|
Header structure |
<!ELEMENT ice-header (ice-sender,
ice-receiver? ,
ice-user-agent?
)
>
|
<!ELEMENT ice-sender EMPTY >
<!ATTLIST ice-sender
sender-id CDATA #REQUIRED
name CDATA #REQUIRED
role (subscriber | syndicator) #REQUIRED
>
|
|
<!ELEMENT ice-receiver EMPTY > <!ATTLIST ice-receiver
receiver-id CDATA #REQUIRED
name CDATA #REQUIRED
>
|
<!ELEMENT ice-user-agent (#PCDATA)> |
The ice-sender element describes the originator
of the payload. The attribute fields are:
The ice-receiver element is optional, and describes
the intended target of the payload. It is optional because the
target of the payload presumably already knows this information;
however, some implementations MAY choose to supply this
data as a debugging aid. Note that the element is optional; however,
if the element is supplied the following attributes are REQUIRED:
This field allows ICE tools to identify themselves with an arbitrary string, in a way analogous to the HTTP User-Agent string. Implementations SHOULD supply this string when sending a payload. No semantics for the contents of this string are defined by this specification.
Each ICE payload contains one or more ice-request
elements, or one or more ice-response elements, or
the unsolicited support elements which are described later in
this document. Note that a Sender MUST NOT mix request
and response elements within a single payload, and a Receiver
SHOULD reject such a payload with a 303 Payload validation
failure error.
|
ICE requests and responses |
<!ELEMENT ice-request (ice-cancel |
ice-change-subscription |
ice-code |
ice-get-catalog |
ice-get-event-log |
ice-get-package |
ice-get-sequence |
ice-get-status |
ice-nop |
ice-notify |
ice-offer |
ice-package+ |
ice-send-confirmations |
ice-repair-item
)
>
<!ATTLIST ice-request
request-id CDATA #REQUIRED
>
|
<!ELEMENT ice-response (ice-code,
(ice-cancellation |
ice-catalog |
ice-event-log |
ice-offer |
ice-location |
ice-package+ |
ice-sequence |
ice-status |
ice-subscription |
)?
)
>
<!ATTLIST ice-response
response-id CDATA #REQUIRED
unsolicited-pending
(false | true) "false"
>
|
An ice-request describes a requested ICE operation.
Other parts of this specification describe the elements representing
the actual ICE operations (ice-cancel, ice-get-catalog,
etc); only the attributes of the ice-request are
described here.
The sole attribute is:
An ice-response describes a response to a previously
requested ICE operation. Other parts of this specification describe
the elements representing the actual ICE responses (ice-cancellation,
ice-catalog, etc.); only the subelements and the
attributes of the ice-response are described here.
Note that an ice-response consists of an ice-code,
containing the code, and an optional additional element chosen
from ice-cancellation, ice-catalog,
etc. For this discussion, call those elements "results elements."
Considering the possibility of a successful vs. unsuccessful code
value, and the presence or absence of the results element, there
are four combinations possible:
ice-code 2xx (any success code) and a results
element: This would be a normal, successful, response to an operation
that returned something. For example, the response to an ice-get-catalog
includes an ice-catalog.
ice-code 2xx (any success code) and no results
element: This would be a normal, successful, response to an operation
that did not return anything and merely needed to indicate acknowledgement.
For example, the response to an ice-notify operation
contains no additional data, and so none is sent.
ice-code XXX (any error code) and a results
element: This is used in certain specific cases to communicate
additional data with an error response. For example, in response
to an ice-subscribe request, the response might
be error code 441 (Counter-proposal) and an ice-offer.
ice-code XXX (any error code) and no results
element: This would be a normal, unsuccessful, response to an
operation. The error code, message, reference, and free-form
text is all communicated within the ice-code element
itself.
There are several attributes:
ice-response (who, by definition,
was the Receiver of the ice-request to which this
is a response). This id has the same uniqueness requirements
as the request-id in an ice-request.
The complete set of conditions under which an ice-response
will contain a code value other than 200 (OK) and also contain
a results element are given here. In all other cases, a code value
other than 200 will have no results element in the ice-response.
When ICE transmits a package, it is possible that the Syndicator
might want a separate confirmation that the Subscriber correctly
received and processed all the data. This is especially important
for packages that require resolution (and fetching) of remote
URLs in order to fully resolve their data. The confirmation
flag attribute present in the ice-package element
provides a method for the Syndicator to indicate it wants the
subscriber to return an additional confirmation message.
More generally, there are times when an implementation might
wish to communicate an explicit processing error at some later
point in time, long after the actual ICE Request/Response message
exchange has completed. Consider the case where a Syndicator pushes
a package to a Subscriber, without a confirmation flag. After
acknowledging the receipt of the bits and returning a 200 (OK)
code, the Subscriber later determines that the package cannot
be processed. Perhaps the XML will not validate, or a remote resource
named in the package could not be fetched. To communicate this
back to the Syndicator, the Subscriber uses a surprise ice-code.
This is simply an ice-request where the request contains
an ice-code. It is called a surprise message
because, unlike the ice-code field in an ice-response,
a surprise ice-code appears asynchronously to any
other state transitions implied by the ICE protocol. To help the
Receiver interpret the surprise message, the message-id
attribute in the ice-code MUST refer back
to a previous message in the stream, said previous message being
the message that initiated the chain of events leading to the
surprise error. Using a surprise message, either party can send
an ice-request consisting of an ice-code
letting the other side know that something bad happened. The protocol
dictates that a Receiver respond to a surprise ice-code
with an ice-response containing an ice-code
and no other elements. Note that the Receiver's ice-code
value merely indicates the usual protocol-level acceptance/rejection
of the message itself; it does not semantically describe anything
about how the Receiver feels about the surprise error. Beyond
defining the response to a surprise error, the protocol does not
define what the Receiver should do upon receipt of such an error
code; at a minimum the most likely implementation will be to bring
the situation to the attention of an administrator.
Explicit confirmation requests in package delivery can then
be seen as a specific variation of this concept. In confirmation,
the Syndicator is explicitly soliciting a future "surprise"
ice-code message and expects to receive it even if
the result is 200 (OK).
The format of an ice-code message is simply an
ice-request containing an ice-code;
both elements have already been described and will not be described
again here. As an example, here is an ice-code message
that a Subscriber might send after a package failed to validate:
<ice-request
request-id="1998-08-11T12:34:56@xyz.com-1"
>
<ice-code
numeric="403"
phrase="Validation failure"
message-id="1998-07-01T11:34:10@nr3.com-1"
package-id="pkg5519923"
>
Could not validate the package you sent.
</ice-code>
</ice-request>
The response packet might look like this:
<ice-response
request-id="1998-07-05T02:03:45@nr3.com-1"
>
<ice-code
numeric="200"
phrase="OK"
message-id="1998-08-11T12:34:56@xyz.com-1"
>
</ice-code>
</ice-response>
Packages can be sent in either an ice-request
or an ice-response (depending on push/pull mode).
Regardless of how sent, whenever a Subscriber receives packages
with a confirmation flag with value true,
the Subscriber MUST eventually send an appropriate ice-code
message as the confirmation. As noted above, the right way to
think of this is that the confirmation ice-code message
is a surprise ice-code message, except that in this
case the Syndicator has explicitly solicited it and so the Subscriber
MUST eventually send it.
Package confirmation specifically implies the following:
This is a much stricter set of acknowledgements than that implied by the 200 (OK) response to the package transmission. After a Syndicator receives a confirmation message, it may assume that the package has been fully processed by the Subscriber and that no further error conditions will occur regarding that particular package.
In push subscriptions, a Subscriber will send two different
code messages to the Syndicator if confirmation has been requested.
The first will be the one contained in the ice-response
that the Subscriber will send in response to the (pushed) ice-request
containing the package. That code will describe whether or not
the Subscriber correctly received the push message. Second, sometime
later the Subscriber will send another ice-code to
describe the higher level results noted above as being part of
confirmation.
Note that the Syndicator can control the level of complexity associated
with the confirmation mechanism. In the simplest implementations, a Syndicator
need never ask for any confirmations. Another simple implementation
would be to ask for confirmations, and never allow a subsequent package
to be delivered until the preceding confirmation is received (effectively
implementing a "stop-and-wait" fully-serial style protocol).
Much more complex implementations, including windowing (allowing
multiple outstanding confirmations) are possible. Note that
the protocol includes two other tools for Syndicators to use in
implementing confirmations: ice-send-confirmations
as a request allowing a Syndicator to poll a Subscriber for outstanding
confirmations (see 5.5.1), and the 602 (Excessive confirmations outstanding)
error code, which allows a Syndicator to force a Subscriber to
synchronize (i.e., to send outstanding confirmations before proceeding
any further). These mechanisms give complete control over
confirmation to the Syndicators, and allow Syndicators to implement many
different models as necessary to meet their requirements.
Two codes have been defined specifically for use with confirmation messages: 201 (Confirmed) and 430 (Not confirmed).
To confirm success, a Sender MUST use the 201 code, not the 200 code. The purpose of this restriction is to emphasize that confirmation is performing a higher-level application oriented check that is different from the ordinary processing implied by 200. For interoperability, a Receiver SHOULD accept either the 200 or 201 code as an acceptable positive confirmation.
To confirm failure, a Sender MUST use an error code. The error code 430 ("Not confirmed") has been set aside for use as a generic "something bad happened" code, but if more details can be accurately conveyed by a different code then the Sender SHOULD use it.
This section shows a complete ICE nop exchange between a Sender and a Receiver, as a way of illustrating the basic ICE protocol principles outlined above.
In this example, the Sender sends a payload containing only one nop request. The Sender initiates the NOP by POSTing the following payload to the Receivers ICE/HTTP URL:
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.somestandard.org/ICE.dtd"
>
<ice-payload
payload-id="1998-07-05T02:02:23@xyz.com"
timestamp="02:02:23,449"
ice.version="1.0">
<ice-header>
<ice-sender
sender-id="4af37b30-2c35-11d2-be4a-204c4f4f5020"
name="XYZ Corporation"
role="subscriber"/>
<ice-user-agent>
Acme Ray Gun ICE System, V0.9beta
</ice-user-agent>
</ice-header>
<ice-request
request-id="1998-07-05T02:02:23@xyz.com-1">
<ice-nop/>
</ice-request>
</ice-payload>
The response would come back in the HTTP Response of the POST, and look like this:
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.somestandard.org/ICE.dtd"
>
<ice-payload
payload-id="1998-07-05T02:03:45@nr3.com"
timestamp="02:03:45,31416"
ice.version="1.0">
<ice-header>
<ice-sender
sender-id="4a2180c9-9435-d00f-9317-204d974e3410"
name="Number Three Corporation"
role="syndicator"/>
<ice-user-agent>
Road Kill Systems ICE Processor, V17 patch 9
</ice-user-agent>
</ice-header>
<ice-response
response-id="1998-07-05T02:03:45@nr3.com-1">
<ice-code
numeric="200"
phrase="OK"
message-id="1998-07-05T02:02:23@xyz.com-1"
>
</ice-code>
</ice-response>
</ice-payload>
This example shows a Subscriber sending a payload containing two nop requests, and the Syndicator responding with two responses. Note that the responses to the nops come back in a different order within the payload than the requests, illustrating one possible side-effect of the fact that no ordering is implied by having multiple requests in a single payload.
Request:
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.somestandard.org/ICE.dtd"
>
<ice-payload
payload-id="1998-07-05T03:03:34@xyz.com"
timestamp="03:03:34,449"
ice.version="1.0">
<ice-header>
<ice-sender
sender-id="4af37b30-2c35-11d2-be4a-204c4f4f5020"
name="XYZ Corporation"
role="subscriber"/>
<ice-user-agent>
Acme Ray Gun ICE System, V0.9beta
</ice-user-agent>
</ice-header>
<ice-request
request-id="1998-07-05T03:03:34@xyz.com-1">
<ice-nop/>
</ice-request>
<ice-request
request-id="1998-07-05T03:03:34@xyz.com-2">
<ice-nop/>
</ice-request>
</ice-payload>
Response:
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.somestandard.org/ICE.dtd"
>
<ice-payload
payload-id="1998-07-05T03:03:45@nr3.com"
timestamp="03:03:45,31416"
ice.version="1.0">
<ice-header>
<ice-sender
sender-id="4a2180c9-9435-d00f-9317-204d974e3410"
name="Number Three Corporation"
role="syndicator"/>
<ice-user-agent>
Road Kill Systems ICE Processor, V17 patch 9
</ice-user-agent>
</ice-header>
<ice-response
response-id="1998-07-05T03:03:45@nr3.com-1">
<ice-code
numeric="200"
phrase="OK"
message-id="1998-07-05T03:03:34@xyz.com-2"
>
</ice-code>
</ice-response>
<ice-response
response-id="1998-07-05T03:03:45@nr3.com-2">
<ice-code
numeric="200"
phrase="OK"
message-id="1998-07-05T03:03:34@xyz.com-1"
>
</ice-code>
</ice-response>
</ice-payload>
ICE allows for simple implementations, known as Minimal Subscriber Implementations, to be legal ICE Subscriber implementations. In a Minimal Subscriber Implementation, the Subscriber provides no method for the Syndicator to initiate messages to the Subscriber; all communication initiates at the Subscriber. This model allows for simple Subscribers that have no active agent for receiving messages from the Syndication server.
There are, however, times in ICE where the Syndicator will want to send messages to the Subscriber. If the Subscriber is not a Minimal Subscriber, the Syndicator can simply send those messages the usual way. If the Subscriber is a Minimal Subscriber Implementation, then the unsolicited message handling support of ICE is necessary to allow these "reverse channel" messages to be sent.
The general model is quite simple:
unsolicited-pending, can be sent in
an ice-response. Using this flag, a Syndicator can
tell a Subscriber that there are unsolicited messages awaiting
collection.
unsolicited-pending flag,
a Subscriber issues a special type of payload element, ice-unsolicited-now,
to open a back channel from the Syndicator back to the Subscriber.
No information is conveyed in this ice-unsolicited-now
request, other than the implicit desire of the Subscriber to
receive any unsolicited messages that are available at this time.
ice-unsolicited-now
with one or more ice-unsolicited-request messages,
containing the actual unsolicited messages. If the Syndicator
has no unsolicited messages to send, the Syndicator responds
with an ice-code 604 (No more unsolicited messages).
ice-unsolicited-response payload element.
ice-unsolicited-response
with an ice-response, ending the conversation.
There is no hard connection between step 1 (reception of the
flag) and step 2 (opening the channel). A Subscriber MAY
wait an arbitrary period of time before issuing the ice-unsolicited-now,
and MAY in fact send other messages even after receiving
the unsolicited-pending flag. A Subscriber SHOULD
issue the ice-unsolicited-now payload as soon as
possible.
A specific error code, 601 ("Unsolicited messages must be processed now"), has been defined as a way for the Syndicator to indicate, at some point, its unwillingness to converse any further until the pending unsolicited messages have been collected by the Subscriber.
There is also no hard connection between step 3 (reception
by the Subscriber of the logical requests) and step 5 (transmission
by the Subscriber of the logical responses). It is very important
to understand that the reverse unsolicited message channel semantics
are AS-IF the Syndicator could have sent the request directly
to the Subscriber using the normal ice-request and
received the response using the normal ice-response.
Thus, all of the normal semantics associated with such a Request/Response
sequence pertain. In particular, note that the number of ice-unsolicited-response
elements in the payload sent from Subscriber to Syndicator MUST
correspond to the number of ice-unsolicited-request
elements. This is the analogous requirement to the one stating
that ice-request and ice-response elements
must match in number.
The following DTD fragment shows the format of the ice-unsolicited-now
message that a Subscriber sends to a Syndicator when it is ready
to receive unsolicited messages.
|
Unsolicited now element |
<!ELEMENT ice-unsolicited-now EMPTY>
<!ATTLIST ice-unsolicited-now
request-id CDATA #REQUIRED
>
|
When a Subscriber sends this message, the ice-unsolicited-now
element takes the place of the ice-request element
the Subscriber would send in all other cases. Thus, the attributes
of the ice-unsolicited-now element are the same as
those of the ice-request element:
request-id
attribute in an ice-request.
Note that Syndicators MUST NOT ever send an ice-unsolicited-now
to a Subscriber. This is discussed in more detail under 3.9.5
Asymmetry.
A Subscriber MAY send an ice-unsolicited-now
at any time. The Subscriber is not forced to wait for the unsolicited-pending
flag before it tries an ice-unsolicited-now. Thus,
it is perfectly legal for a Subscriber to "ping" a Syndicator
with periodic ice-unsolicited-now messages; whether
this is a good idea or not is a quality of implementation issue.
Upon receiving an ice-unsolicited-now, a Syndicator
responds either with an ice-response containing only
a non-success ice-code, or else responds with an
ice-unsolicited-request element. The DTD for the
ice-unsolicited-request element is shown here:
|
Unsolicited Request |
<!ELEMENT ice-unsolicited-request
(ice-change-subscription |
ice-code |
ice-get-event-log |
ice-get-status |
ice-nop |
ice-notify |
ice-package+ |
ice-send-confirmations
)
>
<!ATTLIST ice-unsolicited-request
unsolicited-request-id CDATA #REQUIRED>
|
When a Syndicator sends this message, the ice-unsolicited-request
element takes the place of the ice-request element
the Syndicator would have sent to the Subscriber, if the Syndicator
had been able to send it directly (instead of using the unsolicited
message mechanism). Thus, the attributes of the ice-unsolicited-request
element are the same as those of the ice-request
element:
request-id
attribute in an ice-request.
Note that the set of operations that can be sent this way is a subset of the full set of operations. This is because of the assymetric nature of the unsolicited message support: only Syndicators can use this mechanism to send messages to Subscribers (not vice versa); therefore, the set of legal requests is restricted to those that a Syndicator would send to a Subscriber.
As with ice-request, any number of ice-unsolicited-request
elements MAY be sent in a single payload. The maximum number
to send is an implementation-specific quality of implementation
policy decision.
Note that Subscribers MUST NOT ever send an ice-unsolicited-request
to a Syndicator. This is discussed in more detail under 3.9.5
Asymmetry.
Upon receiving an ice-unsolicited-request, a Subscriber performs the operation it contains and eventually sends an ice-unsolicited-response to return the results to the Syndicator. The DTD for the ice-unsolicited-response element is shown here:
|
Unsolicited Response |
<!ELEMENT ice-unsolicited-response
(ice-code,
(ice-events |
ice-status)?)>
<!ATTLIST ice-unsolicited-response
unsolicited-response-id CDATA #REQUIRED
>
|
When a Subscriber sends this message, the ice-unsolicited-response
element takes the place of the ice-response element
the Subscriber would have sent to the Syndicator, if the Syndicator
had been able to make the original request directly instead of
using the unsolicited message mechanism. Thus, the attributes
of the ice-unsolicited-response element are the same
as those of the ice-response element, except that
there is no unsolicited-pending flag:
response-id
attribute in an ice-response.
However many ice-unsolicited-request elements
were sent in the originating payload, that same number of ice-unsolicited-response
elements must appear in the response, unless there is a catastrophic
payload-level error.
Note that Syndicators MUST NOT ever send an ice-unsolicited-response
to a Subscriber. This is discussed in more detail under 3.9.5
Asymmetry.
ICE does not permit a "Minimal Syndicator" implementation; said differently, a Syndicator is REQUIRED to be capable of being a Responder, responding to protocol requests initiated by a Subscriber. Therefore, the implementation requirements for the unsolicited message are asymmetric with respect to Syndicator and Subscriber:
unsolicited-pending flag, sending
the unsolicited-now payload, etc.
unsolicited-pending
flag, responding to the unsolicited-now payload,
etc.
unsolicited-now payload, and
respond with the code 604 (No more unsolicited messages).
Implementation note: the unsolicited message mechanism makes a good fall-back mechanism for Syndicators to use when communication with their non-Minimal Susbcribers fails. The possibility that a Syndicator MAY choose to use the unsolicited message mechanism in this fashion is the primary reason why all Subscribers MUST implement the subscriber-side portion of the unsolicited message protocol, even if the Subscriber is not a Minimal Subscriber Implementation.
| Informational Note | |
| for historical reference | |
|
The model specified above is an "explicit"
mechanism, where support for the concept of unsolicited messages
has been added at the most fundamental levels of the ICE protocol;
specifically, at a peer level with the concept of An alternative mechanism would have been to
simply define additional requests for unsolicited messages and
"tunnel" them within the existing
It is a fair criticism of the specified (no-tunneling)
design that it explicitly forces extra communication to handle
unsolicited messages. For example, it is not possible for a Subscriber
to request some ICE operation while at the same time request
unsolicited messages. The solution given in this specification
forces the Subscriber to make two separate payloads in that case:
one for the ordinary |
3.9.6 Policy decisions
The Syndicator and Subscriber each have a variety of implementation-specific policy decisions to make regarding unsolicited messages.
On the Subscriber side, the implementation has to decide how
to treat the reception of the unsolicited-pending
flag. The Subscriber MAY choose to immediately issue an
ice-unsolicited-now, preempting any other planned
communication that Subscriber might have at the time, or the Subscriber
MAY choose to defer the collection of unsolicited messages
until some later point in time.
The Syndicator has to decide how many unsolicited messages
it will queue for a Subscriber, and when to switch from the mode
of simply flagging their existence with unsolicited-pending,
and instead forcing the Subscriber to collect them. The Syndicator
uses the 601 (Unsolicited messages must be processed now) code
to force the Subscriber to collect the messages.
In this first example, a Subscriber first performs a nop operation to the Syndicator. The response to the nop operation has the unsolicited-pending flag set. The Subscriber then sends an unsolicited-now to collect the unsolicited message(s). The Syndicator sends two ice-notify operations using unsolicited-request, and the Subscriber responds to both using unsolicited-response.
As explained in 3.9.2 Format of unsolicited-now, it
would have been perfectly legal for a Subscriber to send the ice-unsolicited-now
operation without first getting the unsolicited-pending
flag (which shows up in this example on the first nop). The nop
in this example is used simply as a way to demonstrate the use
of the unsolicited-pending flag by the Syndicator.
(1): SUB ==> SYN: NOP
The Subscriber sends a nop to the Syndicator:
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.somestandard.org/ICE.dtd"
>
<ice-payload
payload-id="1998-07-22T02:02:23@xyz.com"
timestamp="02:02:23,449"
ice.version="1.0">
<ice-header>
<ice-sender
sender-id="4af37b30-2c35-11d2-be4a-204c4f4f5020"
name="XYZ Corporation"
role="subscriber"/>
<ice-user-agent>
Acme Ray Gun ICE System, V0.9beta
</ice-user-agent>
</ice-header>
<ice-request
request-id="1998-07-22T02:02:23@xyz.com-1">
<ice-nop/>
</ice-request>
</ice-payload>
(2) SUB <== SYN: Response w/unsolicited-pending
The Syndicator responds to the nop and sets the unsolicited-pending
flag:
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.somestandard.org/ICE.dtd"
>
<ice-payload
payload-id="1998-07-22T02:03:45@nr3.com"
timestamp="02:03:45,31416"
ice.version="1.0">
<ice-header>
<ice-sender
sender-id="4a2180c9-9435-d00f-9317-204d974e3410"
name="Number Three Corporation"
role="syndicator"/>
<ice-user-agent>
Road Kill Systems ICE Processor, V17 patch 9
</ice-user-agent>
</ice-header>
<ice-response
response-id="1998-07-22T02:03:45@nr3.com-1"
unsolicited-pending="true">
<ice-code
numeric="200"
phrase="OK"
message-id="1998-07-22T02:02:23@xyz.com-1"
>
</ice-code>
</ice-response>
</ice-payload>
(3) SUB ==> SYN: ice-unsolicited-now
The Subscriber, having seen the unsolicited-pending
flag, eventually sends an ice-unsolicited-now:
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.somestandard.org/ICE.dtd"
>
<ice-payload
payload-id="1998-07-22T02:03:55@xyz.com"
timestamp="02:03:55,449"
ice.version="1.0">
<ice-header>
<ice-sender
sender-id="4af37b30-2c35-11d2-be4a-204c4f4f5020"
name="XYZ Corporation"
role="subscriber"/>
<ice-user-agent>
Acme Ray Gun ICE System, V0.9beta
</ice-user-agent>
</ice-header>
<ice-unsolicited-now
request-id="1998-07-22T02:03:55@xyz.com-1"/>
</ice-payload>
(4) SUB <== SYN: Two unsolicited requests
The Syndicator responds by sending two unsolicited requests; in this example both are notify operations containing textual messages.
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.somestandard.org/ICE.dtd"
>
<ice-payload
payload-id="1998-07-22T02:04:01@nr3.com"
timestamp="02:04:01,31416"
ice.version="1.0">
<ice-header>
<ice-sender
sender-id="4a2180c9-9435-d00f-9317-204d974e3410"
name="Number Three Corporation"
role="syndicator"/>
<ice-user-agent>
Road Kill Systems ICE Processor, V17 patch 9
</ice-user-agent>
</ice-header>
<ice-unsolicited-request
unsolicited-request-id="1998-07-22T02:04:01@nr3.com-1">
<ice-notify priority="2">
Our system will be down for maintenance tomorrow
</ice-notify>
</ice-unsolicited-request>
<ice-unsolicited-request
unsolicited-request-id="1998-07-22T02:04:01@nr3.com-2">
<ice-notify priority="4">
Our ICE software will be upgraded next month.
</ice-notify>
</ice-unsolicited-request>
</ice-payload>
(5) SUB ==> SYN: Two unsolicited responses
The Subscriber processes the notify operations, which happen to be simple operations that return no data (convenient for this example). The Subscriber sends the results in an unsolicited-response:
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.somestandard.org/ICE.dtd"
>
<ice-payload
payload-id="1998-07-22T02:10:19@xyz.com"
timestamp="02:10:19,449"
ice.version="1.0">
<ice-header>
<ice-sender
sender-id="4af37b30-2c35-11d2-be4a-204c4f4f5020"
name="XYZ Corporation"
role="subscriber"/>
<ice-user-agent>
Acme Ray Gun ICE System, V0.9beta
</ice-user-agent>
</ice-header>
<ice-unsolicited-response
unsolicited-response-id="1998-07-22T02:10:19@xyz.com-1">
<ice-code
numeric="200"
phrase="OK"
message-id="1998-07-22T02:04:01@nr3.com-2"
>
</ice-code>
</ice-unsolicited-response>
<ice-unsolicited-response
unsolicited-response-id="1998-07-22T02:10:19@xyz.com-2">
<ice-code
numeric="200"
phrase="OK"
message-id="1998-07-22T02:04:01@nr3.com-1"
>
</ice-code>
</ice-unsolicited-response>
</ice-payload>
(6) SUB <== SYN: Acknowledgements
To preserve the Request/Response symmetry of the protocol,
the Syndicator is required to respond to the ice-unsolicited-response
messages. The responses contain no useful data, except that they
do also serve as a convenient place for the Syndicator to show
that there are more unsolicited messages pending (this might happen
if the Syndicator chose to not send all of them in one giant payload).
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.somestandard.org/ICE.dtd"
>
<ice-payload
payload-id="1998-07-22T02:10:25@nr3.com"
timestamp="02:10:25,31416"
ice.version="1.0">
<ice-header>
<ice-sender
sender-id="4a2180c9-9435-d00f-9317-204d974e3410"
name="Number Three Corporation"
role="syndicator"/>
<ice-user-agent>
Road Kill Systems ICE Processor, V17 patch 9
</ice-user-agent>
</ice-header>
<ice-response
response-id="1998-07-22T02:10:25@nr3.com-1">
<ice-code
numeric="200"
phrase="OK"
message-id="1998-07-22T02:10:19@xyz.com-1"
>
</ice-code>
</ice-response>
<ice-response
response-id="1998-07-22T02:10:25@nr3.com-2">
<ice-code
numeric="200"
phrase="OK"
message-id="1998-07-22T02:10:19@xyz.com-2"
>
</ice-code>
</ice-response>
</ice-payload>
(7) SUB ==> SYN: Another ice-unsolicited-now
To illustrate the error response, the Subscriber (in this example)
sends another unsolicited-now message, but this time
the Syndicator has no more messages to send.
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.somestandard.org/ICE.dtd"
>
<ice-payload
payload-id="1998-07-22T02:23:55@xyz.com"
timestamp="02:23:55,449"
ice.version="1.0">
<ice-header>
<ice-sender
sender-id="4af37b30-2c35-11d2-be4a-204c4f4f5020"
name="XYZ Corporation"
role="subscriber"/>
<ice-user-agent>
Acme Ray Gun ICE System, V0.9beta
</ice-user-agent>
</ice-header>
<ice-unsolicited-now
request-id="1998-07-22T02:23:55@xyz.com-1"/>
</ice-payload>
(8) SUB <== SYN: Error response
As mentioned, the Syndicator (in this example) has no more unsolicited messages to send, so it returns this error:
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.somestandard.org/ICE.dtd"
>
<ice-payload
payload-id="1998-07-22T02:24:45@nr3.com"
timestamp="02:24:45,31416"
ice.version="1.0">
<ice-header>
<ice-sender
sender-id="4a2180c9-9435-d00f-9317-204d974e3410"
name="Number Three Corporation"
role="syndicator"/>
<ice-user-agent>
Road Kill Systems ICE Processor, V17 patch 9
</ice-user-agent>
</ice-header>
<ice-response
response-id="1998-07-22T02:24:45@nr3.com-1">
<ice-code
numeric="604"
phrase="No more unsolicited messages"
message-id="1998-07-22T02:23:55@xyz.com-1"
>
</ice-code>
</ice-response>
</ice-payload>
This section describes catalogs, and protocol parameter negotiation, which together form the heart of subscription establishment.
Subscription relationships in ICE usually begin with a request by the Subscriber to obtain a catalog of subscription offers from the syndicator. As already described, prior to the Subscriber making this request, the Subscriber and the Syndicator have probably already engaged in real-world discussions regarding licensing terms, payment options, and other considerations. Those happen outside of the ICE protocol. Once the parties agree that they wish to have a relationship, the ICE process begins.
A typical sequence of events is:
The delivery policy determines the times during which packages can be delivered (push) or requested (pull) for a given subscription. A delivery policy defines the start and stop dates during which the delivery policy is valid, and has one or more delivery rules.
Each subscription offer has a single delivery-policy. A delivery-policy has a start date, a stop date, and contains one or more delivery rules. Delivery policies are described by the following DTD fragment:
|
ice-delivery-policy |
<!ELEMENT ice-delivery-policy (ice-delivery-rule+) >
<!ATTLIST ice-delivery-policy
startdate CDATA #IMPLIED
stopdate CDATA #IMPLIED
>
|
The attributes are:
The multiple delivery-rules in a delivery-policy are conceptually joined with "OR" (not "AND"). In other words, the valid delivery times are the union of all the times defined by each rule in the delivery policy.
A delivery-rule defines a window of time during which deliveries can be performed. Each delivery-rule can be either a push or pull, can define which years, months, dates and days of the week in which deliveries can be performed, a start and ending time for the update window, the frequency with which updates can be performed, and the count of the number of updates that can be performed.
Delivery rules are defined by the following DTD fragment
|
ice-delivery-rule |
<!ELEMENT ice-delivery-rule (ice-negotiable*) >
<!ATTLIST ice-delivery-rule
mode (push | pull) #REQUIRED
monthday NMTOKENS #IMPLIED
weekday NMTOKENS #IMPLIED
startdate CDATA #IMPLIED
stopdate CDATA #IMPLIED
starttime CDATA #IMPLIED
duration CDATA #IMPLIED
minfreq CDATA #IMPLIED
maxfreq CDATA #IMPLIED
mincount CDATA #IMPLIED
maxcount CDATA #IMPLIED
url CDATA #IMPLIED
>
|
The ice-negotiable element is described in 4.2.3.
The attributes are:
push or pull. A push
delivery means that the update is initiated by the Syndicator.
A pull delivery means that the update is initiated
by the Subscriber.
any
or be the special value last. Any value that is
out of range for the given month is defined to mean that no delivery
happens that month; this rule applies to "31" in February,
for example, and applies to "32" (or any other out-of-range
value) in all months. Multiple values MAY be specified,
separated by ' ' (space) per the XML NMTOKENS
de