[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: No Subject
Hi, Attached is the most recent version of the ICE specification. This specification is not available to the general public - hence do not distribute this specification to anyone outside the ebXML transport working group. (See attached file: NOTE1_1N-ICE-19991212.htm) Regards, Erik J Leckner http://www.idealliance.org/ice/ice_ag.htm Seagate Technology, Inc. and ICE Authoring Group MemberTitle: NOTE-ICE-19991212 AC Review Version - N
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.
ICE 1.1 is an ICE 1.0 compatible update to the ICE 1.0 specification. This update is made in response to the implementation experience that has been gained over the past year. It differs from the ICE 1.0 specification in that it corrects several minor deficiencies in the original specification. It corrects several typographic errors. It continues the clarification of the specification to assist developers in achieving inter-operable implementations. Finally, ICE 1.1 specifies several of the most asked for implementation features. ICE 1.1 is fully upwards compatible with ICE 1.0 in that an ICE 1.0 implementation can inter-operate with an ICE 1.1 implementation using any function of ICE 1.0. ICE 1.1 implementations add capabilities ( most notably extensibility ) that are only accessible to other ICE 1.1 implementations.
The ICE authoring group and IDEAlliance recommend that implementations be updated to conform to the ICE 1.1 specification. The minor changes and added function greatly enhance the usability of the protocol in a very wide range of syndication applications and can provide a substantial foundation for delivering syndication solutions.
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.
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 Mark-up Language (XML). Basic concepts in ICE are represented using the element/attribute mark-up 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 mark-up language), PGML (Precision Graphics Mark-up 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 work group 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, name space 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.
Quoting from [NOTE-SMIL]: SMIL allows integrating a set of
independent multimedia objects into a synchronized multimedia presentation. Using SMIL, an
author can
1. describe the temporal behavior of the presentation
2. describe the layout of the presentation on a screen
3. associate hyper-links with media objects
SMIL (the Synchronized Multimedia Interchange Language) is an appropriate container format to be carried in an ICE package. SMIL defines the temporal, layout and linking relationship between media components of a presentation and therefore has the potential to be an important content manager format for syndicated media. ICE optimally carries content described by XML documents. SMIL is a standardized means for managing dynamic content based on an XML document. There is a natural complementary affinity between ICE and SMIL.
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.
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 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 may be done inside of ICE by using subscription extension or by using protocol extension. Or it may be done outside of ICE by, for example, an agreement to use SSL at a certain level of encryption, or by some other external means.
Few internationalization issues occur at the protocol level at which ICE operates, but four specific issues are worthy of note:
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. The ICE protocol also allows 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 (See Appendix A). 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 versus Syndicator, Requester versus Responder, and Sender versus 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 Requester/Responder is based on who initiates the ICE operation. The initiator is the Requester, and the other party, who performs the operation, is the Responder. It is possible for a Syndicator to be either a Requester 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 Requester. When a Syndicator initiates a "push package update" request to a Subscriber, the Syndicator is the Requester.
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 Requester 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 Requester, 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.10, 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.10 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 the following. Note, this is pseudo-code, it does not represent the actual protocol format. (The symbol, "==>", can be read as, "sends the following message to the" and the symbol, "<==", can be read as "receives the following message from the"):
| Package Update Example |
|---|
(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>
|
This exchange of an ice-request and an ice-response occurs entirely within a single HTTP POST/Response transport level transaction.
| Package Update Example |
|---|
(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 "acknowledge" 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:
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 900 megabytes 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 ice-payload always contains only one type of
element: a number of ice-request elements (but no other types), a number of ice-response
elements (but no other types), etc. This restriction simplifies ICE implementations, at
the possible expense of lost opportunities to optimize protocol traffic. A more general model would allow arbitrary packing and a mixture 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 mixtures were permitted, the Ping utility might get a 900 megabyte package pushed at it when all it was expecting was a simple reply. The implication of the arbitrary mixture model on implementations is profound: all communication would have to be mediated through a message queue multiplexor/demultiplexer agent that can appropriately dispatch any mixed 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 request/response mixing. |
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 defines a number of identifiers.
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.
As distinct from the Subscriber UUID and the Syndicator UUID, ICE does not define the format of other identifiers it specifies except for uniqueness constraints. 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 for the Subscriber.
The table below describes each identifier in ICE, its scope, a description of where in
an ICE payload the ID value is assigned, the role of the party that assigns the ID value,
where this ID value is referenced, and finally, the section in the specification where the
identifier is discussed.
| Identifier | Scope | Where assigned | By Whom Assigned | ID Referenced By | Section described in |
| Syndicator's UUID | Unique identifier of a Syndicator | When ICE syndicator created | Entity wishing to use ICE to Syndicate Content. See 3.2.1 above | sender-id attribute on ice-sender element or receiver-id attribute on ice-receiver element (depending on role) | 3.6.1, 3.6.2, 6.3 |
| Subscribers UUID | Unique identifier of a Subscriber | When ICE subscriber created | Entity wishing to use ICE to Subscribe to Content. See 3.2.1 above. | sender-id attribute on ice-sender element or receiver-id attribute on ice-receiver element (depending on role) | 3.6.1, 3.6.2, 6.3 |
| payload ID | Unique across all payloads from a sender to a receiver | payload-id attribute on ice-payload element | Sender assigns. See 3.5.2 | payload-id attribute on ice-code element | 3.4.2, 3.5.2 |
| package ID | Unique across all packages within a subscription | package-id attribute on ice-package element | Syndicator assigns. See 5.2.1 | package-id attribute on ice-code, ice-package-state elements | 3.4.2, 5.2.1, 5.5.2 |
| request ID | Unique across all payloads from a sender to a receiver | request-id attribute on ice-request, ice-unsolicited-now elements | Sender assigns. See 3.7.1 | message-id attribute on ice-code element; request-id attribute on ice-event-msg element | 3.7.1, 3.10.2, 6.3 |
| response ID | Unique across all payloads from a sender to a receiver | response-id attribute on ice-response element | Sender assigns. See 3.7.2 | response-id attribute on ice-event-msg element | 3.7.2, 6.3 |
| unsolicited request ID | Unique across payloads from a sender to a receiver | unsolicited-request-id attribute on ice-unsolicited-request element | Syndicator assigns. See 3.10.3 | message-id attribute on ice-code element; request-id attribute on ice-event-msg | 3.10.3, 6.3 |
| unsolicited response ID | Unique across payloads from a sender to a receiver | unsolicited-response-id attribute on ice-unsolicited-response element | Subscriber assigns. See 3.10.4 | response-id attribute on ice-event-msg | 3.10.4, 6.3 |
| subscription ID | Unique across subscriptions from a Syndicator to a Subscriber | subscription-id attribute on ice-subscription element | Syndicator assigns. See 4.3.1 and 4.6.3 | subscription-id attribute on ice-cancel, ice-change-subscription, ice-get-events, ice-get-package, ice-get-sequence, ice-get-status, ice-repair-item, ice-send-confirmation, ice-cancellation, ice-events, ice-sequence, ice-subscription, ice-offer, ice-package, ice-event-msg elements |
4.3.1, 4.6.1, 4.6.2, 4.6.3. 5.2.1. 5.3, 5.5.1, 5.5.2, 5.5.3, 6.2, 6.3 |
| cancellation ID (see note in 4.6.1) | Unique across all cancellations | cancellation-id attribute on ice-cancellation element | Responder assigns. See 4.6.1 | Not referenced deprecated | 4.6.1 |
| package sequence ID | Unique across all packages of a subscription, or "ICE-INITIAL" or "ICE-ANY" | new-state attribute on ice-package element | Syndicator assigns. See 5.1.3 | current-state attribute on ice-get-package, ice-get-sequence, ice-repair-item, ice-subscription, elements; old-state attribute on ice-package element | 5.1.3 |
| item ID | Unique across items in a package | item-id attribute on ice-item, ice-item-ref elements | Syndicator assigns. See 5.2.2.1 | Not referenced | 5.2.2.1 |
| subscription element ID | Unique within a subscription | subscription-element attribute on ice-item, ice-item-ref, ice-item-group elements | Syndicator assigns. See 5.2.2.1 |
subscription-element attribute on ice-repair-item, ice-item-remove elements | 5.2.2.1, 5.2.2.2, 5.2.2.3, 5.2.3 |
| item group ID | Unique across all group-items in a package | item-group-id attribute on ice-item-group element | Syndicator assigns. See 5.2.2.3 |
Not referenced | 5.2.2.3 |
| extension UUID | Universally Unique Extension identifier | UUID attribute on ice-extension element | Syndicator or Subscriber assigns. See 4.5.5 (ice-extension) | ICE application processor uses UUID to obtain an extension. | 4.5.5 8.4.1 |
| offer ID | Unique within the catalog of offers made by a Syndicator to a Subscriber. | offer-id attribute on ice-offer element | Syndicator assigns. | ICE processor MAY use it to verify received offers. | 4.3.2 |
| ID | Payload-wide (XML document) unique identifier | id attribute on ice-access, ice-negotiable, ice-range, ice-range-define, ice-span, ice-span-max, ice-span-min, ice-span-point, ice-default-value, ice-enum, ice-enum-item, ice-limit and ice-extension elements | Syndicator or Subscriber assigns. See 4.5 | ref attribute on ice-access, ice-span, ice-default-value, ice-span-max, ice-span-min, ice-span-point, ice-enum, ice-enum-item, and ice-limit | 5.2.2.2 4.5.2 4.5.3 4.5.4 4.5.5 |
Many attributes in ICE contain as values the identifiers described above and use them
to track and signal specific states in the syndication relationship. The table below
describes the attributes that contain the identifiers described in the table above.
| Attribute containing an Identifier |
Identifier Contained | Spec. Reference |
| sender-id | Syndicator's UUID or Subscribers UUID | 3.5.1 |
| receiver-id | Syndicator's UUID or Subscribers UUID | 3.5.2 |
| message-id | request-id or response-id | 3.3.2 |
| old-state | package-sequence-id | 5.1.4 |
| new-state | package-sequence-id | 5.1.4 |
| current-state | package-sequence-id | 5.3 |
| sequence-id | package-sequence-id | 5.5.2 |
| other-id | Syndicator's UUID or Subscribers UUID | 6.3 |
| ref | element identifier to access and use previously defined elements such as ice-span, ice-span-max, ice-span-min, ice-span-point, ice-default-value, ice-enum, ice-enum-item or ice-limit | 4.5.2 4.5.3 4.5.4 4.5.5 |
This section describes the date and time format used by ICE in all contexts where a parse-able 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 because of time zones (without a time attached to a Date it is hard to know exactly what the Date really means); see 3.3.5 for how to specify both in an ICE DateTime format. No fields defined by ICE have been defined to be "naked" dates; ICE always uses the DateTime format.
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). Note that ISO8601 and UTC support leap seconds, therefore implementations are required to support 60, 61 and 62 seconds. 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.
| Midnight has two Representations |
|---|
00:00:00 (midnight behind or current) 24:00:00 (midnight ahead -- i.e. 00:00:00 tomorrow ) |
Note alternatively, that 00:00:00 on one day is the same time as 24:00:00 on the previous day. This is deliberate, and in accordance with [ISO8601] section 5.3.2.
ICE Time Format for representing sub-second 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 sub second 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 symbolizes the sub second value. The number of digits in the sub second value, and the precision of the sub second 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 sub second 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 time stamp and then process it as best as the implementation can. Implementations SHOULD properly parse fractions with an arbitrary number of digits in the sub second value.
All times specified within ICE MUST be specified using Coordinated Universal Time (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 sub second granularity, the format is:
Pn,nS
i.e., using the same sub second 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:
| ice-code format |
| <!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 xml:lang CDATA #IMPLIED > |
An example would be:
| Ice-code example. |
|---|
<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:
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.4.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:
When receiving codes:
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 prerequisite 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.
7xx: Local Use Codes
These codes are reserved for use by the local ICE implementation and MUST NOT ever be sent to another ice processor over the transport medium. 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 format |
| <!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:
| ICE XML Document Type Declaration |
|---|
<?xml version="1.0"?> <!DOCTYPE ice-payload SYSTEM "http://www.gca.com/ICE/ICE1_1.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:
| ice-payload format |
| <!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 sender-location CDATA #REQUIRED ice.version CDATA #REQUIRED > |
A single ICE payload contains a header and either:
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.10 and will not be discussed further until then.
There are several attributes:
This construct is provided as a means to allow automatic version recognition as follows:
ICE versioning implements a Least Common Minor Version Numbering Concept. In the event of a presented ICE payload with an identical major version number and different minor version numbers, a receiver implementing this specification MUST respond to a sender with the semantics of the lesser value of the minor version numbers of both the sender and the receiver.
Therefore implementations of ICE version 1.1 must respond to senders implementing ICE
versions 1.0 (nee' 1.00) and 1.01 with semantics of 1.00 and 1.01 respectively (the lesser
of the minor versions implemented). A Sender and Receiver MUST NOT signal a
versioning error in an implementation with the same major version number and a different
minor version number. A Receiver MUST respond to a sender with the same major
version number and a different minor version number with the semantics defined by the ICE
specification with the smaller of the two minor version numbers. Thus, if the Receiver has
a larger minor version number than the Sender, then the Receiver must respond with the
semantics of the Sender. If the Receiver has a smaller minor version number than the
Sender, then the Receiver must respond with the semantics of its version. Similarly, if
the Sender receives a response from a Receiver with a smaller minor version (and identical
major version) then the Sender MUST operate any further protocol interactions with
the Receiver at the Receivers version level. A Receiver MAY signal an error
on payloads labeled with any other unsupported versions. See Appendix
B, section 5 for how to resolve the ice.version number using the protocol.
| Note | |
| for ICE interoperability | |
| This paragraph is intended to apply to ICE 1.0 implementations to bring them into conformance with the ICE versioning scheme. Strictly speaking, there is no way to enforce this behavior on preexisting implementations; but for continued ICE interoperability, they SHOULD conform. Specifically, ICE version 1.0 implementations SHOULD treat all ICE version 1.x versions AS IF they were 1.0 versions because all ICE 1.x versions MUST respond with ICE 1.0 semantics. |
| Informational Note | |
| for historical reference | |
| The ICE Authoring Group wishes to acknowledge the authors of the XML specification, from whom we copied (a |