[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 (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.
| ice-header, ice-sender, ice-receiver and ice-user-agent formats |
<!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.
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 sub elements 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 versus. unsuccessful code value, and the presence or absence of the results element, there are four combinations possible:
There are several attributes:
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:
| Package validation failure message. |
|---|
<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:
| Package validation failure message. |
|---|
<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-codemessage, 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 acknowledgments 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:
| Request |
|---|
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.gca.org/ice/dtds/ICE1_1.dtd"
>
<ice-payload
payload-id="1998-07-05T02:02:23@xyz.com"
timestamp="02:02:23,449"
sender-location="//www.gca.org/ice/syndication"
ice.version="1.1">
<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:
| Response |
|---|
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.gca.org/ice/dtds/ICE1_1.dtd"
>
<ice-payload
payload-id="1998-07-05T02:03:45@nr3.com"
timestamp="02:03:45,31416"
sender-location="//www.adobe.com/ice/atg/RICE/subscriber"
ice.version="1.1">
<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
Adam Souzis, CEO
</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:
| Request |
|---|
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.gca.org/ice/ICE1_1.dtd"
>
<ice-payload
payload-id="1998-07-05T03:03:34@sothebys.com"
timestamp="03:03:34,449"
sender-location="www.sothebys.com/ice/subscribers/number3?
sub=ArtNotes,user=laird.popkin"
ice.version="1.0">
<ice-header>
<ice-sender
sender-id="4af37b30-2c35-11d2-be4a-204c4f4f5020"
name="Sothebys, Inc."
role="subscriber"/>
<ice-user-agent>
Acme Ray Gun ICE System, V0.9beta
Laird Popkin, Chairman
</ice-user-agent>
</ice-header>
<ice-request
request-id="1998-07-05T03:03:34@sothebys.com-1">
<ice-nop/>
</ice-request>
<ice-request
request-id="1998-07-05T03:03:34@sothebys.com-2">
<ice-nop/>
</ice-request>
</ice-payload>
|
Response:
| Response |
|---|
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.gca.org/ice/ICE1_1.dtd"
>
<ice-payload
payload-id="1998-07-05T03:03:45@nr3.com"
timestamp="03:03:45,31416"
sender-location="http://www.nr3.com/ice/subscribers/sothebys?
subscr=ArtNotes,user=laird.popkin"
ice.version="1.1">
<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
Phil Gibson, Web Conductor
</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@sothebys.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@sothebys.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:
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.
| ice-unsolicited-now format |
| <!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:
Note that Syndicators MUST NOT ever send an ice-unsolicited-now to a Subscriber. This is discussed in more detail under 3.10.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:
| ice-unsolicited-request format |
| <!ELEMENT ice-unsolicited-request ( ice-change-subscription | ice-code | ice-get-events | 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:
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 asymmetric 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.10.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:
| ice-unsolicited-response format |
| <!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:
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.10.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:
Implementation note: the unsolicited message mechanism makes a good fall-back mechanism
for Syndicators to use when communication with their non-minimal Subscribers 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 ice-request and ice-response.
An alternative mechanism would have been to simply define additional requests for unsolicited messages and "tunnel" them within the existing ice-request and ice-response framework. There are two reasons why this wasn't done:
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 ice-request and a different one to solicit the unsolicited messages. The Authoring Group felt that the potential protocol optimizations here were not compelling enough to overcome the technical disadvantages imposed by generic tunneling of unsolicited messages. |
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.10.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 no-operation (ice-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:
| Subscriber sends NOP to Syndicator |
|---|
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.gca.org/ice/dtds/ICE1_1.dtd"
>
<ice-payload
payload-id="1998-07-22T02:02:23@cnet.com"
timestamp="02:02:23,449"
sender-location="http://www.cnet.com/ice/catalog/nr3?
user=Kimberley.Jones,subscr=HeadLines"
ice.version="1.1" >
<ice-header>
<ice-sender
sender-id="4af37b30-2c35-11d2-be4a-204c4f4f5020"
name="CNET Corporation"
role="subscriber" />
<ice-user-agent >
Acme Ray Gun ICE System, V0.9beta
Rick Levine, Web Ray Architect
</ice-user-agent>
</ice-header>
<ice-request
request-id="1998-07-22T02:02:23@cnet.com-1">
<ice-nop />
</ice-request>
</ice-payload>
|
(2) SUB <== SYN: Response with unsolicited-pending
The Syndicator responds to the no-operation and sets the unsolicited-pending flag:
| Syndicator sends response & unsolicited-pending flag |
|---|
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.gca.org/ice/dtds/ICE1_1.dtd"
>
<ice-payload
payload-id="1998-07-22T02:03:45@tms.com"
timestamp="02:03:45,31416"
sender-location="http://www.tms.com/ice/catalog/cnet?
user=Kimberly.Jones,subscr=Headlines"
ice.version="1.1" >
<ice-header >
<ice-sender
sender-id="4a2180c9-9435-d00f-9317-204d974e3410"
name="Tribune Media Services Corporation"
role="syndicator" />
<ice-user-agent >
Road Kill Systems ICE Processor, V17 patch 9
Brad Husik, Principal Product Purveyor
</ice-user-agent>
</ice-header>
<ice-response
response-id="1998-07-22T02:03:45@tms.com-1"
unsolicited-pending="true" >
<ice-code
numeric="200"
phrase="OK"
message-id="1998-07-22T02:02:23@cnet.com-1"
/>
</ice-response>
</ice-payload>
|
(3) SUB ==> SYN: ice-unsolicited-now
The Subscriber, having seen the unsolicited-pending flag, eventually sends an ice-unsolicited-now:
| Subscriber sends ice-unsolicited-now |
|---|
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.gca.org/ice/dtds/ICE1_1.dtd"
>
<ice-payload
payload-id="1998-07-22T02:03:55@cnet.com"
timestamp="02:03:55,449"
sender-location="http://www.cnet.com/ice/catalog/tms?
user=Kimberley.Jones,subscr=Headlines"
ice.version="1.1" >
<ice-header >
<ice-sender
sender-id="4af37b30-2c35-11d2-be4a-204c4f4f5020"
name="CNET Corporation"
role="subscriber" />
<ice-user-agent>
Acme Ray Gun ICE System, V0.9beta
Conleth O'Connell, Chief Ray Gun Architect
</ice-user-agent>
</ice-header>
<ice-unsolicited-now
request-id="1998-07-22T02:03:55@cnet.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.
| Syndicator sends unsolicited-requests |
|---|
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.gca.org/ice/dtds/ICE1_1.dtd"
>
<ice-payload
payload-id="1998-07-22T02:04:01@tms.com"
timestamp="02:04:01,31416"
sender-location="http://www.tms.com/ice/catalog/cnet?
user=Kimberly.Jones,subscr=Headlines"
ice.version="1.1" >
<ice-header >
<ice-sender
sender-id="4a2180c9-9435-d00f-9317-204d974e3410"
name="Tribune Media Services Corporation"
role="syndicator" />
<ice-user-agent >
Road Kill Systems ICE Processor, V17 patch 9
Neil Webber, Chief QOI Officer
</ice-user-agent>
</ice-header>
<ice-unsolicited-request
unsolicited-request-id="1998-07-22T02:04:01@tms.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@tms.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:
| Subscriber sends results in unsolicited-response |
|---|
<?xml version="1.0" ?>
<!DOCTYPE ice-payload
SYSTEM "http://www.gca.org/ice/dtds/ICE1_1.dtd"
>
<ice-payload
payload-id="1998-07-22T02:10:19@cnet.com"
timestamp="02:10:19,449"
sender-location="http://www.cnet.com/ice/tms?
user=Kim.Jones,sbs=Headlines"
ice.version="1.1" >
<ice-header >
<ice-sender
sender-id="4af37b30-2c35-11d2-be4a-204c4f4f5020"
name="CNET Corporation"
role="subscriber" />
<ice-user-agent >
Acme Ray Gun ICE System, V0.9beta
Andy Werth, Chief Ray Gunner
</ice-user-agent>
</ice-header>
<ice-unsolicited-response
unsolicited-response-id="1998-07-22T02:10:19@cnet.com-1">
<ice-code
numeric="200"
phrase="OK"
message-id="1998-07-22T02:04:01@tms.com-2"
/>
</ice-unsolicited-response>
<ice-unsolicited-response
unsolicited-response-id="1998-07-22T02:10:19@cnet.com-2">
<ice-code
numeric="200"
phrase="OK"
message-id="1998-07-22T02:04:01@tms.com-1"
/>
</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).
| Response to Unsolicited Messages Request |
|---|
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.gca.org/ice/dtds/ICE1_1.dtd"
>
<ice-payload
payload-id="1998-07-22T02:10:25@tms.com"
timestamp="02:10:25,31416"
sender-location="http://www.tms.com/ice/cnet?
usr=Kim.Jones,sbs=Headlines"
ice.version="1.1" >
<ice-header >
<ice-sender
sender-id="4a2180c9-9435-d00f-9317-204d974e3410"
name="Tribune Media Services Corporation"
role="syndicator" />
<ice-user-agent >
Road Kill Systems ICE Processor, V17 patch 9
Phil Gibson, Chief Implementation Officer
</ice-user-agent >
</ice-header >
<ice-response
response-id="1998-07-22T02:10:25@tms.com-1" >
<ice-code
numeric="200"
phrase="OK"
message-id="1998-07-22T02:10:19@cnet.com-1"
/>
</ice-response >
<ice-response
response-id="1998-07-22T02:10:25@tms.com-2" >
<ice-code
numeric="200"
phrase="OK"
message-id="1998-07-22T02:10:19@cnet.com-2"
/>
</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.
| Unsolicited Now Message |
|---|
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.gca.org/ice/dtds/ICE1_1.dtd"
>
<ice-payload
payload-id="1998-07-22T02:23:55@cnet.com"
timestamp="02:23:55,449"
sender-location="http://www.cnet.com/ice/tms?
usr=Kim.Jones,sbs=Headlines"
ice.version="1.1">
<ice-header>
<ice-sender
sender-id="4af37b30-2c35-11d2-be4a-204c4f4f5020"
name="CNET Corporation"
role="subscriber" />
<ice-user-agent >
Acme Ray Gun ICE System, V0.9beta
Diane Kennedy, Chief Technology Officer
</ice-user-agent >
</ice-header>
<ice-unsolicited-now
request-id="1998-07-22T02:23:55@cnet.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:
| No more unsolicited messages |
|---|
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.gca.org/ice/dtds/ICE110.dtd" >
<ice-payload
payload-id="1998-07-22T02:24:45@tms.com"
timestamp="02:24:45,31416"
sender-location="http://www.tms.com/ice/cnet?
usr=Kim.Jones,sbs=Headlines"
ice.version="1.1"
>
<ice-header>
<ice-sender
sender-id="4a2180c9-9435-d00f-9317-204d974e3410"
name="Tribune Media Services Corporation"
role="syndicator"
/>
<ice-user-agent>
Road Kill Systems ICE Processor,V17 patch 9
Sami Khoury, Chief Technology Officer
</ice-user-agent>
</ice-header>
<ice-response
response-id="1998-07-22T02:24:45@tms.com-1">
<ice-code numeric="604"
phrase="No more unsolicited messages"
message-id="1998-07-22T02:23:55@cnet.com-1"
/>
</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 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 content exchange 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 format |
<!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 format |
<!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
min-update-interval CDATA #IMPLIED
max-update-interval CDATA #IMPLIED
minfreq CDATA #IMPLIED
maxfreq CDATA #IMPLIED
min-num-updates CDATA #IMPLIED
max-num-updates CDATA #IMPLIED
mincount CDATA #IMPLIED
maxcount CDATA #IMPLIED
url CDATA #IMPLIED
>
|
The ice-negotiable element is described in 4.2.3.. It designates those parameters that are available for negotiation as described in section 4.5.
The attributes of ice-delivery-rule are:
All of these attributes are conceptually joined with "AND" (not "OR"). That is, within a single delivery-rule, the valid delivery times are those times that satisfy all the restrictions listed in the attributes within the rule.
Additional Definitions
To explain the interaction of the attributes, a few additional terms must be defined:
Given the above definitions, the following algorithm shows one way of computing the SelectedDays in an ice-delivery-rule. ICE implementations MUST function AS-IF they work this way:
Any days remaining are the SelectedDays.
NOTE: This might be an empty set, in which case the ice-delivery-rule is a no-op. For example, if startdate is Feb 1, 1999, stopdate is Feb 28, 1999, and monthdayis 31 then the set of SelectedDays is empty.
The SelectedTimeWindow of each SelectedDay can then be determined as follows:
The semantics of max-num-updates and min-num-updates can now be more fully defined:
max-num-updates controls the number of deliveries that are permitted in any single SelectedTimeWindow. In a pull subscription, this is a way for the Syndicator to tell the Subscriber "don't ask me for updates more than this many times per SelectedTimeWindow". For push subscriptions, this is a way for the Syndicator to tell the Subscriber that it will not push more than that many times in a single SelectedTimeWindow.
Similarly, min-num-updates controls the minimum number of deliveries that are required in any single SelectedTimeWindow. For example, a min-num-updates equal to two in a pull subscription is an instruction from the Syndicator to the Subscriber asking the Subscriber to poll at least twice during each SelectedTimeWindow.
max-update-interval is a maximum time interval (refer to its definition above). This definition applies during each individual SelectedTimeWindow and controls how often, during a single SelectedTimeWindow, a Subscriber must poll (for pull subscriptions) or how often a Syndicator must push (for push subscriptions). In the case of pull, a Subscriber SHOULD NOT allow more than the max-update-interval interval to elapse in any single SelectedTimeWindow without generating an ice-get-package request to the Syndicator (this is a "should not" instead of a "must not" because exigent circumstances on the Subscriber side can, of course, lead to the Subscriber being unable to meet the constraint; how a given Syndicator reacts in such cases is a quality-of-implementation issue). Similarly, in the case of push, a Syndicator SHOULD NOT allow more than the max-update-interval interval to elapse in any single SelectedTimeWindow without generating a new push to the Subscriber.
min-update-interval is a minimum time interval (refer to its definition above). This definition applies during each individual SelectedTimeWindow and controls how often, during a single SelectedTimeWindow, a Subscriber may poll (for pull subscriptions) or how often a Syndicator may push (for push subscriptions). In the case of pull, a Subscriber SHOULD NOT attempt an ice-get-package within a single SelectedTimeWindow if the time interval to the previous ice-get-packagein the same SelectedTimeWindow is less than the min-update-interval value. Note: this is a "should not" instead of a "must not" because exigent circumstances on the Subscriber can, of course, lead to the Subscriber wanting to violate this constraint; how a given Syndicator reacts in such cases is a quality-of-implementation issue. Similarly, in the case of push, a Syndicator SHOULD NOT attempt a push if insufficient time (as defined by the min-update-interval value) has elapsed since the last push in the same SelectedTimeWindow.
Note that both max-update-interval and min-update-interval apply only within a single SelectedTimeWindow. There is no history across SelectedTimeWindows. Thus, for example, if min-update-interval is P3600S (one hour), and there are two adjacent 24-hour SelectedTimeWindows, it is entirely possible for one delivery to occur at 23:59:59 in the first SelectedTimeWindow, and for the second to occur at 00:00:01 in the second -- i.e., two deliveries separated by only a few seconds, even though the min-update-interval value seems to imply a one hour separation requirement. The intervals specified by max-update-interval and min-update-interval only apply within a single SelectedTimeWindow.
If there is a conflict between the intervals (min-update-interval and max-update-interval) and update numbers (min-num-updates and max-num-updates) parameters, the intervals takes precedence.
Putting it all together in a single example: consider a subscription in which updates could occur:
The delivery policy would look like:
| Delivery Span Example |
|---|
<ice-delivery-policy startdate="1998-07-02T12:00:00">
<ice-delivery-rule
mode="pull"
starttime="02:00:00"
duration="P7200S"
max-num-updates="1"
/>
<ice-delivery-rule
mode="pull"
starttime="09:00:00"
duration="P28800S"
weekday="1 2 3 4 5"
min-update-interval="P1800s"
/>
<ice-delivery-rule
mode="push"
url="http://www.acme.com/ice-in/"
/>
</ice-delivery-policy>
|
In the ice-delivery-rule, the ice-negotiable elements describe which pieces of the ice-delivery-rule are subject to negotiation (see section 4.5). The format is:
| ice-negotiable format |
<!ELEMENT ice-negotiable ( ice-text | ice-range )* >
<!ATTLIST ice-negotiable
min CDATA #IMPLIED
max CDATA #IMPLIED
id ID #IMPLIED
type ( ice-extension |
ice-operation |
x-domainname-categoryname |
ice-categoryname |
monthday | weekday |
startdate | stopdate |
starttime | duration |
minfreq | maxfreq |
mincount | maxcount |
min-update-interval |
max-update-interval |
min-num-updates |
max-num-updates
) #REQUIRED
>
|
<!ELEMENT ice-text ( #PCDATA ) > <!ATTLIST ice-text xml:lang #IMPLIED > |
The ice-negotiable element defines parameters that are explicitly negotiable. It also defines the negotiating range of the parameter values so that mutually acceptable values can be rapidly achieved. This element is the basis of parameter negotiation and is used in an ice offer (described below) to assist in the selection of desired subscriptions and then to adjust their parameters for mutually acceptable content interchange.
Ice 1.0 and 1.01 required that ice-negotiable be an empty element; Ice 1.1, for compatibility, permits an empty element but includes an ice-range and ice-text to identify and describe both built in operational parameters and extended ice-extension parameters. The ice-range is intended to replace and augment the plethora of subscription operational parameters that are defined on the type attribute (e.g. monthday,...). While these parameters and the associated min and max values are still acceptable, their use is deprecated. They are scheduled for removal in the next major version of ICE and are included here only for inter operability and compatibility according to Appendix B.
The optional ice-text element is intended to contain a textual description of the collection of negotiable parameters. It has a single attribute:
The optional ice-range element is defined in section 4.5.2 below. It defines negotiable parameters and their ranges.
The attributes for ice-negotiable are:
| Num | type attribute value | Attribute "type" Meaning |
| 1 | ice-operation | The set of parameters described by this ice-negotiable are built-in ICE operational parameters. These are subscription operational parameters defined by the ice-delivery-rule and section 4.5.7. |
| 2 | ice-extension | The set of parameters described are extensions; either at the subscription or protocol level. |
| 3 | ice-categoryname | Reserved name tokens beginning with "ICE-", "iCE-", IcE-, icE-, ...., "ice-" for future standardization. Implementations MUST NOT use any categorynames other than parameter or extension. |
| 4 | x-domainname-categoryname | Defines non-conflicting name category for experimental or private use. "Domainname" is the extender's domain and "categoryname" is an NMTOKEN. |
| 5 | monthday, weekday, startdate, stopdate, starttime, duration, minfreq, maxfreq, mincount, maxcount, min-update-interval, max-update-interval, min-num-updates, max-num-updates | Deprecated. Use an ice-range element instead. This attribute is intended to be removed in a future version of ICE and is only included for compatibility and minor-version interoperability. It identifies the built-in operational parameter being negotiated. |
A catalog contains subscription offers. A Subscriber typically begins an ICE
relationship by obtaining the catalog of subscription offers from the Syndicator. This
section defines the format of the catalog and the protocol operations for obtaining a
catalog.
| Informational Note | |
| for historical reference | |
| The notion of the ice-catalog is completely separate from the concept of "browsing a site to find things you might want to subscribe to." HTML based Web pages are a more appropriate way for Syndicators to advertise their offerings and to guide potential Subscribers through the process of selecting an offering. Indeed, some of the manual steps outlined regarding how a Syndicator and a Subscriber first contact each other and exchange relevant authentication data might be automated using HTML, JavaScript, applets, etc. The ice-catalog is simply the way that the ICE tool first obtains a set of offers that it can use to establish a subscription; browsing an ice-catalog is not intended to take the place of browsing a Web site. |
An ice-catalog has the following format:
A catalog consists contact information, and zero or more ice-offer elements or groups of ice-offer elements. Each ice-offer contains a proposed set of parameters for a subscription.
An ice-catalog has the following attributes.
Contact information is used for aiding human-to-human communication. The body of the element SHOULD contain human-readable text describing the primary points of contact. There are also several attributes:
An ice-offer-group is simply a convenient way to organize a set of offers together in a way that might make sense to the Subscriber when viewing the catalog (i.e., the Subscribers ICE tool might provide a tree-view of this data).
| ice-offer-group format |
<!ELEMENT ice-offer-group
( ice-offer-group+ | ice-offer+ )
>
<!ATTLIST ice-offer-group
description CDATA #REQUIRED
>
|
The only attribute is:
The format of the ice-offer structure is shown here:
| ice-offer format |
<!ELEMENT ice-offer ( ice-delivery-policy,
ice-business-term* ) >
<!ATTLIST ice-offer
offer-id CDATA #IMPLIED
constraints-hash CDATA #IMPLIED
constraints-hash-method CDATA #IMPLIED
constraints-url CDATA #IMPLIED
description CDATA #REQUIRED
product-name CDATA #IMPLIED
subscription-id CDATA #IMPLIED
rights-holder CDATA #IMPLIED
expiration-date CDATA #IMPLIED
atomic-use (false | true) "false"
editable (false | true) "false"
ip-status CDATA #IMPLIED
showcredit (false | true) "false"
usage-required (false | true) "false"
type (protocol | subscription ) "subscription"
quantity CDATA #IMPLIED
expiration-priority (first | time |
quantity | last) "first"
>
|
An offer contains a delivery policy, defined previously, and a possibly empty set of negotiable parameters and business terms (defined below). An offer has the following attributes:
| Case | Description |
|---|---|
| 1 | When an offer appears in an ICE catalog, there is no subscription yet established and therefore a subscription-id MUST NOT be present. |
| 2 | When an offer is used in a negotiation before a subscription is established, there is no subscription and therefore a subscription-id MUST NOT be present. |
| 3 | When an offer appears in an ice-status, the subscription-id must be present. |
| 4 | When an offer is used to renegotiate an existing subscription, the subscription-id must be present. |
Business terms provide the means for additional content and parameters to be communicated and negotiated between the parties; both for specific subscriptions as well as for more general properties of the relationship.
The ice-business-term element is:
| ice-business-term format |
<!ELEMENT ice-business-term ( #PCDATA |
ice-text |
ice-negotiable
)*
>
<!ATTLIST ice-business-term
xml:lang CDATA #IMPLIED
type ( credit |
licensing |
payment |
reporting ) #REQUIRED
url CDATA #IMPLIED
name CDATA #IMPLIED
id CDATA #IMPLIED
>
|
Business terms contain optional plain text, text elements and negotiable parameters as content. The text and the text elements may be used to communicate additional information about the subscription that is not directly germane to subscription delivery; but enhances and clarifys additional aspects of the content such as usage limitations, or additional licensing terms.
The meaning and use of negotiable parameters in an ice-business-term are not constrained by the ICE protocol. However, ICE's negotiation mechanism MUST be used to arrive at mutually acceptable values for parameters defined by every ice-negotiable appearing as content in an ice-business-term . If negotiation of ice-negotiable parameters fails (i.e results in a "sorry" ice-code), the ice-offer containing the ice-business-term fails in the sense that no subscription is established.
The attributes are:
| Num | type attribute value | Attribute "type" Meaning |
| 1 | credit | Refers to the type of acknowledgement required when using the content. Note that ICE makes no further requirements about credit. The party making the offer (usually a syndicator) MAY choose to provide parameters in this category that MAY or MAY NOT be negotiable. |
| 2 | licensing | Refers to the general terms of licensing. Note that ICE makes no further requirements about licensing. The party making the offer (usually a syndicator) MAY choose to provide parameters in this category that MAY or MAY NOT be negotiable. |
| 3 | payment | Payment refers to the cost and payment terms expected when using the content. Note that ICE makes no further requirements about payment. The party making the offer (usually a syndicator) MAY choose to provide parameters in this category that MAY or MAY NOT be negotiable. |
| 4 | reporting | Refers to the end-user usage statistics expected when content is used. Note that ICE makes no further requirements about reporting (but see logging). The party making the offer (usually a syndicator) MAY choose to provide parameters in this category that MAY or MAY NOT be negotiable. |
| 5 | usage | Refers to the uses that the content may be put. Note that while ICE currently makes no further requirements about usage, this area is a likely subject for future standardization. The party making the offer (usually a syndicator) MAY choose to provide parameters in this category that MAY or MAY NOT be negotiable. |
Subscribers can use ice-get-catalog to obtain the list of subscription offers for which they are eligible. The format is:
| ice-get-catalog format |
| <!ELEMENT ice-get-catalog EMPTY > |
The return response is an ice-catalog.
Typically, the Syndicator will look at the sender-id field in the header to determine who the Subscriber is; if the syndicator doesn't recognize the particular Subscriber the Syndicator MAY return a 405 (Unrecognized sender) error code, or MAY choose to allow the request anyway. Allowing the request anyway is a policy decision made by the Syndicator as to whether anonymous catalog browsing is permitted.
Note that Subscribers are not required to perform any ice-get-catalog operations, ever. The only requirement is that eventually a Subscriber knows how to fill in an ice-offer request to establish a subscription. It is possible, for example, for the parameters for filling in that ice-offer to come from some other out-of-band mechanism such as an HTML/JavaScript application.
A Subscriber uses the ice-offer request to establish a subscription. Typically, a Subscriber will use ice-get-catalog to get a catalog, take one of the ice-offers from that catalog, prioritize the parameters and send it back to the Syndicator in a request. However, the Subscriber is free to create an ice-offer in any implementation-defined manner it wants. For example, a Syndicator might e-mail an ice-offer to a Subscriber, who could then feed it to their ICE tool and begin protocol processing here.
After the Subscriber sends the offer to the Syndicator, the Syndicator can respond in one of four ways:
The simplest success case for establishing a subscription is for the Subscriber to issue an ice-offer request, and the Syndicator to respond with a 200 (OK) code. If the Syndicator responds with a negotiation response (code 440 or 441), the Subscriber SHOULD enter into the parameter negotiation protocol as outlined in section 4.5
ICE encourages many aspects of a subscription's operation to be managed through the negotiation of parameters. This provides a means for Syndicator and the Subscriber to reach mutually agreeable subscription operation.
The model, described in this section, also permits a Syndicator or Subscriber to define and negotiate other parameters of importance to both the subscription, and the Syndicator/Subscriber relationship. The model also permits semantic extension. Generalized parameter negotiation is defined and explained in below. The use of parameter negotiation to extend ICE is described in section 8,below.
It is important to understand that this negotiation model is for protocol level parameter negotiation; it is not an attempt to automate the arcane and baroque nature of human-to-human business deal negotiation.
In previous versions of ICE, the parameters described in an ice-negotiable element was a hint, not a mandate. If a Subscriber wished to try negotiating an attribute not listed in an ice-negotiable, the Subscriber COULD do so, and the Syndicator COULD choose to accept the negotiated value. Similarly, a Subscriber COULD choose to attempt to negotiate a value outside the range, if one is specified. The intent of ice-negotiable was simply to give guidance to the Subscriber negotiation implementation. This behavior is specifically deprecated and should be used only for interoperability with existing ICE minor versions prior to 1.1.
In ICE 1.1 and above, a formal means for specifying additional parameters for negotiation is provided as well as the process to negotiate them. As a result, the "hint" nature of ice-negotiable has been replaced with a formal mechanism. Therefore, to assure interoperability, a Subscriber MUST abide by the restrictions it describes, because a Syndicator MUST NOT accept a negotiated value outside the described ranges. While almost any set of parameters may be negotiated according to the process in section 4.4.6 below, the process is much more tightly defined. Specifically, the negotiating range is explicit and it is an error to suggest values outside the offer range.
ICE supports negotiation for the following types of parameters:
These parameters are outside the operation of the ICE protocol. Their effect on the operation of the subscription are secondary to the subscription operational parameters and typically only apply to a single subscription. The ice-business-term element is used to negotiate these parameters. Subscribers and Syndicators are expected to either understand these parameters or refuse subscription offers that contain them. ICE assumes that the Syndicator and Subscriber have external knowledge of how to use these parameters. They were defined in section 4.3.3 above.
The flow of negotiation in ICE is based on the exchange of ice-offer elements. Each ice-offer is simply a set of parameters that the Sender would like to have the Receiver accept.
The response to a proposal can be one of three things:
The Subscriber drives the entire negotiation process. Negotiation begins with the Subscriber making an ice-offer request to the Syndicator. (But note that the Subscriber typically obtains the offer from a catalog of offers provided by the Syndicator.) The Syndicator then does one of three things:
If the Subscriber receives a counter proposal, the Subscriber MAY update the ice-offer or try another ice-offer, either with the contents of the counter proposal received from the Syndicator, or with some other mixture of parameters. The method of choosing what parameters to alter, while a quality of implementation issue is controlled by negotiation rules described in Section 4.5.5.
If the Subscriber receives a Sorry response, the Subscriber MAY try again with some other ice-offer, although the Syndicator has (unhelpfully) not given any clues as to what to try.
A Subscriber implementation MAY choose to never negotiate, simply always accepting the parameters proposed by the Syndicator. Such an implementation is called the Trivial negotiation implementation, and the protocol has been carefully designed to allow such implementations to exist and be conforming.
To Subscribe to a subscription, a Trivial Negotiation implementation simply obtains an offer using ice-get-catalog. It then picks an offer from the catalog. There might be multiple offers to choose from, especially if the Syndicator is equipped with negotiation logic. A Trivial implementation SHOULD just pick an offer and send it to the Syndicator in an ice-offer request.
Ignoring error conditions, which would be handled the usual way, there are three possible outcomes:
Thus, the minimal message flow in a trivial negotiation is:
If there is one round of negotiation, it looks like this:
Another scenario would be the Syndicator rejecting an offer with a simple "Sorry". Note that this can happen even if the offer came from the catalog (as already discussed). This would look like this:
As mentioned, even a trivial implementation SHOULD implement some form of policy that limits the number of times the negotiation loop will be executed. A Syndicator SHOULD update the catalog to select more acceptable parameters in offers in support of trivial subscriber implementations.
Any implementation that does more than what is described for the trivial implementation is, by definition, a non-trivial negotiation implementation. Section 4.4.6 defines the resolution mechanism for non-trivial negotiation. This mechanism is designed to rapidly resolve parameter ranges to mutually acceptable values with a minimum of request/response interaction.
What distinguishes a non-trivial negotiation implementation from a trivial one is its ability to create counter proposals on its own. The most useful application of this technique for subscription operation is in the area of delivery schedules. Consider a push-based subscription. The Syndicator software can implement load balancing by attempting to spread delivery times around the hour. A Subscriber with many subscriptions might wish to do the same thing. Thus, the first delivery schedule proposed by a Syndicator might not be one that the Subscriber wishes to accept. A non-trivial negotiation implementation on the Subscriber would ignore the Syndicators schedule proposal and offer its own preferred proposal.
The implementation rules defined in Section 4.4.6 are designed to increase the probability of a successful negotiation outcome. These rules implement the following principles:
A parameter proposal under negotiation MUST change, be accepted, or result in a "Sorry" response.
To assure rapid, predictable arrival at a mutually agreeable offer, ICE defines rules for all negotiations to proceed. These rules are designed to produce a mechanical step by step parameter resolution process. They are not designed to follow any specific style of human negotiation nor any economic model of negotiation. As stated in section 4.4, It is important to understand that this negotiation model is for protocol level parameter resolution; it is not an attempt to automate the arcane and baroque nature of human-to-human business deal negotiation. These rules provide a rapid, predictable means for converging on a set of parameters in ICE; regardless of what the parameters are. Either a mutually acceptable offer is achieved or a "sorry" is achieved.
Parameter negotiation occurs by constrained convergence. An offer is updated by each party and sent to the other for consideration. Each updated offer's parameter ranges MUST be no greater than previous offers and MUST include the default (acceptable) value. If the range does not get smaller (i.e. have fewer enumeration items to select from; or a span's interval does not decrease) after an initial attempt, a response, and an identical second attempt, the negotiation is at an impasse and the receiving party of the second attempt MUST either decrease the parameter range and potentially alter the default or abandon the offer with a "sorry" response.
For example, one party to a negotiation is willing to negotiate a parameter called price in the range of $10 to $20 with a default price of $20; the other party must eventually come back with an new offer above or at $10. If the other party comes back with an $11 offer, then the first party must eventually come back with an offer under $20 and change the default as well. (The first party can always say "sorry" if it finds the negotiation unacceptable; but then, it would likely have setup the offer with a more acceptable range earlier.) Note that the first party could, for example, change the service level that is negotiated later to a lower quality in order to give a price that is acceptable now.
Resolving multiple parameters to concrete (completion) occurs on a parameter by parameter basis in the order defined by the originating offer. The first term in the offer is negotiated first and so on in lexical order. There is NO requirement that a protocol interchange occur on each parameter. A receiver can accept any number of terms and make them concrete by accepting the default value(s) provided by the sender. However, these parameters are examined and accepted in order of appearance. For example, suppose that a sender, say Tom, sends an offer that consists of k parameters, say P1, P2, ..., Pi, Pi+1, Pi+2 ...,Pk. And suppose the receiver, say Jerry, accepts the default values from P1 through Pi, (thus resolving the first i parameters) but chooses a non-default value for Pi+1 (thus indicating negotiation of Pi+1) and accepts the default values for Pi+2 through Pk. Jerry then returns the updated offer to Tom for the next round of negotiation. The original sender, Tom, MUST accept P1 through Pi and is not only free to negotiate parameter, Pi+1, but also to reset any of the Pi+2 through Pk to ranges that don't exceed the ranges in the original offer.
The motivation for this mechanism is that negotiation typically is organized in a most important to least important priority order. Thus, negotiation over an earlier parameter may affect the willingness to negotiate on later parameters. The level of this willingness is embedded in the rule that allows a later parameter range to be adjusted (within the agreed upon bounds) based on earlier parameter negotiation.
The order of parameters set by the subscriber in the originating offer is the order in which the negotiation proceeds. While the syndicator may set the offer in a catalog, the order of negotiation is set by the subscriber -- since the subscriber is the one that makes the originating offer. A subscriber MAY, but is not required to, obtain an offer from a Syndicator's catalog.
Once a parameter is made concrete {i.e. has an agreed upon (possible set of) values)}; it is no longer available for negotiation. A participant cannot re-open a concrete parameter for negotiation without terminating the current offer negotiation and re-initiating the entire negotiation.
A parameter is concrete when it has been accepted by both sides. Selecting the default value is a clear indication of acceptance.
Parameter's not yet negotiated MAY have their ranges diminished as the result of a current negotiation by either side.
During the negotiation process, no range can be increased. This means that the "width" of a span can only be decreased. This could mean, for example, that a price range could be changed from say $10 to $20 to say $15 to $20. Similarly, the number of enumerations offered stays the same or decreases.
A parameter is made concrete or completed, when the default values and the ranges match; as well as satisfying the original selection requirement on both sides of the negotiation. This means that once agreement is obtained, negotiation is complete for that parameter and can move on to the next parameter.
Negotiation has been augmented such that more fine-grained parameters may be expressed and negotiated. There are three types of parameters:
The mechanism for arbitrary parameter negotiation permits subscription and protocol-level extensions as well. These extension mechanisms are described in detail in section 8.3 and section 8.4; while the details of all parameter negotiation is described below.
The ice-negotiable element may contain an ice-range element. An ice-range in turn, contains one or more elements specifying enumerations and spans. For example:
| Example Ice-negotiable |
|---|
<ice-negotiable id="tape_format" type="ice-extension">
<ice-range name="tape selection">
<ice-text>Please select a tape format and length.</ice-text>
<ice-enum id="format" name="tape format" select="1">
<ice-default-value> beta </ice-default-value>
<ice-enum-item> beta </ice-enum-item>
<ice-enum-item> vhs </ice-enum-item>
<ice-enum-item> hi-8 </ice-enum-item>
</ice-enum>
<ice-span id="length" name="tape length" select="1">
<ice-default-value> 60 </ice-default-value>
<ice-span-min> 60 </ice-span-min>
<ice-span-max> 120 </ice-span-max>
</ice-span>
</ice-range>
</ice-negotiable>
|
There are several things to note from this example.
First, the "type" attribute of the ice-negotiable node is set to ice-extension. This is done largely for backwards compatibility with minor versions (1.0 and 1.01) of the ICE specification. None of the other valid values for this attribute apply, so "ice-extension" is used to indicate the presence of extended, domain-specific data.
Second, the negotiation block contains two negotiable parameters: a video tape format and a desired length. The available formats are expressed as an enumeration of strings which are expected to have meaning to the syndicator and subscriber. The lengths are expressed as a span, but note that the value need not be numeric. A minimum value of "Monday" and a maximum value of "Friday" are also valid. In both cases, a default value is specified.
According to the semantics of offer negotiation (section 4.4), if the offer falls within the subscribers operating constraints, the offer is accepted. Otherwise, a counter-offer is produced and sent to the syndicator. The purpose of the id attributes are provided so that elements in a negotiation containing multiple parameters with associated spans and enumerations are uniquely identifiable.
A third important point in the above example is the "select" attribute of the ice-enum element, which specifies the number of contained items that MUST be selected. In the example above, this value is 1, but the attribute may take on any positive integer value as well as the tokens "one-or-more", "zero-or-more", and "zero-or-one".
The power of this selection facility will become more apparent in the section 8, where the parameter negotiation mechanism is used to negotiate the use of extensions themselves.
An ice-range provides a set of values that define the range that a parameter may assume for negotiation. A parameter is resolved to an accepted set of values (or a single value) using the parameter negotiation process defined in this section.
| ice-range format |
<!ELEMENT ice-range ( ice-range-define?,
ice-text?,
(ice-span | ice-enum)+
)
>
<!ATTLIST ice-range
id ID #IMPLIED
name CDATA #IMPLIED
description CDATA #IMPLIED
order ( numeric |
lexical |
time |
enumeration
) "numeric"
>
|
The attributes for ice-range are:
| No. | Attribute "order" value | Attribute "order" Meaning |
| 1 | numeric | Content is interpreted numerically using a decimal integer constant as defined in the ANSI C Standard or a floating constant as defined in the IEEE 754 floating point standard. All implementations MUST support at least 18 decimal digits for decimal integer constants and IEEE 754 Double format for floating constants. Whenever two numeric values are to be compared and one of the values is a floating constant, then the other value is converted to an IEEE Double value ( using the IEEE default rounding mode, round to nearest.) prior to the comparison. |
| 2 | lexical | Content is interpreted as unicode strings (with the then current encoding) with leading and trailing whitespace removed. Whenever two lexical values are to be compared, the Unicode characters are compared lexically character by character indexed from zero and incrementing by one to the last character of the string with fewest characters. Indexing terminates at the first unequal comparison and the lexical comparison result is returned. If the characters compare equal up to the string with fewest characters, the longer (other) of the two strings is determined to be the greater of the two and that result is returned; otherwise the two strings are equal and that result is returned. |
| 3 | time | Content is in ICE Date format ( Section 3.2.1), ICE Time format ( Section 3.2.2), ICE Date and Time format ( Section 3.2.3), or ICE duration format( Section. 3.2.6). Whenever two time values are to be compared, they must be in the same ICE format. If two time values to be compared differ in format, an ICE 458 error code ( Time formats incompatible for comparison ) is returned. |
| 4 | enumeration | Content is an ice-enum. Values must be an ice-enum-item.
Whenever two enumeration values are compared, the ordering of the enumeration items
follows the sequential ordering of the appearance of the items in the ice-enum.
Thus, if an enumeration is defined with the ice-enum-items appearing in order e1,
then e2, then e3, and so on through ek, the ordering is e1 < e2 < e3
< ... < ek. Thus, an enumeration such as [ Sunday, Monday, Tuesday, Wednesday,
Thursday, Friday, Saturday ] has the natural ordering so that a span from Tuesday through
Friday makes sense. When an enumeration is referenced in a later defined span, Spans from a larger to a smaller value are assumed to follow modular ordering such that the span proceeds from the minimum value in the span (which must be one of the values in the referenced enumeration) up through the next larger value in the referenced enumeration until terminated by the maximum value of the span or until the largest value of the referenced enumeration. It then continues from the smallest value of the referenced enumeration up to the maximum value of the span. Thus, Spans assume that enumerations follow modular ordering rules. So, a span from Thursday through Tuesday means [ Thursday, Friday, Saturday, Sunday, Monday, Tuesday ] even though Sunday is less than Saturday. |
The Ice-range-define element provides range definitions for later use in parameter negotiation. It contains, ice-span and ice-enum definitions that may be used later.
| ice-range-define Format |
<!ELEMENT ice-range-define ( ice-span | ice-enum )+ >
<!ATTLIST ice-range-define
id ID #IMPLIED
name CDATA #IMPLIED
description CDATA #IMPLIED
>
|
The attributes for ice-range-defines are:
An ice-range-define is a container for a declaration of ranges that may be used during negotiation. Each ice-span or ice-enum> is declared with an XML ID that uniquely defines the range in the payload. This ID may then be referenced for use in negotiating a parameter value and/or limiting a future choice set.
An ice-span is used to provide a range of numerical values from which to select a specific value using the negotiation process. Negotiation proceeds by narrowing the range until a single (point) value is determined. An ice-span is resolved or "complete" when a single point value is determined.
An ice-span MUST contain an ice-default-value. In a negotiation, this value is set by the sender when the status attribute has value "negotiable" or "required" to indicate the acceptable "resolved" value of the negotiation for this parameter. A receiver accepts the value by sending the identical value back in the ice-default-value provided that it has accepted every preceding parameter default value as being indicated with a status attribute value of "accepted". It also changes the status attribute on this parameter to "accepted". In the case of the first default value, the receiver has accepted the "empty" preceding parameter default value. These rules mean that that receivers accept values in physical presentation order. Once a senders default parameter value is accepted, the sender and receiver MUST NOT change the value of the parameter during the remaining negotiation. Further, the default value is the value for the parameter used by the Syndicator and Subscriber until it is (later) renegotiated or the subscription is terminated. An accepted value for a parameter resolves the parameter.
An ice-span contains an optional ice-span-min, zero or more intermediate ice-span-points, and an optional ice-span-max.
The ice-span-min defines the minimum value for the range of values. The default-value MUST NOT be less than ice-span-min using the ordering relation from the order attribute. Detection of a default value less than ice-span-min results in a Span selection out of range error (453).
The ice-span-max defines the maximum value for the range of values. The default-value MUST NOT be greater than ice-span-max using the ordering relation from the order attribute. Detection of a default value greater than ice-span-max results in a Span selection out of range error (453).
The ice-span-points define intermediate values for the range. An ice-span-point value MUST NOT be less than the value of ice-span-min and MUST NOT be greater than the value of ice-span-max. Detection of an ice-span-point that exceeds ice-span-max or is less than ice-span-min results in an Invalid ice span code (457). These values identify limits of the span during negotiation. They effectively partition an ice-span into an set of sub-spans. Two ice-span-points that have equal values are redundant but not prescribed and may be used interchangeably.
ice-span [---------+-----+--------+-------+--------+-----------] | | | | | | | min p1 p2 p3 p4 p5 max |
An ice-span that contains an ice-span-min without an ice-span-max means that the sender is prepared to consider any value above or equal to the value of ice-span-min. Note that from an implementation perspective, the maximum value that must be supported is defined as the maximum IEEE 754 double value. (Note that +Infinity could also be supported.)
An ice-span that contains an ice-span-max without an ice-span-min means that the sender is prepared to consider any value below or equal to the value of ice-span-max. Note that from an implementation perspective, the minimum value that must be supported is defined as the minimum IEEE 754 double value. (Note that -Infinity could also be supported.).
An ice-span that contains both an ice-span-min and an ice-span-max means that the sender is prepared to consider any value above or equal to the value of ice-span-min and below or equal to the value of ice-span-max.
For efficiency, the precision of a numerical value of the default value of a span determines the precision of any intermediate values computed. For example, integer precision on a default value means that intermediate values in the span are integral. Consider the following cases:
A consequence of these rules is that a negotiator SHOULD consider carefully the precision of the default value when negotiating a parameter value. A default value of 7.000 for a span computes with far more precision than with a default value of 7. These rules are used when computing spans defined for an ice-enumeration.
A number of error responses are possible from an ice-span. An "Invalid Reference" 452 error is returned when a ref attribute value references a non-existent element. A "Span selection out of range" 453 error response is returned when a ice-default-value or an ice-span-point is set with a value that exceeds the maximum or is less than the minimum value of the span. If the span has been limited to a union of sub-spans, this error can also occur when a value is specified that is not in the union of sub-spans. A "Time formats incompatible for comparison" 458 error response is returned if the span the time formats of the structural elements differ in type of time format (ice-time, ice-date or duration). A "Limit invalid" 455 error is returned if the IDREFs in a ice-limit fail to reference elements in the payload. The error is detected on both the ref attribute and on the limits attribute.
| ice-span format |
<!ELEMENT ice-span ( ice-default-value,
ice-span-min?,
ice-span-point*,
ice-span-max?
)
>
<!ATTLIST ice-span
id ID #IMPLIED
ref IDREF #IMPLIED
name CDATA #IMPLIED>
description CDATA #IMPLIED
status ( required |
negotiable |
accepted
) "negotiable"
order ( numeric |
lexical |
time |
enumeration
) "numeric"
>
|
<!ELEMENT ice-default-value (#PCDATA) >
<!ATTLIST ice-default-value id ID #IMPLIED
name CDATA #IMPLIED
description CDATA #IMPLIED
ref IDREF #REQUIRED
>
|
<!ELEMENT ice-span-min ( #PCDATA | ice-limit )* >
<!ATTLIST ice-span-min id ID #IMPLIED
name CDATA #IMPLIED
description CDATA #IMPLIED
ref IDREF #REQUIRED
>
|
<!ELEMENT ice-span-point ( #PCDATA | ice-limit )* >
<!ATTLIST ice-span-point id ID #IMPLIED
name CDATA #IMPLIED
description CDATA #IMPLIED
ref IDREF #REQUIRED
>
|
<!ELEMENT ice-span-max ( #PCDATA | ice-limit )* >
<!ATTLIST ice-span-max id ID #IMPLIED
name CDATA #IMPLIED
description CDATA #IMPLIED
ref IDREF #REQUIRED
>
|
<!ELEMENT ice-limit EMPTY >
<!ATTLIST ice-limit
name CDATA #IMPLIED
description CDATA #IMPLIED
id ID #IMPLIED
ref IDREF #REQUIRED
limits IDREFS #REQUIRED
default CDATA #REQUIRED
>
|
The attributes on the ice-span are:
The attributes on ice-default-value are:
The attributes on ice-span-min are:
The attributes on ice-span-point are:
The attributes on ice-span-max are:
The attributes on ice-limit are:
If the ref attribute references an ice-span there MUST be pairs of IDREFs as the values of the limits attribute. Each IDREF MUST reference a min, point or max element in the referenced ice-span. These pairs define a union of sub-spans which limit the selectable values that are permitted in later negotiation of the associated parameter. The sub-span defined by each pair is inclusively from the smallest value of the pair to the largest. Thus, it is possible for a limit to exclude sub-ranges of the original span. If there are an odd number of IDREFs or the references do not exist or cannot be converted to span values a "Limit Invalid" 455 error response is returned,
If the ref attribute references an ice-enum then each IDREF in the limits value list MUST reference an ice-enum-item in the referenced ice-enum. The ice-enum-items in the limits list are the only items that may be selected in a later negotiation of the associated parameter. If the referenced elements do not exist or are not ice-enum-items a "Limit invalid" 455 error response is returned. If the resulting number of items left for selection is incompatible with the select attribute of the associated ice-enum then a "Enumeration selection empty or invalid" 456 error message is returned.
The ice-enum is used to provide a finite ordered set of values from which a subset is selected. An ice-enum is "resolved" or is "complete" when the number of items in the enumeration list satisfies the select attribute according to the table below and the status attribute of the ice-enum is set to "accepted".
| ice-enum format |
<!ELEMENT ice-enum (ice-default-value,ice-enum-item+) >
<!ATTLIST ice-enum
id ID #IMPLIED
ref IDREF #IMPLIED
name CDATA #IMPLIED
description CDATA #IMPLIED
select CDATA #REQUIRED
order ( numeric |
lexical |
time |
enumeration
) "enumeration"
status ( required |
negotiable |
accepted
) "negotiable"
>
|
The attributes for an ice-enum are:
ICE uses attributes containing "name" to always be an ICE application defined value and uses attributes named with suffix "-id" or "id" as being ICE defined identifiers.
| Num | Select value | Select Meaning |
| 1 | zero-or-one | Either none or one of the enumeration items MUST be selected. Any other selection results in a selection violation status code (454). |
| 2 | zero-or-more | Either none, one, or several enumeration items MUST be selected. If this value is used, selection or lack of selection of the values cannot result in a selection violation status code (454). |
| 3 | one-or-more | Either one or several enumeration items MUST be selected. A selection of zero (or none) results in a selection violation status code (454). |
| 4 | non-negative integer | Exactly (non-negative integer) enumeration items MUST be selected. A value of zero means that the item MUST NOT be selected and the items are probably being used to taunt the receiver. For example, a value of 5 means that exactly 5 options MUST be selected. If the value of the "select" attribute exceeds the number of available items for selection and the number of items is positive, the select attribute value is treated AS IF it were the number of items; otherwise a enumeration violation status code is returned,[454] ( This rule is designed to protect against having zero items offered (probably through a mechanical mistake in the offer) but still allow a large positive number to be used to ask for selection of all of the items.) |
An ice-enum-item requires either a value, an ice-extension, an ice-span or an ice-limit.
An enum-item can contain an ice-span. An ice-span in an enum-item is treated AS IF it is a sequence of ice-enum-items. Each ice-enum-item has a value that is one of the intermediate values in the span.
Note: The ice-span is a shorthand notation for convenience. It adds no new semantic capability to an enumeration. The utility of this shorthand becomes quickly apparent during definition of large enumerations such as the monthday attribute on the ice-delivery-rule.
| ice-enum-item format |
<!ELEMENT ice-enum-item ( #PCDATA |
ice-extension |
ice-span |
ice-limit )*
>
<!ATTLIST ice-enum-item id ID #IMPLIED
ref IDREF #IMPLIED >
|
<!ELEMENT ice-extension EMPTY>
<!ATTLIST ice-extension
id ID #IMPLIED
name CDATA #IMPLIED
uuid CDATA #REQUIRED
>
|
The attributes on an ice-enum-item are:
The attributes on an ice-extension are:
An ice-limit as content in an ice-enum-item has the same semantics as was defined above in ice-span. It is used to conditionally limit a parameter to be negotiated later should the containing ice-enum-item be selected. It permits selection of a value during the negotiation of this parameter to limit the range of values permitted during a later parameter negotiation. It does this by identifying the range to be limited as well as the limits.
There is a definition in this section for each of the ice-delivery-rule attributes. so that the values can be negotiated (by reference) in an ice-negotiable element.
ICE has the following built-in ice-range-defines. These are the default negotiable parameters that control how the ICE protocol performs package delivery to fulfill subscriptions. For brevity, each ice-span and ice-enum has the (default) attribute, status="negotiable" but the attribute is not shown.
All ice-operation type parameters are built-in to ICE and need not be declared in an ice-range-define element prior to use. All ICE processors MUST treat a reference to any of the ice-operation parameters defined in this section AS IF their definitions (included below) had been declared appropriately in a payload.
Additional "ice-operation" type parameters MAY be defined in the future as experience with the protocol is obtained. Note also, that additional syndicator or subscriber defined parameters are permitted to enhance the value of subscriptions.
All undefined "ice-operation" type parameters are reserved for future standardization. Undefined "ice-operation" type parameter names MUST not be used by ICE application processors. ICE application processors SHOULD use "ice-extension" and/or "x-domainname-categoryname for subscription and private use respectively.
The ice-operation parameter, monthday, replaces the deprecated ice-negotiable value "monthday". It, like all ice-operation parameters, is built-in to ICE and need not be declared in an ice-range-define element prior to use. All ICE processors MUST treat a reference to "monthday" in an ice-enum AS IF the following business term had been previously declared:
| Monthday - Built-in ICE Subscription Parameter Definitions |
|---|
<ice-negotiable type="ice-operation" name="monthday" >
<ice-text>
monthday restricts delivery to given days of the month.
It corresponds to the deprecated ice-negotiable
element attribute type value, "monthday".
</ice-text>
<ice-range-define id="monthday-builtin-definition" order="enumeration">
<!-- set the default value order to be enumeration -->
<ice-enum id="monthday" order="enumeration" select="one-or-more" >
<!-- one-or-more allows a list of monthdays to be selected
as required by the old ICE definition -->
<ice-default-value> any </ice-default-value>
<ice-enum-item id="anymonthday"> any </ice-enum-item>
<!-- the following is equivalent to
31 ice-enum-item definitions -->
<ice-span id="monthday_numbers" order="numeric" >
<ice-default-value> 1 </ice-default-value>
<ice-span-min> 1 </ice-span-min>
<ice-span-max> 31 </ice-span-max>
</ice-span>
<ice-enum-item id="lastmonthday" > last </ice-enum-item>
</ice-enum>
</ice-range>
</ice-negotiable>
|
The ice-operation parameter, weekday, replaces the deprecated ice-negotiable value "weekday". It, like all ice-operation parameters, is built-in to ICE and need not be declared in an ice-range-define element prior to use. All ICE processors MUST treat a reference to "weekday" in an ice-enum AS IF the following had been previously declared:
| Weekday - Built-in ICE Subscription Parameter Definition |
|---|
<ice-negotiable type="ice-operation" name="weekday" >
<ice-text>
weekday restricts delivery to a given day(s) of the week.
It corresponds to the deprecated ice-negotiable
element attribute type value, "weekday".
</ice-text>
<ice-range-define id="weekday-builtin-definition" order="enumeration">
<!-- set the default value order to be enumeration -->
<ice-enum id="weekday" order="enumeration" select="one-or-more" >
<!-- one-or-more allows a list of weekdays to be
selected as required by the ICE 1.0 definition -->
<ice-default-value> any </ice-default-value>
<!-- the following is equivalent to 7 ice-enum-item definitions -->
<ice-span id="weekday-numbers" order="numeric" >
<ice-default-value> 1 </ice-default-value>
<ice-span-min> 1 </ice-span-min>
<ice-span-max> 7 </ice-span-max>
</ice-span>
<ice-enum-item id="Monday" > Monday </ice-enum-item>
<ice-enum-item id="Tuesday" > Tuesday </ice-enum-item>
<ice-enum-item id="Wednesday" > Wednesday </ice-enum-item>
<ice-enum-item id="Thursday" > Thursday </ice-enum-item>
<ice-enum-item id="Friday" > Friday </ice-enum-item>
<ice-enum-item id="Saturday" > Saturday </ice-enum-item>
<ice-enum-item id="Sunday" > Sunday </ice-enum-item>
<ice-enum-item id="anyday" > any </ice-enum-item>
</ice-enum>
</ice-range>
</ice-negotiable>
|
The ice-operation parameter, startdate, replaces the deprecated ice-negotiable value "startdate". It, like all ice-operation parameters, is built-in to ICE and need not be declared in an ice-range-define element prior to use. All ICE processors MUST treat a reference to "startdate" in an ice-span AS IF the following had been previously declared:
| Startdate - Built-in ICE Subscription Parameter Definition |
|---|
<ice-negotiable type="ice-operation" name="startdate" >
<ice-text>
startdate defines the beginning of the Span
of an ice-delivery-rule.
It corresponds to the deprecated ice-negotiable
element attribute type value, "startdate".
</ice-text>
<ice-range-define id="startdate-builtin-definition" order="time">
<!-- set the default value order to be time -->
<ice-span id="startdate" order="time" select="zero-or-one" >
<!-- zero-or-one allows the default startdate (now) to be selected;
or a future startdate -->
<ice-default-value> now </ice-default-value>
<!-- the following introduces new ice-date and time definitions -->
<ice-span-min> now </ice-span-min>
<!-- this means the current date and time -->
<ice-span-max> anytime </ice-span-max>
<!-- this means the any valid date or any valid time -->
</ice-span>
</ice-range>
</ice-negotiable>
|
The ice-operation parameter, stopdate, replaces the deprecated ice-negotiable value "stopdate". It, like all ice-operation parameters, is built-in to ICE and need not be declared in an ice-range-define element prior to use. All ICE processors MUST treat a reference to "stopdate" in an ice-span AS IF the following had been previously declared:
| Stopdate - Built-in ICE Subscription Parameter Definition |
|---|
<ice-negotiable type="ice-operation" name="stopdate" >
<ice-text>
stopdate defines the end of the Span of
an ice-delivery-rule.
It corresponds to the deprecated ice-negotiable
element attribute type value, "stopdate".
</ice-text>
<ice-range-define id="stopdate-builtin-definition" order="time">
<!-- set the default value order to be time -->
<ice-span id="stopdate" order="time" select="zero-or-one" >
<!-- zero-or-one allows the default stopdate (never) to be selected;
or a future stopdate -->
<ice-default-value> never </ice-default-value>
<!-- the previous introduced new ice-date and time
definition, never -->
<ice-span-min> now </ice-span-min>
<!-- this means the current date and time -->
<ice-span-max> anytime </ice-span-max>
<!-- this means any valid date or any valid time -->
</ice-span>
</ice-range>
</ice-negotiable>
|
The ice-operation parameter, starttime, replaces the deprecated ice-negotiable value "starttime". It, like all ice-operation parameters, is built-in to ICE and need not be declared in an ice-range-define element prior to use. All ICE processors MUST treat a reference to "starttime" in an ice-span AS IF the following term had been previously declared:
| Starttime - Built-in ICE Subscription Parameter Definition |
|---|
<ice-negotiable type="ice-operation" name="starttime" >
<ice-text>
starttime defines the beginning of a selected time window for
an ice-delivery-rule.
It corresponds to the deprecated ice-negotiable
element attribute type value, "starttime".
</ice-text>
<ice-range-define id="starttime-builtin-definition" order="time">
<!-- set the default value order to be time -->
<ice-span id="starttime" order="time" select="zero-or-one" >
<!-- zero-or-one allows the default starttime
(00:00:00) or another starttime selection -->
<ice-default-value> 00:00:00 </ice-default-value>
<ice-span-min> 00:00:00 </ice-span-min>
<ice-span-max> 24:00:00 </ice-span-max>
<!-- this means midnight -->
</ice-span>
</ice-range>
</ice-negotiable>
|
The ice-operation parameter, duration, replaces the deprecated ice-negotiable value "duration". It, like all ice-operation parameters, is built-in to ICE and need not be declared in an ice-range-define element prior to use. All ICE processors MUST treat a reference to "duration" in an ice-span AS IF the following had been previously declared:
| Duration - Built-in ICE Subscription Parameter Definition |
|---|
<ice-negotiable type="ice-operation" name="duration" >
<ice-text>
duration defines the elapsed time for a selected
time window in an ice-delivery-rule.
It corresponds to the deprecated ice-negotiable
element attribute type value, "duration".
</ice-text>
<ice-range-define name="duration-builtin-definition" order="time">
<!-- set the default value order to be time -->
<ice-span id="duration" order="time" select="zero-or-one" >
<!-- zero-or-one allows the default duration
(24:00:00 - startime) or another duration selection -->
<ice-default-value> ( P86400S - starttime ) </ice-default-value>
<ice-span-min> P0S </ice-span-min>
<ice-span-max> P86400S </ice-span-max>
<!-- this means 24 hours -->
<!-- note that the default will cause the actual duration
to be computed based on starttime -->
</ice-span>
</ice-range>
</ice-negotiable>
|
The default value of duration is the amount of time from the starttime up to 24:00:00 hours.
The ice-operation parameter, min-update-interval, replaces the deprecated ice-negotiable value "min-update-interval". It, like all ice-operation parameters, is built-in to ICE and need not be declared in an ice-range-define element prior to use. All ICE processors MUST treat a reference to "min-update-interval" in an ice-span AS IF the following had been previously declared:
| Min-update-interval - Built-in ICE Subscription Parameter Definition |
|---|
<ice-negotiable type="ice-operation" name="min-update-interval" >
<ice-text>
min-update-interval defines the minimum amount of time between
updates.
It corresponds to the deprecated ice-negotiable element attribute
type values, "minfreq" and "min-update-interval".
</ice-text>
<ice-range-define id="min-update-interval-builtin-definition" order="time">
<!-- set the default value order to be time -->
<ice-span id="min-update-interval" order="time" select="zero-or-one" >
<!-- zero-or-one allows the default min-update-interval P0S
or another min-interval selection -->
<ice-default-value> P0S </ice-default-value>
<ice-span-min> P0S </ice-span-min>
<ice-span-max> P86400S </ice-span-max>
<!-- this means 24 hours -->
</ice-span>
</ice-range-define>
</ice-negotiable>
|
The ice-operation parameter, max-update-interval, replaces the deprecated ice-negotiable type attribute value "max-update-interval". It, like all ice-operation parameters, is built-in to ICE and need not be declared in an ice-range-define element prior to use. All ICE processors MUST treat a reference to "max-update-interval" in an ice-span AS IF the following had been previously declared:
| Max-update-interval - Built-in ICE Subscription Parameter Definition |
|---|
<ice-negotiable type="ice-operation" name="max-update-interval" >
<ice-text>
max-update-interval defines the maximum amount of time between
updates.
It corresponds to the deprecated ice-negotiable element attribute
type values, "maxfreq" and "max-update-interval"
</ice-text>
<ice-range-define id="max-update-interval-builtin-definition" order="time">
<!-- set the default value order to be time -->
<ice-span id="max-update-interval" order="time" select="zero-or-one" >
<!-- zero-or-one allows the default max-update-interval (duration/2)
or another min-interval selection
<ice-default-value> (duration/2) </ice-default-value>
<ice-span-min> P0S </ice-span-min>
<ice-span-max> duration </ice-span-max>
<!-- this means the duration of the delivery window (24 hours or less) -->
</ice-span>
</ice-range-define>
</ice-negotiable>
|
Note that the expression (duration/2) means that, by default, the maximum update interval will be half of the delivery window. This SHOULD cause delivery near the center of the window.
The ice-operation parameter, min-num-updates, replaces the deprecated ice-negotiable
type attribute value "min-num-updates". It, like all ice-operation parameters,
is built-in to ICE and need not be declared in an ice-range-define element prior to use.
All ICE processors MUST treat a reference to "min-num-updates" in an ice-span AS
IF the following had been previously declared:
| Min-num-updates - Built-in ICE Subscription Parameter Definition |
|---|
<ice-negotiable type="ice-operation" name="min-num-updates" >
<ice-text>
min-num-updates defines the minimum number of updates in each
selected time window.
It corresponds to the deprecated ice-negotiable element
attribute type values, "mincount" and "min-num-updates"
</ice-text>
<ice-range-define name="min-num-updates-builtin-definition" order="numeric">
<!-- set the default value order to be numeric -->
<ice-span id="min-num-updates" order="numeric" select="zero-or-one" >
<!-- zero-or-one allows the default min-num_updates, 1
or another number selection -->
<ice-default-value> 1 </ice-default-value>
<ice-span-min> 1 </ice-span-min>
<!-- no ice-span-max means up to the maximum integer may be specified. -->
</ice-span>
</ice-range-define>
</ice-negotiable>
|
The ice-operation parameter, max-num-updates, replaces the deprecated ice-negotiable type attribute value "max-num-updates". It, like all ice-operation parameters, is built-in to ICE and need not be declared in an ice-range-define element prior to use. All ICE processors MUST treat a reference to "max-num-updates" in an ice-span AS IF the following had been previously declared:
| Max-num-updates - Built-in ICE Subscription Parameter Definition |
|---|
<ice-negotiable type="ice-operation" name="max-num-updates" >
<ice-text>
max-num-updates is used to define the maximum number of
updates in each selected time window.
It corresponds to the deprecated ice-negotiable element
attribute type values, "maxcount" and "max-num-updates".
</ice-text>
<ice-range-define name="max-num-updates-builtin-definition" order="numeric">
<!-- set the default value order to be numeric -->
<ice-span id="max-num-updates" order="numeric" select="zero-or-one" >
<!-- zero-or-one allows the default max-num_updates, 1
or another number selection -->
<ice-default-value> any </ice-default-value>
<ice-span-min> 1 </ice-span-min>
<!-- ice-span-max> any </ice-span-max -->
<!-- no ice-span-max means up to the maximum implementation
integer value may be selected. -->
</ice-span>
</ice-range-define>
</ice-negotiable>
|
The ice-operation parameter, mode, replaces the deprecated ice-negotiable type attribute value "mode". It, like all ice-operation business term parameters, is built-in to ICE and need not be declared in an ice-range-define element prior to use. All ICE processors MUST treat a reference to "mode" in an ice-enum AS IF the following had been previously declared:
| Mode - Built-in ICE Subscription Parameter Definition |
|---|
<!-- the following new subscription options are defined -->
<ice-negotiable type="ice-operation" name="mode" >
<ice-text>
mode is used to define whether the syndicator initiates
the delivery of subscription content(push) or waits for
the subscriber to request the content(pull).
It is the negotiable form of the ice-delivery-rule element
mode attribute.
</ice-text>
<ice-range-define name="mode-builtin-definition" order="enumeration">
<!-- set the default value order to be enumeration -->
<ice-enum id="mode" order="enumeration" select="1" >
<ice-default-value> push </ice-default-value>
<ice-enum-item name="push" > push </ice-enum-item>
<ice-enum-item name="pull" > pull </ice-enum-item>
</ice-enum>
</ice-range-define>
</ice-negotiable>
|
In this section we consider several examples to illustrate the use of the parameter negotiation model.
Consider the case of syndicating Internet video to a broadcaster. The syndicator is Tribune Entertainment. The syndicator offers the following programs:
Tribune Entertainment offers the programs in two delivery styles:
The programs are offered in several digital video formats:
The offer has the following structure:
| Sam Rubin Live Offer |
|---|
<ice-offer productname="Sam Rubin Live from the Oscars"
description="Broadcast of Sam Rubin Live from the Oscars"
editable="false" atomic-use="true"
ip-status="SEE-LICENSE" rights-holder="Tribune Entertainment"
show-credit="true" usage-required="false"
>
<ice-delivery-policy startdate="2000-02-19T12:00:00,0"
stopdate="2000-02-26T12:00:00,0"
>
<ice-delivery-rule mode="push" monthday="any"
weekday="any" startdate="2000-02-19T12:00:00,0"
starttime="12:00:00" stopdate="2000-02-19T12:00:00,0"
min-num-updates="1" max-num-updates="1"
duration="P7200S"
>
</ice-delivery-rule >
</ice-delivery-policy >
<ice-negotiable type="ice-extension"
id="video_format" name="format"
>
<ice-text>
Please select the video format and delivery style.
<!-- This may be used by the subscriber to
display a request to an operator. -->
</ice-text>
<ice-range name="video format"
uuid="uri://www.VideoStandards.Org/video/formats/format.dtd" >
<!--uuid uniquely identifies the name space in which the
parameters exist and defines the semantics of the
parameters. ICE applicaiton processors are therefore expected
to know the type and range that a parameter has. -->
<ice-range-define>
<ice-enum enum-id="Bandwidth" >
<ice-enum-item id=bw1 > 28.8 </ice-enum-item>
<ice-enum-item id=bw2 > 56 </ice-enum-item>
<ice-enum-item id=bw3 > DSL </ice-enum-item>
<ice-enum-item id=bw4 > T1 </ice-enum-item>
<ice-enum-item id=bw5 > LAN </ice-enum-item>
<ice-enum-item id=bw6 > T3 </ice-enum-item>
<ice-enum-item id=bw7 > 100M </ice-enum-item>
<ice-enum>
<ice-enum enum-id="DeliveryStyle" >
<ice-enum-item id="ds1"> download </ice-enum-item >
<ice-enum-item id="ds2"> streaming </ice-enum-item >
</ice-enum>
<ice-span span-id="SegmentTime" >
<ice-default-value > 120 </ice-default-value >
<ice-span-min id="stmin" > 0 </ice-span-min >
<ice-span-point id="stsg1" > 15 </ice-span-point >
<ice-span-point id="stsg2" > 30 </ice-span-point >
<ice-span-point id="stsg3" > 45 </ice-span-point >
<ice-span-point id="stsg4" > 60 </ice-span-point >
<ice-span-point id="stsg5" > 75 </ice-span-point >
<ice-span-point id="stsg6" > 90 </ice-span-point >
<ice-span-point id="stsg7" > 105 </ice-span-point >
<ice-span-point id="stsg8" > 120 </ice-span-point >
<ice-span-max id="stmax" > 120 </ice-span-max >
</ice-span >
<ice-span span-id="Hour1" >
<ice-default-value > 60 </ice-default-value >
<ice-span-min id="hr1min" > 0 </ice-span-min >
<ice-span-max id="hr1max" > 60 </ice-span-max >
</ice-span >
<ice-span span-id="Hour2" >
<ice-default-value > 120 </ice-default-value >
<ice-span-min id="hr2min" > 60 </ice-span-min >
<ice-span-max id="hr2max" > 120 </ice-span-max >
</ice-span >
</ice-range-define >
<!-- Negotiable Parameters -->
<ice-enum id="data_format" select="1" >
<!-- could be "one-or-more" for rebroadcast -- >
<ice-default-value > QuickTime </ice-default-value >
<ice-enum-item >
<ice-limit ref="Bandwidth" limits="bw1 bw3" default="bw3" />
<ice-limit ref="DeliveryStyle" limits="ds2" />
Real Video
</ice-enum-item >
<ice-enum-item >
<!-- contentModel=( <#PCDATA | >,<constraints > )* -->
ASF
<ice-limit ref="Bandwidth" limits="bw1 bw2 bw5" default="bw5" />
<ice-limit ref="SegmentTime" limits="stmin stsg4" default="stsg4" />
<ice-limit ref="SegmentTime" limits="stmin stsg8" default="stsg8" />
<!-- If multiple limit span IDREFs are in the limits
attribute then a default attribute must specified
having value of one of the IDREFs.
Now this span will be negotiated later.
This provides a selectable default in the parameter's
negotiation. -->
</ice-enum-item >
<ice-enum-item > QuickTime </ice-enum-item >
<ice-enum-item >
MP2
<ice-limit ref="DeliveryStyle" limits="ds1" />
</ice-enum-item >
</ice-enum >
<ice-enum ref="DeliveryStyle" select="1" >
<ice-default-value > download </ice-default-value >
</ice-enum >
<ice-enum ref="Bandwidth" select="one-or-more" />
<ice-span ref="SegmentTime" >
<ice-default-value> 120 <ice-default-value>
<ice-span-min> 0 <ice-span-min>
<ice-span-max> 120 <ice-span-max>
<ice-span>
</ice-range >
</ice-negotiable >
</ice-offer>
|
The following is an example negotiation scenario based on the above offer. The previous versions of ICE left the details of negotiation as a quality of implementation issue. In ICE 1.1 and above, the order of parameter negotiation is defined; as are the details of how a parameter is negotiated.
In the following example, a subscriber obtains the catalog from Tribune Entertainment. It selects an offer from the catalog and as luck would have it, it is the very same offer defined above. In an effort to make the negotiation interchange more comprehensible, the XML has been compressed to remove the extraneous syntactic details.
The ice-range-defines have been compressed so that the range of the defines
can be easily viewed. It has the general form:
parameter-name - range=range default=default-value
A range that is an enumeration has the general form:
{ E1, E2, ..., Ek }
where each of the Ei are enumeration items. Similarly, a range that is a span has the general from:
min..max
where min is the minimum value of the range and max is the maximum value.
The default-value for the default attribute is shown as either a value (usually numeric) when used in defining a range; or, when used in a limit its value is a quoted IDREF that references a specific range item.
Finally, an ice-limit has been compressed to the general form:
(Limit: range-id, Limits="id reference list" default="id reference" )
Occasionly, the default attribute will be left off when it is identical to the single reference in the Limits attribute. Finally, the status attribute has values Negotiable, Required or Accepted. The "status=" is left off for brevity.
| Negotiation of the Sam Rubin Live Subscription |
|---|
1. SUB ==> SYN : ice-get-catalog
2. SUB <== SYN : ice-catalog 3. SUB="="> SYN : ice-offer [ offer-from-catalog ]
1. Video Format Offer [ see above ]
2. Defines
1. Bandwidth - range={28.8K, 56K, DSL, LAN}
2. Delivery Style - range={Download, Streaming}
3. SegmentTime - range=0..120, default=120
4. Hour1 - range=0..60, default=60
5. Hour2 - range=60..120, default=120
3. Data Format, select=1, default="RealVideo" negotiable
1. Real Video (Limit: Bandwidth, Limits="bw1 bw3" default="bw3" )
(Limit: DeliveryStyle, Limits="ds2")
2. ASF (Limit: Bandwidth, Limits="bw1 bw2 bw3", default="bw1")
(Limit: SegmentTime, Limits="hour1")
3. QuickTime
4. MP2 (Limit: DeliveryStyle, Limits="ds1")
4. DeliveryStyle, select=1, default="download" negotiable
5. Bandwidth, select="one-or-more" negotiable
4. SUB <== SYN : Error 441, ice-offer [ counter-offer ] 1. Video Format Offer 2. Defines 1. Bandwidth range="{28.8K," 56K, DSL, LAN} 2. Delivery Style range="{Download," Streaming} 3. SegmentTime range="0..120," default="120" 4. Hour1- range="0..60," default="60" 5. Hour2 range="60..120," default="120" 3. Data Format, select="1," default="df1" accepted 1. Real Video (Limit: Bandwidth, Limits="bw1 bw3" default="bw3" ) (Limit: DeliveryStyle, Limits="ds2" ) 4. DeliveryStyle, select="1," default="ds2" negotiable 5. Bandwidth, select="one-or-more" negotiable (Limit: Bandwidth, Limits="bw1 bw3" default="bw1" ) 5. SUB="="> SYN : ice-offer [ the counter-offer from step 4 ]
1. Defines
1. Bandwidth - range={28.8K, 56K, DSL, LAN}
2. Delivery Style - range={Download, Streaming}
3. SegmentTime - range=0..120, default=120
4. Hour1 - range=0..60, default=60
5. Hour2 - range=60..120, default=120
2. Data Format, select=1, default="df1" accepted
3. DeliveryStyle, select=1, default="ds2" accepted
4. Bandwidth, select="one-or-more", default="bw1" accepted
6. SUB <== SYN : ice-subscription !
|
Notice that the order of parameter negotiation follows the physical order of presentation. In addition, note that the selection of a value for an earlier parameter limits the range of values that can be selected for later parameters. This reduces the interchange necessary to arrive at a subscription and it permits the specification of a branching tree of possibilities where the selectable values of parameters are conditioned on earlier choices. Thus, it is possible to manage negotiations in which, for example, not all video formats are available at all bandwidths.
Implementation of a trivial negotiation is very simple. A subscriber selects an offer from a catalog, sets the status of each of the negotiable parameters to "accepted" and sends it back to the offering syndicator. The syndicator validates the offer, setups a subscription and sends it back to the subscriber. Thus, a single messages interchange accomplishes subscription establishment. The Syndicator can always issue a counter-offer with a 441 error code soliciting negotiation with the Subscriber. This would normally be done when the Syndicator wishes to alter delivery rules to a more propitious parameter set; for example, to a less busy delivery window.
In this section, a standard negotiation for ice-operation parameters is undertaken. It illustrates how negotiation can proceed in the normal case.
Consider the case of online delivery of an online monthly magazine. The magazine will be placed on the subscribers Web site and is part of subscribers strategy to maintain high traffic by keeping the site's content fresh. The magazine must arrive at least 48 hours before the beginning of the month so that it can be available on the web site for the entire month.
The same compression technique used above is used here to illuminate protocol operation without syntactic clutter.
The Catalog contains the following offer:
| Online Magazine Delivery Offer |
|---|
Online Magazine Format Offer
1. max-num-updates, default=2, required
2. min-num-updates, default=1, required
3. monthday, default="15 16 17 18 19 20 21 22 23
24 25 26 27 28 29 30 31",
span-min=15,
span-max=last, negotiable
4. weekday, default="1 2 3 4 5 6 7", negotiable
5. startdate, default="now", negotiable
6. stopdate, default="now+1 Year", negotiable
7. starttime, default="00:00:00", negotiable
8. duration, default="24:00:00", negotiable
9. min-update-interval, default="20 days",
span-min="20 days",
span-max="30 days", negotiable
10.max-update-interval, default="35 days",
span-min="28days",
span-max="40 days", negotiable
11.mode default=push, negotiable
|
The key points here are the required acceptance of at most 2 updates per accepted delivery window since this is monthly subscription, the idea is that it occurs at most twice during a delivery period.
The syndicator, in the offer is not concerned about the time of day that the delivery will be begin, because it is setup to span the entire delivery day. However, the syndicator wants to be able to update at any time from the 20th of the month to the last day of the month.
| Initial offer for Delivery time and duration Subscription |
|---|
1. SUB ==> SYN : ice-get-catalog
2. SUB <== SYN : ice-catalog 3. SUB="="> SYN : ice-offer [ offer adjusted from catalog ]
Online Magazine Format Offer [ see above ]
1. max-num-updates, default=2, accepted
2. min-num-updates, default=1, accepted
3. mode default=push, accepted
4. monthday, default="26", negotiable
span-min=15,
span-max=27
5. startdate, default="now", negotiable
6. stopdate, default="now+1 year", negotiable
7. starttime, default="17:00:00", negotiable
8. duration, default="07:00:00", negotiable
9. min-update-interval, default="20 days", negotiable
span-min="20 days",
span-max="30 days"
10. max-update-interval, default="35 days", negotiable
span-min="28days",
span-max="40 days"
11. weekday, default="Wednesday", negotiable
enum-range=[Monday,Friday]
|
The subscriber obtains and extracts a suitable offer from the catalog in steps 1 and 2. It reformulates the offer by reordering the parameters in it's priority order. The Subscriber first accepts the required parameters and their values, namely max-num-updates="2", min-num-updates="1" and mode="push" which means that in each delivery window, The syndicator will initiate at least one and at most two updates.
The subscribers most important (negotiable) parameter is the first negotiable parameter. In this example, it is the monthday -- because it defines the delivery window in which the protocol operates. The subscriber wants the next issue of the magazine to be delivered between the 15th and 27th of the month with an ideal delivery date on the 26th. The general idea is to reduce the amount of time that both the current and next issue must be stored.
The startdate is the next most important parameter. The subscriber is ready to start the subscription right away; but is willing to let the syndicator choose the startdate. The stopdate defaults to providing a one year subscription. However, it is negotiable suggesting that the subscriber is willing to opt for a different period of the subscription.
In a subscription where both ice-operation parameters and extended parameters are defined: 1. Limits can be placed such that say, the price changes when the length of subscription changes 2. Extended parameters MAY be negotiated before, after or at subscriber option in relation to the ice-operation parameters. This is accomplished by lexical placement in the Payload; and the use of the ice-limit element. There is no reason that the two types cannot be intermixed since the ice-operation parameters are well defined; they MAY be interspersed with the other parameters.
The starttime parameter has been reduced to start after 5PM (17:00) signaling a desire on the part of the subscriber to make sure that the overhead of delivery only occurs after the peak traffic of the day is over. (Note that ICE dates and times are always expressed in UTC (GMT) so that when you apply this, don't forget to offset the time by your time zone. That is, if you are in Bejing China, your local time is UTC+8:00:00, so your 17:00:00 is really 01:00:00). Also in concert with duration has been reduced from the default of 24 hours to only 7 hours. Note that an additional ice-delivery rule might be needed to open up the times from (00:00:00 to 06:00:00)
| Syndicator Counter offers for flexible Monthday delivery |
|---|
4. SUB <== SYN : Error 441, ice-offer [ counter-offer ] Online Magazine Format Offer [ see above ] 1. max-num-updates, default="2," accepted 2. min-num-updates, default="1," accepted 3. mode default="push," accepted 4. monthday, default="22" , negotiable (need flexibility to send early!) span-min="15," span-max="26" 5. startdate, default="now" , negotiable 6. stopdate, default="now+1 year" , negotiable 7. starttime, default="17:00:00" , negotiable 8. duration, default="07:00:00" , negotiable 9. min-update-interval, default="20 days" , negotiable span-min="20 days" , span-max="30 days" 10. max-update-interval, default="35 days" , negotiable span-min="28days" , span-max="40 days" 11. weekday, default="Wednesday" , negotiable enum-range="[Monday,Friday]" |
The Syndicator, would prefer the flexibility to deliver content earlier in the month. To preserve this flexibility, it counter proposes a default of the 22nd and would be happier accepting as early as the 15th of the month. Further, the Syndicator is willing to commit to delivery by the 26th.
| Subscriber Counter offers monthday in desired range. |
|---|
5. SUB ==> SYN : Error 441: ice-offer [ counter-offer ]
Online Magazine Format Offer [ see above ]
1. max-num-updates, default=2, accepted
2. min-num-updates, default=1, accepted
3. mode default=push, accepted
4. monthday, default="26", negotiable
(sub can't afford space!)
span-min=25, span-max=26
5. startdate, default="now", negotiable
6. stopdate, default="now+1 yr", negotiable
7. starttime, default="17:00:00", negotiable
8. duration, default="07:00:00", negotiable
9. min-update-interval, default="20 days", negotiable
span-min="20 days", span-max="30 days"
10. max-update-interval, default="35 days", negotiable
span-min="28days", span-max="40 days"
11. weekday, default="Wednesday",negotiable
enum-range=[Monday,Friday]
|
Notice that the subscriber is adamant about making the delivery as late in the month as possible consistent with it's needed setup times.
| Syndicator accepts Monthday and all other parameters |
|---|
6. SUB <== SYN : ice-subscription [Subscription] Online Magazine Format Offer [ see above ] 1. max-num-updates, default="2," accepted 2. min-num-updates, default="1," accepted 3. mode default="push," accepted 4. monthday, default="26" , accepted(ok,!) 5. startdate, default="now" , accepted 6. stopdate, default="now+1 yr" , accepted 7. starttime, default="17:00:00" , accepted 8. duration, default="07:00:00" , accepted 9. min-update-interval, default="20 days" , accepted 10. max-update-interval, default="35 days" , accepted 11. weekday, default="Wednesday" ,accepted |
The Syndicator decides to accept the monthday default value, and determines that it can deliver within the remaining parameters. It decides to accept all of the remaining parameters; and establish the subscription.
>From the protocol perspective, the negotiation required a total of 6 messages to setup the subscription; of which two messages were needed to obtain the offer. Notice that the number of messages would increase if additional parameters are to be negotiated. The key point here is that the cost of negotiation is linear in the number of negotiated parameters.
This example, while compressed for brevity and clarity could easily be expanded to show the full XML syntax of the messages.
ICE defines a number of status operations for manipulating subscriptions. They are:
Each is described below.
Cancels a subscription. This can be issued by either the Syndicator or the Subscriber. The format is:
| ice-cancel format |
| <!ELEMENT ice-cancel
EMPTY > <!ATTLIST ice-cancel subscription-id CDATA #REQUIRED reason CDATA #REQUIRED xml:lang CDATA #REQUIRED > |
The attributes are:
When a Requester sends an ice-cancel to a Responder, the two most likely types of response are:
The Requester should interpret any other error code as best it can.
One possible way for the Subscriber to tell if the Syndicator thinks it is still subscribed is to use ice-status to obtain the list of active subscription-id values.
The ice-cancellation returned in a successful response is:
| ice-cancellation format |
| <!ELEMENT ice-cancellation
EMPTY > <!ATTLIST ice-cancellation cancellation-id CDATA #REQUIRED subscription-id CDATA #REQUIRED > |
The attributes are:
Changes a subscription. This can be issued by either the Syndicator or the Subscriber. The semantics of this request are that a new parameter negotiation process is begun; however, until the negotiation process is completed successfully, the existing parameters remain in force.
The format of ice-change-subscription is:
| ice-change-subscription format |
| <!ELEMENT ice-change-subscription EMPTY > <!ATTLIST ice-change-subscription subscription-id CDATA #REQUIRED > |
There is only one attribute:
There are two cases to consider: Subscriber-initiated changes and Syndicator initiated changes.
When the Subscriber wishes to initiate a subscription change, the sequence of requests is as follows:
The existing subscription parameters always remain in force until an ice-offer is accepted with 200 (OK) by the Syndicator.
When the Syndicator wishes to initiate a subscription change:
While renegotiation is active, the Syndicator MAY reject other requests on this subscription with the 442 (Renegotiate in progress) error code.
The Syndicator MAY, by rejecting requests with 442 (Renegotiate in progress), initiate renegotiation without ever sending an ice-change-subscription. If a Subscriber receives a 442 error code and is not already engaged in renegotiation on that subscription, the Subscriber MUST enter into the ice-change-subscription renegotiation process.
Obtains status information for a subscription. This can be issued by either the Subscriber or the Syndicator. The format is:
| ice-get-status format |
| <!ELEMENT ice-get-status EMPTY > <!ATTLIST ice-get-status subscription-id CDATA #IMPLIED > |
| <!ELEMENT ice-status (
ice-contact, ice-subscription+ ) > |
| <!ELEMENT ice-subscription (ice-offer) > <!ATTLIST ice-subscription subscription-id CDATA #REQUIRED current-state CDATA #IMPLIED expiration-date CDATA #IMPLIED quantity-remaining CDATA #IMPLIED expiration-priority (first | last) #IMPLIED > |
There is only one attribute for ice-get-status:
The response is an ice-status, containing ice-contact contact information and ice-subscription data. There are no attributes on ice-status.
The ice-subscription element describes the state of a particular subscription with most of parameters being described by the ice-offer contained within it. There are several attributes:
Package delivery in ICE follows a Sequenced Package Model. This section describes that model. In this first description, the basic concepts are introduced without regard for the specific protocol messages used to realize the semantics of the model. Later sections will describe the specific messages.
An ICE subscription consists of a discrete set of packages delivered, in order, over a period of time. Consider the following diagram representing the delivery of individual packages, each labeled P and positioned along a time-line:
| ->---|-----P-----P-------P-----P------P--------P----P-----> t
t=0 |
ICE defines the term collection to mean the current content of a subscription. In the Headlines.com example discussed in 2.1.1, the collection consists of all the headline text, thumbnail images, etc., existing on a Syndicator or Subscribers site at any point in time. In the Parts Information Scenario described in 2.1.2, the collection consists of the complete set of service bulletins, price lists, etc., again as it exists at any one point in time.
ICE uses the package as the atomic unit of collection manipulation; the only way for a Syndicator to change a Subscribers collection is for the Syndicator to send a package to the Subscriber (push or pull). It is not possible for the Syndicator to send a "naked" file unless it is part of a package. Similarly, a Subscriber cannot request an update for an individual file; the only thing the Subscriber can do is request a new package of updates from the Syndicator.
It follows from this model that the state of a Subscribers collection is completely described by knowing the set of packages the Subscriber has received over time
ICE forces a Syndicator (and a Subscriber) to view the package stream as a strictly ordered sequence of packages. This means that packages cannot be processed out of order, and all intermediate packages must be processed.
For explanatory purposes, assume for the moment that packages were numbered P1 for the first package, P2 for the second, etc., In this case the strictly ordered package model of ICE requires that the Subscriber always process package PN-1 before processing package PN.
This model may seem at first glance to be a poor match for certain types of syndications, where intermediate updates might not be important. For example, in the Headlines.com example, if a Subscriber misses 10 days of headlines, it might be perfectly reasonable for the Subscriber to simply get the current set of headlines and ignore the intervening packages. The ICE model does, in fact, allow for this type of Syndication; this will be explained in a moment.
Given that ICE defines a package as the atomic unit of collection manipulation, and given that ICE forces a Subscriber to process all packages in a strict order, it is possible for a Syndicator (or Subscriber) to completely describe the state of the Subscribers collection with a single value: namely, an identifier indicating the position of the Subscriber within the ordered sequence of packages.
Thus, if packages were numbered with integers, consider the following package sequence:
| ->---|-----P1----P2------P3----P4-----P5------P6----P7----->
t t=0 |
In this example, simply knowing the number of the last package successfully processed by a Subscriber will suffice to know the complete state of the Subscribers collection. For example, knowing that the Subscriber is "in state 5", meaning, has received and correctly processed package number 5, implies that the Subscribers collection is in the state that would be achieved by starting in an empty state, and processing packages 1 through 5, in order. Thus, a simple number by itself, e.g., "5", suffices for describing the state of the Subscribers collection. In ICE, this "number" is called a Package Sequence Identifier, and is actually not a number at all, but rather an opaque string per the following definition:
Definition: A Package Sequence Identifier is an opaque string, generated by a Syndicator, representing the state at the boundary (before or after) of package processing. Each package sent by a Syndicator to a Subscriber has two package sequence identifiers attached to it: an "old" state value representing the required state before processing the package, and a "new" state value representing the resulting state after processing the package.
Note that the identifier is completely opaque to the Subscriber. This gives the ICE implementation on the Syndicator the complete flexibility to use an implementation specific method for encoding state into this identifier. For example, the implementation might use integers as described above, or it might use timestamps, or it might use a unique key into a proprietary database as the state encoding mechanism. All of these methods are permitted, and the opaqueness of the identifier guarantees that (properly-implemented) Subscribers will not be affected by these choices.
ICE defines three distinguished values for Package Sequence Identifier strings:
Furthermore, ICE reserves all Package Sequence Identifier strings beginning with ICE- (capital I, capital C, capital E, hyphen). All other values of a Package Sequence Identifier are controlled by the Syndicator and are completely opaque to the Subscriber.
The requirements for Subscribers regarding Package Sequence Identifiers are:
When a Syndicator delivers a package to a Subscriber, whether by push or pull, the package contains two sequence identifiers: the old-state, which represents the state the Subscriber must be in before applying the package, and the new-state, which represents the state the Subscriber will be in after applying the package.
Assume, for example, that a Syndicator is using the names of people as the Package Sequence Identifier. Using this method, a set of packages delivered over time might consist of:
First Package: old-state: ICE-INITIAL new-state: STEVE Next Package: old-state: STEVE new-state: GREG Next Package: old-state: GREG new-state: ROGER
As will be shown in more detail later, a Subscriber is required to store its current Package Sequence state at all times. When it first starts a new subscription, the Subscriber starts in state ICE-INITIAL. In the above example, the first package the Subscriber receives must have an old-state of ICE-INITIAL (or ICE-ANY, which will be discussed next). If, due to some operational error, the Subscriber were to receive the wrong package, e.g., one that said old-state: GREG instead of old-state: ICE-INITIAL, then the Subscriber would know not to process that package and to raise an error condition.
The above model works well for subscriptions requiring a strict, fully-reliable, replication of state from a Syndicator to a Subscriber. The Package Sequence model strictly forces the Subscriber to receive all packages in their proper order, and process them each individually. The protocol does this by requiring the Subscriber to remember its current Package Sequence Identifier, and to send that Identifier to the Syndicator when requesting a package update (for pull; push subscriptions are slightly more complex and will be discussed later). Thus, the Syndicator always knows what state the Subscriber is in, and the Syndicator can thus always compute what the "right" next package to send to the Subscriber.
Some models of subscriptions do not require the rigor of this model. As mentioned, the Headlines.com model can be implemented in a much simpler fashion: each package is actually a full update of the Subscriber, and there are no dependencies on intervening packages. The ICE Package Sequence model accommodates this type of subscription using the ICE-ANY value. When ICE-ANY appears in the "old-state" of a package, it means that the package can be applied by a Subscriber regardless of what state the Subscriber is in.
By using combinations of ICE-ANY preconditions and specific preconditions, a Syndicator can also implement hybrid models where some packages are useful regardless of the Subscribers current state.
An example will help tie this all together. To understand the example, assume for the moment that packages can contain files, and that they can also contain "remove" operations that refer to files delivered in previous packages. As will be explained later, packages can indeed contain these types of things, albeit in a much more general (and complex) way (because packages are not limited to operating only on files).
A Syndicator provides a restaurant review service; Subscribers receive updates with new restaurants, new information about existing restaurants, etc.
Assume for the moment that the service is just starting up and there is only one Subscriber. The service is launched with only 3 restaurant reviews. The package stream generated over time by the Syndicator might look something like this:
At this point assume that a new Subscriber signs up. That Subscriber needs all three packages P1, P2, P3, in that order. The Syndicator will know this because the Syndicator (by definition) knows that it is currently in state "P3", and it will know that the Subscriber is in state ICE-INITIAL when the Subscriber requests its first update.
Note that, as an implementation optimization, the Syndicator can construct a special "catch up" package in this case. That would look like this:
A Syndicator implementation that does that might be more efficient than sending all three incremental updates. But whether or not this should be done is a quality-of-implementation decision made by the Syndicator. Nothing in the sequenced package model dictates one approach or the other.
Finally, assume one more package needs to get sent, this time to two Subscribers:
As mentioned before, the Subscriber must keep track of the sequence identifier of the last successfully processed package. The Subscriber sends this sequence identifier back to the Syndicator when requesting an update, so that the Syndicator can understand the Subscribers state. The Syndicator contains the logic to understand what to do based on the Subscribers (stated) sequence identifier. In the case of an unreliable update model, the Syndicator can basically ignore the sequence identifier and just send the current package (with an old-state of ICE-ANY). In other models, the Syndicator can compute what to send by decoding the sequence identifier (which it generated in an earlier package) and using that to determine what to send.
This shows the messages exchanged in the above example when the new Subscriber was added between Time 3 and Time 4 in the above sequence.
SUB ==> SYN I'm subscribing to RESTAURANTS SYN ==> SUB OK SUB ==> SYN GetPackage, my state is ICE-INITIAL SYN ==> SUB - three packages P1, old-state: ICE-INITIAL new-state: XYZ-1 P2, old-state: XYZ-1 new-state: XYZ-2 P3, old-state: XYZ-2 new-state: XYZ-3
Alternatively, this last message could have been:
SUB ==> SYN I'm subscribing to RESTAURANTS SYN ==> SUB OK SUB ==> SYN GetPackage, my state is ICE-INITIAL SYN ==> SUB - one package Px, old-state: ICE-INITIAL new-state: XYZ-3
where the "Px" package would be a customized package designed specifically to get a Subscriber from the initial state to the current state. The key point is the separate specification of a list of packages to be received, and an explicit statement about what the state will be after processing the packages.
It is entirely the Syndicators discretion as to what the best way to update the Subscriber is (e.g., sending all the incremental packages or sending a special catch up package).
Suppose the Subscriber comes back before Time 4 and asks for an update:
SUB ==> SYN GetPackage, my state is XYZ-3 SYN ==> SUB 202 Package sequence state already current
Later, there are updates available:
SUB ==> SYN GetPackage, my state is XYZ-3 SYN ==> SUB one package: P4, oldstate XYZ-3, new XYZ-4
ICE packages contain content as a set of idempotent operations: remove and add. These operations use the addressing mechanism of a subscription element to reference and manage delivered content. The method of delivery does not affect these operations. As detailed in the Sequenced Package Model section, each package moves the subscription from an old state into a new state of the subscription.
| ice-package format |
|---|
<!ENTITY % cm.content "ice-item-group | ice-item | ice-item-ref" >
<!ENTITY % cm.package "((ice-item-remove+, (%cm.content;)*) |
(%cm.content;)+)" >
<!ELEMENT ice-package (%cm.package;) >
<!ATTLIST ice-package
activation CDATA #IMPLIED
atomic-use (false | true) "false"
confirmation (false | true) "false"
editable (false | true) "false"
exclusion CDATA #IMPLIED
expiration CDATA #IMPLIED
fullupdate (false | true) "false"
xml:lang CDATA #IMPLIED
new-state CDATA #REQUIRED
old-state CDATA #REQUIRED
package-id CDATA #REQUIRED
show-credit (false | true) "false"
subscription-id CDATA #REQUIRED
>
|
The attributes are:
An ice-package describes a set of content operations: removals and additions. The remove operation is specified using the ice-item-remove element. The content additions contain the content that needs to be added or updated and are specified using the ice-item and ice-item-ref elements. The ice-item-group element allows the Syndicator to associate the content specified using the ice-item elements together. For example, in the restaurant reviews example, each review may consists of different types of content: an HTML file and two graphic files for example. These three files could be contained within three ice-item elements and grouped together in an ice-item-group as a single restaurant review. Likewise, unrelated content can be specified in an ice-package by just using the ice-item elements without an intervening ice-item-group. The ice-item and ice-item-ref elements distinguish themselves by the way they contain the content. The ice-item element is used to contain content directly in the delivered content. The ice-item-ref element is used to distribute an indirect reference to the actual content.
The content model of the ice-package element is constructed so that it MUST contain some operation; at a minimum, a single removal or a single addition. If there are removal operations, they MUST be specified and, therefore, performed before any additions. It is possible that an ice-package only contains removal operations. Alternatively, an ice-package may consist entirely of additions. The ice-package specifies an old-state and a new-state. Before the new-state can be reached, all of the operations contained within a package MUST be processed, and, if constraints are specified, the constraints MUST be met as well. If an operation can not be performed successfully, all previously performed operations specified in the package MUST be undone, so the Subscriber is not left in an inconsistent state with regards to the package sequence, and a surprise ice-code message MUST be delivered to the Syndicator indicating the type of error that occurred, such as 420 (Constraint failure). All of the operations are idempotent, i.e., it is not an error if the same content is added more than once, nor is it an error if a remove operation does not find the element to remove. In both cases the results are the same (an add operation resulted in the content existing on the Subscribers system, and a remove operation resulted in the content not existing).
The details of the additions and removals are described within their respective sections. XML parameter entities were used to construct the ice-package content model to modularize the description and to allow for reuse of the content model (notice that the cm.content entity is used for the ice-item-group content model below).
ICE provides three operations by which packages can add new content to the Subscribers collection: ice-item, ice-item-ref, and ice-item-group. Each is described below.
| ice-item format |
|---|
<!ENTITY % cm.item "#PCDATA" > <!ELEMENT ice-item (%cm.item;) > |
<!ENTITY % attlist.item "
activation CDATA #IMPLIED
expiration CDATA #IMPLIED
content-filename CDATA #IMPLIED
content-transfer-encoding (base64 | x-native-xml)
'x-native-xml'
content-type CDATA 'application/octet-stream'
ip-status CDATA #IMPLIED
item-id CDATA #REQUIRED
xml:lang CDATA #IMPLIED
license CDATA #IMPLIED
rights-holder CDATA #IMPLIED
show-credit CDATA #IMPLIED
subscription-element CDATA #IMPLIED
">
<!ATTLIST ice-item %attlist.item;
name CDATA #REQUIRED
ice-element CDATA #FIXED 'ice-item'
>
|
The attributes are:
The ice-item element explicitly contains the content being distributed. The default content model for an ice-item is simply character data. The data MUST conform to the definition of character data in XML. Binary data can be transmitted within an ice-item by using a base64 encoding. The content model for an ice-itemMAY be overridden by other XML ELEMENT declarations, this does not affect the operational semantics of the element itself. To replace ice-item, please refer to the Extensibility section in 8.x.x. The purpose of the name attribute is to represent in a generic way what specific mark-up might represent if both parties had agreed to a common vocabulary and had specific applications for handling the content. For example, what gets represented as <ice-item name="headline"> might be more specifically marked up using <headline> using XML as the mark-up language. This element allows for quick deployment of the content without a lot of up-front investment. Because the content models are extensible, the investment in specific mark-up vocabularies can be similarly expressed within the same protocol.
The ice-item-ref element is a managed pointer to content. It's content is included in a package delivery by reference. It is used when the data is cumbersome or inappropriate for direct package inclusion. This data is typically streaming or other volatile data whose value is not static enough for direct inclusion. Uses of ice-item-ref could include time-based data, specially authorized data; or simply data too large to deliver without special arrangement.
To manage data access, an ice-item-ref can contain zero or more ice-access elements. An ice-access defines an optional access window and an optional set of access controls. The access window defines the times when the content may be accessed; while the access control defines the means to successfully meet imposed access challenges.
Multiple ice-access elements permit flexible specification of controls and access times so that many different data control policies can be implemented. This allows a wide range of differing availability and security requirements to be supported.
The format of the the ice-item-ref and its associated content model is:
| ice-item-ref format |
|---|
<!ENTITY % cm.access "( ice-access-window?,
ice-access-control?
)" >
<!ELEMENT ice-access %cm.access; >
<!ATTLIST ice-access
name CDATA #IMPLIED
description CDATA #IMPLIED
id ID #IMPLIED
>
<!ENTITY % cm.item-ref "(ice-access)*" >
<!ELEMENT ice-item-ref %cm.item-ref; >
<!ATTLIST ice-item-ref %attlist.item;
url CDATA #REQUIRED
ice-element CDATA #FIXED 'ice-item-ref'
>
|
The attributes of ice-item-ref in common with ice-item, namely those defined with attlist.item have the same semantics:
All other attribute semantics of ice-item-ref are identical to ice-item. The processing of this operation requires resolving the reference and obtaining the content associated with it. Resolving the reference consists of evaluating the list of ice-access elements to determine the correct times to access the referenced content and pass the access challenges. Note also that content-type is useful to the content retrieval and resolution process. Failure to resolve the reference or obtain the content MUST cause a surprise ice-code message, 431 (Failure fetching external data), to be sent to the Syndicator. If the associated failure is caused by an access ( access-window or access-control) failure, implementations SHOULD note that in the surprise message.
If the content of an ice-item-ref contains multiple ice-access elements, a union of all the access times results. The access controls are processed in physical order of appearance and are associated only with the spans of time specified by their associated ice-access-window in the containing ice-access If access times overlap, the access controls are used in order of appearance in the payload at the appropriate time to meet access challenges offered by the receiver. Content may be accessed an any of the union of times and the associated access-control will be used to obtain access.
The ice-access contains an optional ice-access-window and and optional ice-access-control. If the ice-access-window is missing, then access to the content MAY be at any time the receiver desires. Otherwise, access MUST be during the spans of time defined by the ice-access-window. If the ice-access-control is missing, then access to the content is assumed to be uncontrolled during the access window times. If both the ice-access-window and ice-access-control are missing, then the ice-access in assumed to be available at any time with uncontrolled access. The attributes of the ice-access are:
descriptionOPTIONAL. The description attribute is provided for ICE application processors. Presumably it will be used to describe the ice-access element.
The ice-access-window element declares the windows in time that the content referenced by the containing ice-item-ref MAY be accessed. It also defines the access repetition rates. The access window uses the same semantics as the ice-delivery-policy, where the "delivery window" becomes the access window. The ice-delivery-policy as specified here MUST NOT be negotiated. All parameter values in an ice-delivery-policy in an ice-access-window MUST be resolved. It is an error for the parameter values in an ice-delivery-policy in an ice-access-window to not be resolved.
| ice-access-window format |
|---|
<!ENTITY % cm.access-window "(ice-delivery-policy)" >
<!ELEMENT ice-access-window %cm.access-window; >
<!ATTLIST ice-access-window
name ID #IMPLIED
start-time CDATA #IMPLIED
stop-time CDATA #IMPLIED
>
|
The ice-access-control element provides an automated mechanism for responses to access challenges. A content provider (syndicator or subscriber) may place content in a password protected (or other access controlled) location to prevent unauthorized use of the content. This element would typically be provided by the Sender to alert a receiver that the content referenced by the ice-item-ref will be subject to an access challenge. This element also provides the receiver with the means to respond (successfully) to the challenge.
| ice-access-control format |
|---|
<!ENTITY % cm.access-control "(#PCDATA)" >
<!ELEMENT ice-access-control %cm.access-control; >
<!ATTLIST ice-access-control
id ID #IMPLIED
name CDATA #IMPLIED
description CDATA #IMPLIED
control-type ( password |
cookie |
custom ) #REQUIRED
user CDATA #IMPLIED
password CDATA #IMPLIED
access-reference CDATA #IMPLIED
extension-id CDATA #IMPLIED
>
|
Each ice-access-window has an optional ice-access-control associated with it in the sense that
The ice-item-group defines an aggregation element that permits tree structured content to be transported by ICE. The content model for an ice-item-group also permits content references to be placed in the tree structured content through the use of the ice-item-ref element.
| ice-item-group format |
|---|
<!ELEMENT ice-item-group ((%cm.content;)+) >
<!ATTLIST ice-item-group %attlist.item;
activation CDATA #IMPLIED
item-group-id CDATA #REQUIRED
name CDATA #IMPLIED
subscription-element CDATA #IMPLIED
>
|
The attributes for ice-item-group have the same semantics as the ice-item element with the following clarifications and exceptions.
The ice-item-group element allows relationships among content items to be expressed. For example, a story or headline could be individually described as content items within one of these groups. The content model for an ice-item-group allows for the nesting of groups and individual content items. The identifier on the group is assigned by the Syndicator and is scoped within the package. The name is for logging purposes and otherwise has no semantics associated with it. The availability of the subscription-element attribute allows for coarser operations to occur. For example, a subsequent package might contain a remove operation identifying the group's subscription-element identifier that MUST be used to remove all individual items previously contained within that group. Likewise, any updates or adds associated with the same group's subscription-element associates the individual items together.
Similar to archiving packages, groups with subscription-element identifiers allow for other items to be added over a sequence of packages. Consider a package that delivered a group identified as subel3 with three content items. In a subsequent package that delivers a group identified as subel3 with four different items, the resulting addition of the four will yield a group containing seven items. If any of those items also contained subscription-element attributes, they would be replaced, so the yield would be less. This is similar to the case where a tar file specifying a directory with three files being extracted, and later on receiving a tar file with the same directory specified but four different files. The contents of the directory would be seven files (unless there were files with the same name in the archive). There is a difference between an archive file delivering directories and files with the ICE package containing groups and items that groups have no physical manifestation, but groups with a subscription-element attribute requires the Subscriber to manage the content contained within that group.
| ice-item-remove format |
|---|
<!ELEMENT ice-item-remove EMPTY >
<!ATTLIST ice-item-remove
subscription-element CDATA #REQUIRED
>
|
The attribute is:
The subscription-element attribute on the ice-item-remove element identifies the content item (or group of content items) that MUST be removed from a Subscribers system. The physical location(s) of the content that needs to be removed MUST be managed by the Subscriber. A full update of content items can be achieved by a Syndicator in one of a number of ways. Two specific ways are either to enumerate all of the subscription element identifiers in a set of ice-item-remove elements followed by the new content in a set of ice-item elements or to specify the fullupdate attribute on the ice-package element to have a value of true. This remove request can be seen as a logical removal in the sense that the end result after processing the whole package must be that the content specified in the ice-item-remove element must be removed from the Subscribers system. During an intermediate stage of processing, it may mean that the remove has not occurred until the very end because the content is being updated in an add operation. In this case the add operation overrides the remove.
The content models of the ice-package and ice-item, elements MAY be extended or replaced with declarations of different elements or content. See section 8.
If a subscription has a delivery policy method of type pull, the Subscriber must initiate the delivery of the packages with the ice-get-package request. When a Subscriber requests a package from the Syndicator, the Subscriber MUST provide the state of the subscription and subscription identifier, and MAY provide an application-specific parameter value.
The message format is:
| ice-get-package format |
|---|
<!ELEMENT ice-get-package EMPTY > <!ATTLIST ice-get-packagecurrent-state CDATA #REQUIRED parameter CDATA #IMPLIED subscription-id CDATA #REQUIRED > |
The attributes are:
When a Subscriber sends an ice-get-package to a Syndicator, the most likely types of response are:
The Subscriber should interpret any other return code as best it can. The number of ice-package elements and the number of state transitions that are provided in a single response is determined by the quality of implementation of the Syndicators ICE application.
If a subscription has a delivery policy method of type push, the Syndicator must initiate the delivery of the packages with the ice-request containing one or more ice-package elements. When a Syndicator sends a package to the Subscriber, the Syndicator MUST provide the expected state of the subscription before and after the package is processed. The Subscriber is still responsible for maintaining the current state of the subscription, but the Syndicator now has that responsibility to support push operations. The message format is defined in section 5.2.1 Package format.
When a Syndicator sends an ice-package request to a Subscriber, the most likely types of response are:
The Syndicator should interpret any other return code as best it can.
This section contains all other package-related protocol operations.
When a Syndicator requests confirmation from a Subscriber, the Syndicator MAY choose to allow a certain number of additional operations to occur while that confirmation request is still outstanding. The number, and type, of such requests that the Syndicator will honor in the interim is a quality of implementation issue and a Syndicator policy issue.
Eventually, the Syndicator might want to indicate its unwillingness to proceed any further until the Subscriber furnishes the expected pending confirmations. ICE provides two different methods for the Syndicator to indicate this. First, the Syndicator MAY return error code 602 (Excessive confirmations outstanding) on any request made by the Subscriber. This is a "passive" way for the Syndicator to indicate its displeasure; passive in the sense that the Subscriber will not find out about it until the Subscriber makes a request.
The second method ICE provides is the ice-send-confirmations message. This message allows the Syndicator to tell the Subscriber explicitly that it is expecting confirmations and is puzzled as to why it hasn't received them yet.
The message format is:
| ice-send-confirmations format |
<!ELEMENT ice-send-confirmations EMPTY >
<!ATTLIST ice-send-confirmations
subscription-id CDATA #IMPLIED
>
|
The attributes are:
The proper response to this message is for the Subscriber to return a code telling the Syndicator whether the Subscriber agrees or not that there are outstanding confirmations. If the Subscriber agrees that there are outstanding confirmations on this subscription, the Subscriber MUST return ice-code 200 (OK). If the Subscriber does not have any outstanding confirmations on this subscription, the Subscriber MUST return ice-code 303 (No more confirmations to send). Notwithstanding those two requirements, the Subscriber MAY return any arbitrary error code to indicate other processing problems. So, for example, an ice-send-confirmations request that does not validate might still generate a 402 code.
ICE provides a mechanism allowing the Subscriber to get information about package ordering and potential optimizations. The Subscriber does this with an ice-get-sequence request. In this request, the Subscriber sends its current package sequence state, and a set of package identifiers and their ("new-state") package sequence state values. The request returns a sorted, and potentially optimized (as described below), list of the packages and sequence identifiers.
The message format is:
| ice-get-sequence format |
<!ELEMENT ice-get-sequence (ice-package-state+) >
<!ATTLIST ice-get-sequence
current-state CDATA #REQUIRED
subscription-id CDATA #REQUIRED
>
|
<!ELEMENT ice-package-state EMPTY >
<!ATTLIST ice-package-state
package-id CDATA #REQUIRED
new-state CDATA #REQUIRED
>
|
There are two attributes on the ice-get-sequence element:
The ice-get-sequence element contains one or more ice-package-state elements, each of which contains the following attributes:
The response is an ice-sequence, as shown here:
| ice-sequence format |
<!ELEMENT ice-sequence (ice-package-state*) >
<!ATTLIST ice-sequence
subscription-id CDATA #REQUIRED
>
|
There is only one attribute on the ice-sequence element:
The response contains a sorted list of ice-package-state elements. This list might be a subset of the elements sent in the ice-get-sequence request, if the Syndicator determines that some of the intervening packages need not be processed by the Subscriber.
The ice-repair-item request allows a Subscriber to ask for a replacement copy of an individual asset in a collection. The intent is to provide a mechanism for repairing a Subscribe-r's collection after minor mishaps, such as a file being accidentally deleted.
The message format is:
| ice-repair-item format |
<!ELEMENT ice-repair-item EMPTY >
<!ATTLIST ice-repair-item
subscription-id CDATA #REQUIRED
subscription-element CDATA #REQUIRED
current-state CDATA #REQUIRED
>
|
The attributes are:
In making this request, the Subscriber is asking the Syndicator to return a copy of the asset as of the given package sequence state, if it is able to do so.
When a Syndicator receives this request, there are at least four possible responses it can make:
Note that this request is provided for the convenience of the Subscriber, in the hopes that in some cases the Syndicator might be able to easily supply a replacement asset. The request does not obviate the requirement for a Subscriber to perform backup processes; in particular since the Syndicator is always allowed to return an error (including 503) on this request, the Subscriber MUST NOT assume that individual asset repair requests will work.
ICE allows a Syndicator to request the protocol event logs of the Subscriber, and vice versa, as an aid for debugging and diagnosis. This section describes the protocol operations for manipulating log files.
ICE does not impose a particular format on the data contained in the logs. There are a number of reasons for this, the most compelling reason being that there are a variety of other efforts underway to define log file formats (e.g., XLF). For interoperability at the ICE level, the only requirement is that one system know how to ask another system for a log file and that ICE be able to transport multiple log file formats. Beyond that, the two systems can agree at the application layer as to what those log files will actually contain.
ICE does in fact define one log file format, called the "ice" format. Section 6.3 describes this format.
Event logs consist of implementation-defined data collected and recorded by the ICE tools used on each side of the relationship. There is only one meaningful operation that can be applied to event logs: they can be requested. This request can be made by the Subscriber, to obtain the Syndicator logs, or by the Syndicator, to obtain the Subscriber logs.
The format of this ICE request is shown below:
| ice-get-events format |
<!ELEMENT ice-get-events EMPTY >
<!ATTLIST ice-get-events
format NMTOKENS #IMPLIED
start CDATA #IMPLIED
stop CDATA #IMPLIED
subscription-id CDATA #IMPLIED
>
|
The attributes are:
The response is an ice-events message, as shown here:
| ice-events format |
<!ENTITY % cm.events "ice-event-log" >
<!ELEMENT ice-events (%cm.events;) >
<!ATTLIST ice-events
format CDATA #REQUIRED
start CDATA #IMPLIED
stop CDATA #IMPLIED
subscription-id CDATA #IMPLIED
>
|
The attributes are:
In the case where format is "ice", the content model of the ice-events element is an ice-event-log, as described next (6.3).
Note that the content model of the ice-events element MAY be extended or replaced with declarations of different elements or content. See Appendix A.
This section describes the "ice" format, which is just one log file format that can be transported by ice-get-events. ICE implementations SHOULD support this format, and MAY support other formats as well.
The "ice" format log consists of an ice-event-log wrapper, containing a number of ice-event-msg and ice-event-info elements, as shown here:
| ice-event-log format |
<!ELEMENT ice-event-log ((ice-event-msg | ice-event-info)*) >
<!ATTLIST ice-event-log
version CDATA #REQUIRED
>
|
<!ELEMENT ice-event-msg (ice-code?, ice-event-data?) >
<!ATTLIST ice-event-msg
other-id CDATA #IMPLIED
request CDATA #REQUIRED
request-id CDATA #REQUIRED
request-start CDATA #REQUIRED
request-type CDATA #IMPLIED
response CDATA #REQUIRED
response-id CDATA #IMPLIED
response-stop CDATA #REQUIRED
response-type CDATA #IMPLIED
role (requestor | responder)
#REQUIRED
subscription-id CDATA #IMPLIED
>
|
<!ELEMENT ice-event-info (ice-event-data?) >
<!ATTLIST ice-event-info
event CDATA #REQUIRED
event-start CDATA #REQUIRED
event-stop CDATA #REQUIRED
>
|
<!ELEMENT ice-event-data ANY >
<!ATTLIST ice-event-info
name CDATA #IMPLIED
description CDATA #IMPLIED
>
|
In an ice-event-log, there is only one attribute:
The ice-event-log contains zero or more ice-event-msg or ice-event-info elements. The ice-event-msg element represents a record of an ICE protocol event. It contains logging information about both the request and the corresponding response.
The attributes are:
Within the ice-event-msg itself is an ice-code, logging the code that came back in the response (if any), and an ice-event-data element, which has an ANY content model and allows loggers to record additional data in an implementation specific format. This information is completely implementation dependent, determined by the Sender of the log, and can safely be ignored by the Receiver. It is expected that as inter-operable ICE implementations arise, it will become clear what additional information is valuable to log, and that additional information may be added to a future version of this specification. Note that ICE reserves all element names beginning with the sequence "ice-" (regardless of case), so additional, implementation-defined sub-elements MUST obey this restriction in order to avoid conflict with future versions of the ICE event log format.
The ice-event-info element provides a way to log other information events not directly related to protocol operations. The attributes are:
The strings in the event attribute have the following meanings:
All standardized information in the ice-event-log is transmitted as attributes. This is done so that the logs are easy to scan using standard pattern matching tools, as well as making efficient use of XML parsers, while the ice-code and implementation-defined additional information is transmitted in the body of the element where it can be retrieved as needed.
Note that while ICE can specify the format of communication of ICE events, it leaves the details of how logging is controlled, and indeed whether any logging is done at all, as a quality of implementation issue. It is perfectly legal for an ICE implementation to never log anything, and always return an empty log in response to an ice-get-events request. That being said, it is expected that logging will be useful for debugging and diagnosis, and the ability to share logs between Subscriber and Syndicator will help in managing the relationship.
This section describes protocol operations that don't fit into any other category.
The ICE no operation (ice-nop) is useful for debugging and diagnosis. Subscribers MAY also use it as a way to poll for the unsolicited-pending flag.
A Sender MAY use the ICE no operation to obtain the ICE version of a receiver. The ICE version is used to determine if the sender can inter-operate with the receiver. For maximum interoperability, senders SHOULD send the ice-nop with the syntax of ICE at its major version number and a minor version of 0. If this is done, all ICE processors with the major version and any minor version will be able to respond to the request, thus maximizing the number of potential relationships.
The format of ice-nop is:
| ice-nop format |
<!ELEMENT ice-nop EMPTY > |
There are no attributes and there is no element body. The response message is normally just a 200 (OK) code.
The no operation request can be sent by Subscribers or Syndicators.
ICE provides a way for an administrator on either the Subscriber or the Syndicator to send a text message to the other system. The intent is that these text messages would be taken by the ICE tool and displayed to an appropriate user in some form. These messages are a good way to communicate planned system level events such as planned down time, or expected changes in the nature of the subscription ("starting next week, we're shipping 100MB of video files with every headline"), etc.
ICE provides no semantic interpretation of the message content whatsoever.
The format of the ice-notify request is:
| ice-notify format |
<!ELEMENT ice-notify (ice-text+) >
<!ATTLIST ice-notify
priority (1 | 2 | 3 | 4 | 5) #REQUIRED
>
|
The body of the element contains one or more text messages. The sole attribute is:
While ICE addresses the core problem of the syndication of digital assets, a number of factors contribute to the necessity that it also support a structured extension mechanism such that as yet unanticipated operating scenarios may be addressed within the protocol's framework. One such factor is the desire to send unescaped XML mark-up as the content within an "ice-item" tag. Another is the desire to programmatically negotiate over domain-specific parameters (such as video encodings) in a formalized way. And another is the desire to leverage the negotiation facilities in ICE before, in fact, boot-strapping to message exchanges that are outside the ICE protocol entirely (see section 8.4.1). To that end, ICE provides an extension mechanism that preserves interoperability among implementations while allowing unanticipated domain-specific scenarios to be addressed, as well. This section describes each of the permissible types of extension and provides examples of their use.
Extensibility in ICE is permitted in four ways:
The general Parameter negotiation mechanism and its use for defining and negotiating additional parameters has been described in section 4.4. Each of the remaining methods is discussed below.
Content-model extensibility is defined in terms of the locations within the grammar (as defined by the DTD) below which domain-specific document structures may be added.
| note: | The ICE Authoring Group expects this scheme to change with version 2.0 of the specification, by which time XML schemas and name spaces are expected to have fully emerged, thus allowing these enforced-by-policy restrictions to be formalized. |
ICE was designed to allow for other XML mark-up to be used within its framework using XML facilities, but without modifying the core ICE DTD itself. This gives ICE applications and users the ability to use ICE beyond what the authors had originally designed. There are three specific areas of content model extensibility that the authors felt were important to allow for alternative mark-up: the format of the events returned in the ice-events response, the content contained within the ice-item element, and the mark-up used within an ice-package element. In all three cases, the basic mechanism is the same, but the implications and expectations of extending the mark-up changes slightly.
Three package formats exist for delivering content using ICE.
The XML elements in the ICE DTD below which the definition of further document structure is permitted are:
ICE is extended through content model extension by permitting any of these elements to be redefined in the DTD to contain domain-specific elements. The word "contain" is carefully chosen: to maintain interoperability, the existing attributes and structures MUST NOT be changed; applications are only allowed to make additions to the DTD below these elements.
Extension is allowed below ice-item, ice-events, and ice-package.
Note; Extension at the ICE package package level ( i.e. %cm.package is redefined) defeats ICE's interoperability goal since, ICE implementations MAY support Syndicators who modify or extend ice-packages...
The ability for Syndicators and subscribers to completely define a package content model was compelling to the authoring group as a means to ensure general ability to carry any XML content.
When extending ICE via redefining the %cm.package mechanism, each element defined in the extended %cm.package MUST have %attlist.item as (part of) it's attribute list. Also it is required that every %cm.package level element inserted through extension MUST have an attribute named ice-element whose value declares how the element is to be treated by the ice processor; specifically as an ice-item, ice-item-group or ice-item-ref. Therefore, the ICE processor can treat (for ICE protocol purposes), the elements AS IF they were respectively one of an ice-item, an ice-item-group or an ice-item-ref.
If ICE is extended to carry XML structured content using extension below ice-item, the containing content models MUST map to corresponding ICE defined elements. This assures that essential elements in the extended content model can perform ICE level functions. Specifically this requirement means that ICE's collection and package management functions can be supported by ICE processors in the extended content model (and thus assure interoperability). Containing content elements are those elements in the content model defined by the extended definition of %cm.package and/or %cm.item.
Child elements of the extended content models are not required to map to ice elements unless they also appear in %cm.package or in %cm.item, but MAY do so. If the child elements do not map to an ice-element, an ICE processor examines them for well formed XML and if well formed, MUST treat them as opaque application data.
The following define the available mappings for extended elements and their meaning:
| Num. | ice-element Mapping |
Definition and Explanation |
| 1 | ice-item | The extension element behaves in ICE AS IF it were an ice-item. Thus, this element is subject to ice-item operations (ice-item-remove, ice-item, ice-repair-item). It has, in addition to its attributes, all of the attributes defined for an ice-item. Note that elements with this mapping MUST conform to the definition of character data in XML |
| 2 | ice-item-group | The extension element behaves in ICE AS IF it were an ice-item-group. This element MUST have, within it's content model, every extension element that maps to ice-item, ice-item-ref and (recursively), ice-item-group. It has, in addition to its attributes, all of the attributes defined for an ice-item-group. Note that all semantics for ice-item also apply to ice-item group; and thus to every element mapped to ice-item-group. |
| 3 | ice-item-ref | This extension element behaves in ICE AS IF it were an ice-item-ref. This element, in addition to its attributes, has all of the attributes defined for an ice-item-ref. An extension element that is mapped to ice-item-ref is processed by a receiving ICE processor by resolving the reference ( provided by the url attribute ) and obtaining the content from the reference. |
On an extended element, the mapping is accomplished by setting the (default) attribute value, ice-element, to one of "ice-item", "ice-item-group" or "ice-item-ref".
For example, consider the content-model extensions required to syndicate the following document via ICE, without the need for escaping reserved XML tokens:
| Content Model Extensions |
|---|
<article>
<title>ICE, Syndication, and You</title>
<author>I. C. Emmerson</author>
<abstract>
This article discusses the particulars of
syndicating digital assets with ICE.
</abstract>
</article>
|
The syndicator desires to send this document as an ice-item. Before extension, the ice-item element is defined in the DTD as:
<!ENTITY % cm.item "#PCDATA" > <!ELEMENT ice-item (%cm.item;)> |
This element would be redefined in the DTD as follows:
<!ENTITY % cm.item "article*"> <!ELEMENT ice-item (%cm.item;)> <!ELEMENT article (title, author, abstract)> <!ELEMENT title (#PCDATA)> <!ELEMENT author (#PCDATA)> <!ELEMENT abstract (#PCDATA)> |
The ice-item element contains zero-or-more article elements to permit other ice-items to continue to work in the un-extended way. Given the above redefinitions, the relevant segment of an ICE payload now looks like:
| Modifying ice-events Content Model |
|---|
<ice-item content-transfer-encoding="x-native-xml" item-id="28">
<article>
<title>ICE, Syndication, and You</title>
<author>I. C. Emerson</author>
<abstract>
This article discusses the particulars
of syndicating digital assets with ICE.
</abstract>
</article>
</ice-item>
|
The omission of the above ATTLIST definitions is intentional and done for brevity sake. This means that each of the elements will be, by default, treated as ice-items by ICE protocol processors.
If the event log format is desired to be different than ice, the content model for the ice-events element can be modified to describe the mark-up of the content. To extend the content-model for validation purposes, the ice-payload can contain a DOCTYPE declaration that modifies the ENTITY declaration that describes the content for the ice-events element. In the example below, the content-model is modified to use event elements to wrap each log entry.
| Modifying ice-events Content Model |
|---|
<!DOCTYPE ice-payload SYSTEM "ice.dtd" [
<!ENTITY % cm.events "event+" >
<!ELEMENT event (#PCDATA) >
]>
<ice-payload payload-id="ipl-80a56cfe-19980425-33"
timestamp="25-04-1998T09:13:19"
ice.version="1.1" >
<ice-header>
<ice-sender
sender-id="http://www.eggnews.com/"
name="Eggceptional News"
role="syndicator" />
</ice-header>
<ice-response
response-id="irp-80425f38-19980621181600" >
<ice-code numeric="200" phrase="OK"
message-id="irq-80a56cfe-19980425011530" >
</ice-code>
<ice-events format="simple">
<event>something happened</event>
<event>something else happened</event>
</ice-events>
</ice-response>
</ice-payload>
|
Similar to using alternative mark-up for event log format, it may be desirable to modify the content model used for an ice-item. The goal here is to allow validation of the content contained within an ice-item without changing any of the semantics behind its protocol handling. Thus, there is value to know that the XML content distributed using the ICE protocol was packaged and delivered in a valid well formed way, but the management of the content is no different than if it had been escaped for inclusion. In the example below, the comic-strip format is purely fictional and is unknown to represent any work (present or future) that may in fact resemble the format used therein. The mechanism is the same as described in 8.2.3, i.e., all declarations need to be declared within the DOCTYPE declaration, but the content-model being modified is for ice-item.
| Modifying ice-item Content Model |
|---|
<?xml version="1.0"?>
<!DOCTYPE ice-payload SYSTEM "../ice.dtd" [
<!ENTITY % cm.item "comic-strip" >
<!ELEMENT comic-strip (#PCDATA) >
<!ATTLIST comic-strip
author CDATA #REQUIRED
copyright CDATA #REQUIRED
pubdate CDATA #REQUIRED
numpanes CDATA #IMPLIED
title CDATA #REQUIRED
>
]>
<ice-payload ...
<ice-response ...
<ice-package ...
<ice-item-group ...
<ice-item
item-id="431-1"
subscription-element="431-1"
name="Comic"
content-filename="d.gif"
content-type="application/xml"
>
<comic-strip
title="Doones County"
author="Gary Beathard"
numpanes="3"
copyright="United Tribune"
pubdate="20010324">
PdXIWZQ8IiPLHtxqyjZFWt0hHrQcrjxAQ8VquFJS8vDC+
g4SsHSChBRUN0tTxS1wTuMC/242YYPBs87U8IkRlGu4G5
. . .
M7qLNPuTNMlXc8G4sUgXc8dPdREbcFWnM9FndTgkwAAOw==
</comic-strip>
</ice-item>
</ice-item-group>
</ice-package>
</ice-response>
</ice-payload>
|
Replacing the content model for the ice-package element provides a way to leverage ICE applications for managing content segments from arbitrary XML mark-up. Besides the mechanisms shown in the other sections where an element's content model is replaced, replacing the content model for the ice-package element requires that the attributes associated with the ice-item element be applied to appropriate elements within the domain-specific element declarations, otherwise, it is possible that the Subscribers ICE application will not have enough context to know how to manage the delivered content.
There are some restrictions to be aware of when extending the ice-package content model.
<!ENTITY % cm.package "#PCDATA">, instead use elements in the content model such as that shown in the sample below.
<!ENTITY % cm.package "ice-item-group | ice-item | comic-strip | ice-item-ref" >
| Example Extending ice-package |
|---|
<?xml version="1.0"?>
<!DOCTYPE ice-payload SYSTEM "../ice.dtd" [
<!ENTITY % cm.package "(ice-item|comic-strip)+"
>
<!ELEMENT comic-strip (#PCDATA) >
<!ATTLIST comic-strip
author CDATA #REQUIRED
copyright CDATA #REQUIRED
pubdate CDATA #REQUIRED
numpanes CDATA #IMPLIED
title CDATA #REQUIRED
>
<!ENTITY % attlist.item "
activation CDATA #IMPLIED
expiration CDATA #IMPLIED
content-filename CDATA #IMPLIED
content-transfer-encoding (base64 | x-native-xml)
'x-native-xml'
content-type CDATA 'application/octet-stream'
ice-element CDATA #FIXED 'ice-item'
ip-status CDATA #IMPLIED
item-id CDATA #REQUIRED
xml:lang CDATA #IMPLIED
license CDATA #IMPLIED
rights-holder CDATA #IMPLIED
show-credit CDATA #IMPLIED
subscription-element CDATA #IMPLIED
">
<!ATTLIST comic-strip %attlist.item; >
]>
<ice-payload ...
<ice-response ...
<ice-package ...
<comic-strip
item-id="431-1"
subscription-element="431-1"
content-type="phrase/html"
title="Doones County"
author="Gary Beathard"
numpanes="3"
copyright="United Tribune"
pubdate="20010324">
PdXIWZQ8IiPLHtxqyjZFWt0hHrQcrjxAQ8VquFJS8vDC+
g4SsHSChBRUN0tTxS1wTuMC/242YYPBs87U8IkRlGu4G5
. . .
M7qLNPuTNMlXc8G4sUgXc8dPdREbcFWnM9FndTgkwAAOw==
</comic-strip>
</ice-package>
</ice-response>
</ice-payload>
|
It is possible that the content of some subscriptions will require semantic extensions to properly deal with that content. It is also possible that to accomplish a particular form of syndication, completely out-of-band data must be exchanged between the syndicator and the subscriber.
Further, it may be that certain of these extensions are required for successful processing of the payload; or that other extensions are optional but advisable for "optimal" performance.
ICE must be able to adapt to as-yet undefined and unanticipated scenarios. The protocol deals with this requirement as follows.
An ice-negotiable contains a "type" attribute, whose default value is "ice-operation". The "type" attribute may also be specified with value, "ice-extension". An ice-negotiable with this "type" attribute value explicitly identifies an extension to the subscription (and possibly the protocol). Such a parameter MAY be offered for negotiation; or be required to complete the subscription. An ice-extension parameter MAY be defined by either a syndicator (the expected case) or a subscriber. These extensions are outside the standard operation of the ICE protocol other than negotiation. A Syndicator that requires more than 40% of it's total number of subscriptions to have a semantic extension that is not publicly available MUST NOT claim ICE protocol compliance. An ICE processor MUST provide offers that do not require use of subscription or protocol semantic extensions. ICE processors SHOULD permit subscription extensions to be negotiated away without refusing the offer. An ICE processor is not required to provide the same services for a subscription that negotiates away use of semantic extensions. The intent here is to ensure that semantic extensions are limited in scope so that interoperability is achievable at some, if not optimal, level. The negotiation mechanism described in sections 4.4 and 4.5 above is used to define and negotiate the desired set of extensions for a given subscription. Consider the following example:
| Subscription Extension Example |
|---|
<ice-business-term >
<ice-negotiable type="ice-extension">
<!-- note that an <ice-range-define> is optional. -->
<ice-range>
<ice-enum type="ice-extend" select="2">
<ice-enum-item>
<ice-extend uuid="oxaa"
name="Tribune media holographic transcoder extension"/>
</ice-enum-item>
<ice-enum-item>
<ice-extend uuid="oxcc"
name="Microsoft antimatter containment unit extension"/>
</ice-enum-item>
</ice-enum>
<ice-enum type="ice-extend" select="zero-or-more">
<ice-enum-item >
<ice-extend uuid="oxba"
name="vignette monty python recitation engine extension"/>
</ice-enum-item>
</ice-enum>
</ice-range>
</ice-negotiable>
</ice-business-term>
|
Note that, rather than the ice-enum-item elements simply containing character data, they each now delimit an instance of the ice-extend element, denoting that the parameter over which the syndicator and subscriber are negotiating is the availability of extensions to the subscribers ICE implementation. Also note that this process is identical, regardless of the value of the "type" attribute of the ice-negotiable element (be it "subscription" or "protocol"). The effect of these two values of the attribute will be discussed shortly.
In the example above, there are two enumeration blocks. The important difference is the value of the "select" attribute of each block. In the first block, "select" equals 2, indicating that two of the contained enumerations MUST be selected - and the first block happens to contain only two items (extensions for holographic transcoding and antimatter containment). This has the effect of allowing the syndicator to express "mandatory" extensions. Another indicator is to use the status="required" attribute on the ice-enum
Similarly, the second enumeration block containing the Vignette extension has a "select" value of "zero-or-more" - this time, the effect being that the extension is "optional". At this point, the issue becomes, what if the subscriber does not have all the mandatory extensions available to it? In the case that the subscriber is not able to use any of the mandatory extensions (because, for example, a particular extension is not installed with the subscribers ICE implementation), the syndicator MUST fall back to core, unextended ICE for the subscription in question. This may very well mean that no subscription is established at all, but it also allows for some service, even if degraded. In the case that the subscriber is not able to use all the optional extensions, the syndicator MUST allow the offer-negotiation to continue AS IF the optional extensions had not been accepted. Note that this could mean that no subscription is established.
In all cases, the "uuid" attribute is an identifier uniquely (in the universe) specifying the module that should be invoked to process the extension, and the "name" attribute is a human-readable description.
It is possible that to accomplish a particular form of syndication, completely out-of-band data must be exchanged between the syndicator and the subscriber. Further, it may be that certain of these extensions are required for successful processing of the payload; or that other extensions are optional but advisable for "optimal" performance.
ICE must be able to adapt to as-yet undefined and unanticipated scenarios. The protocol deals with this requirement as follows.
An ice-offer contains a "type" attribute, that indicates if an offer is for protocol extension with a value of "protocol". Note that this type attribute is different from the type attribute on an ice-negotiable. Only in a subscription offer with type="protocol" can extensions to the basic ICE protocol be proffered and negotiated. That is extensions that add or change ICE-requests and ICE-responses or any other payload level changes MUST be negotiated in a protocol type subscription offer. Payload level extensions MUST NOT be used without successful establishment of a protocol level subscription. Once a protocol level subscription relationship is established between a Syndicator and a Subscriber, any Protocol extensions negotiated are freely usable in ALL protocol interchanges between the two -- including subscription payload interchange.
Now we turn to the semantics of the "type" attribute of the ice-offer element. If the value of this attribute is "protocol", then further definitions in the DTD are required. The relevant portions of the DTD are as follows:
| Extensions to Requests and Responses |
<!ENTITY % cm.extension-response "EMPTY"> |
<!ENTITY % cm.extension-request "EMPTY" > |
<!ENTITY % sub.requests "ice-cancel |
ice-get-catalog |
ice-get-package |
ice-get-sequence |
ice-offer |
ice-repair-item"
>
|
<!ENTITY % syn.requests "ice-package+ | ice-send-confirmations" > |
<!ENTITY % com.requests "ice-change-subscription |
ice-code |
ice-get-events |
ice-get-status |
ice-nop |
ice-notify |
ice-extension-request"
>
|
<!ELEMENT ice-extension-request %cm.extension-request; > |
<!ELEMENT ice-request (%sub.requests; |
%syn.requests; |
%com.requests;)
>
|
<!ENTITY % uni.responses "ice-cancellation |
ice-catalog |
ice-location |
ice-offer |
ice-package+ |
ice-sequence |
ice-subscription"
>
|
<!ENTITY % com.responses "ice-events |
ice-status |
ice-extension-response"
>
|
<!ELEMENT ice-extension-response %cm.extension.response; ) > |
<!ELEMENT ice-response ( ice-code,
( %uni.responses; |
%com.responses;
)?
)
>
|
In the event that a protocol-level extension was negotiated, the first two entities, "cm.extend-response" and "cm.extend-request", MUST be redefined to be a content model containing the extended document structure that is to be used by the extension. At this point, the messaging semantics via ICE become wide open. For example, below is a partial message sent by a syndicator that has arranged to employ protocol level extensions with a particular peer:
| Protocol Extension Example |
|---|
<ice-payload ice.version="1.1">
<ice-request request-id="12345">
<ice-extend-request>
<completely-out-of-band>
...
</completely-out-of-band>
</ice-extend-request>
</ice-request>
</ice-payload>
|
It is important to note that, while extensions at these levels (particularly at the protocol level, where messages are wrapped with little more than an "ice-payload" pair) allow a great deal of flexibility in ICE, fundamental inter operability of the protocol is preserved. The reason that this is the case is that in order to even establish the possibility of extended ICE message exchanges in the first place, ICE offer-negotiation must take place between the syndicator and subscriber.
In other words, until a subscription is established, core, unextended ICE is being spoken.
It is conceivable that peers in an ICE-based relationship will require the ability to send out-of-band messages to each other -- "out-of-band" in the sense that the messages are outside the scope of ordinary ICE conversations dealing with offer negotiation, subscription establishment, updates, confirmation, and so on. This example illustrates one such case and how the extension mechanism introduced in ICE protocol version 1.1 accommodates it.
Consider the case that a particular subscriber expects periodic down-time for its ICE server, the duration of which will frequently span multiple delivery windows such that syndicated pushes of subscription updates will fail. The syndicator would like to handle these cases more cleanly than by simply retrying the update at a later time -- it would like to know when to stop updates and when to resume them. Such a scenario could arise if the subscriber connects to the network via a dialup connection or plans on a hardware upgrade to their ICE server.
The first step that must be taken in order to allow messages of this nature to be exchanged is that their existence at all must be negotiated. Negotiation takes place in the context of subscription establishment. Thus, the subscriber initiates with a request for a catalog:
| Catalog Request |
|---|
<ice-payload ice.version="1.1"
payload-id="74"
timestamp="2000-09-22T04:37:00"
sender-location="http://ice.samico.com/ice/">
<ice-header>
<ice-sender sender-id="aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
name="sami co. ice subscriber"
role="subscriber"/>
</ice-header>
<ice-request request-id="74">
<ice-get-catalog/>
</ice-request>
</ice-payload>
|
The syndicator responds with a catalog containing two subscription offers:
| Catalog Response containing two offers |
|---|
<ice-payload ice.version="1.1"
payload-id="74"
timestamp="2000-09-22T04:37:03"
sender-location="http://ice.bruceco.com/ice/">
<ice-header>
<ice-sender sender-id="bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
name="bruce co. ice syndicator"
role="syndicator"/>
</ice-header>
<ice-response response-id="74">
<ice-code numeric="200" phrase="OK"/>
<ice-catalog>
<ice-contact description="Call him if something crashes."
name="Bruce Hunt, CEO, Bruce Co.">
Bruce Hunt
bhunt@bruceco.com
(123) 456 7890
</ice-contact>
<ice-offer type="protocol"
description="Let's send down-time messages.">
<ice-delivery-policy>
<ice-delivery-rule mode="pull"/>
</ice-delivery-policy>
<ice-negotiable id="down-time-msg"
type="ice-extension">
<ice-text>
Acceptance of this offer will allow us to
exchange messages outside the scope of
normal ICE communication.
The enclosing elements will be defined in
the following "ice-range" block.
</ice-text>
<ice-range order="enumeration">
<ice-enum select="2" status="required"
order="enumeration"
status="negotiable">
<ice-enum-item>
down-time
</ice-enum-item>
<ice-enum-item>
down-time-ack
</ice-enum-item>
</ice-enum>
</ice-range>
</ice-negotiable>
</ice-offer>
<ice-offer type="subscription"
description="bruce co. press releases">
<ice-delivery-policy>
<ice-delivery-rule mode="push"/>
</ice-delivery-policy>
<ice-negotiable id="press_releases"
type="credit">
<ice-text>
This subscription provides bruce co. press releases.
Permission to quote is hereby granted if credited
with (c)1999 bruce co. all rights reserved.
<ice-text/>
</ice-negotiable>
</ice-offer>
</ice-catalog>
</ice-response>
</ice-payload>
|
These two messages comprise a complete ICE request/response pair, at which point the contents of the catalog are propagated up to the end-user of the subscribers ICE software. This user initiated the original catalog request (the first message above) because he knew of both the expected down-time of his ICE server and the availability of an out-of-band message that could temporarily suspend subscription updates from the syndicator.
The subscribers ICE software presents two possible subscriptions. The end-user is only concerned with the protocol extension and so ignores the press-release offer.
The remaining offer has a type of "protocol", indicating that a protocol-level extension is being offered. This protocol offer contains a delivery policy and an ice-negotiable. The delivery policy may be ignored completely in the case of protocol offers because the semantics of protocol-extended message exchange are completely (and necessarily) outside of ICE. The required elements and attributes must be supplied as shown above to preserve backward compatibility with earlier, pre-extensible versions of ICE. This point will be clarified when the mechanics of protocol-extended message exchange are covered later in this example.
This protocol offer also contains an ice-negotiable whose identifier is "down-time-msg" and whose type is "ice-extension". The type denotes that extensions are to be negotiated over. The identifier simply allows this element to be distinguished from others within this same offer. Because this is the only ice-negotiable present in this offer, the identifier value is not significant here.
The "ice-negotiable" delimits an "ice-text" element, which is simply free-form text for an end-user, and an "ice-range" element whose "order" attribute describes the nature of the enclosed value specifiers. In this case, ICE is using the apparatus defined earlier for the purposes of arbitrary parameter and value negotiation to specify the "wrapper elements", that is; to enclose the out-of-band messaging desired by the syndicator and the subscriber. This is done by specifying an enumeration with a two values (namely, the wrapper element types) with a select "2" constraint and a "required" status. (i.e., "If you want this subscription at all, you have to choose this item.").
Presumably, all the end-user sees is the free-form text ("Acceptance of this offer..."), at which point he indicates to his ICE subscriber software his desire to accept the offer. In response, the subscriber sends the following message to the syndicator, which is little more than the unchanged offer sent by the syndicator:
| Subscriber Offer Accepting Protocol Extension |
|---|
<ice-payload ice.version="1.1"
payload-id="75"
timestamp="2000-09-22T04:40:00"
sender-location="http://ice.samico.com/ice/">
<ice-header>
<ice-sender sender-id="ssssssss-ssss-ssss-ssss-ssssssssssss"
name="sami co. ice subscriber"
role="subscriber"/>
</ice-header>
<ice-request request-id="75">
<ice-offer type="protocol"
description="Let's us send down-time messages.">
<ice-delivery-policy>
<ice-delivery-rule mode="pull"/>
</ice-delivery-policy>
<ice-negotiable id="down-time-msg"
type="ice-extension">
<ice-text>
Acceptance of this offer will allow us to
exchange messages outside the scope of
normal ICE communication.
The enclosing elements will be defined in
the following "ice-range" block.
</ice-text>
<ice-range order="enumeration">
<ice-enum select="2" order="enumeration"
status="accepted" >
<ice-enum-item >
down-time
</ice-enum-item >
<ice-enum-item>
down-time-ack
</ice-enum-item>
</ice-enum>
</ice-range>
</ice-negotiable>
</ice-offer>
</ice-request>
</ice-payload>
|
The syndicator indicates that a subscription has been established by enclosing the agreed-upon offer within an "ice-subscription" block:
| Subscription Established Response |
|---|
<ice-payload ice.version="1.1"
payload-id="75"
timestamp="2000-09-22T04:40:03"
sender-location="http://ice.bruceco.com/ice/"
>
<ice-header>
<ice-sender sender-id="bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
name="bruce co. ice syndicator"
role="syndicator"/>
</ice-header>
<ice-response response-id="75">
<ice-code numeric="200" phrase="OK"/>
<ice-subscription subscription-id="down-time-protocol-ext">
<ice-offer type="protocol"
description="Let's us send down-time messages.">
<ice-delivery-policy>
<ice-delivery-rule mode="pull"/>
</ice-delivery-policy>
<ice-negotiable id="down-time-msg"
type="ice-extension">
<ice-text>
Acceptance of this offer will allow us to
exchange messages outside the scope of
normal ICE communication.
The enclosing elements will be defined in
the following "ice-range" block.
</ice-text>
<ice-range order="enumeration">
<ice-enum select="2" order="enumeration">
<ice-enum-item>
down-time
</ice-enum-item>
<ice-enum-item>
down-time-ack
</ice-enum-item>
</ice-enum>
</ice-range>
</ice-negotiable>
</ice-offer>
</ice-subscription>
</ice-response>
</ice-payload>
|
Communication via protocol-extended ICE may now begin between this particular subscriber and this particular syndicator. If another subscriber wishes to be able to send down-time messages, it must engage in this negotiation process.
Since out-of-band protocol messages have been negotiated, the following exchange of an expected subscriber client down-time message between this syndicator and subscriber is now possible. It is important to note that the DTDs that are referenced or included in the ICE messages that are sent must now define the entities "ice-extension.request" and "ice-extension.response" to contain the content-model of the protocol extensions. In the case of this simple example, these would be defined as "down-time" and "down-time-ack", respectively. The subscriber sends the following message:
| Down-time Message using Protocol Extension |
|---|
<ice-payload ice.version="1.1"
payload-id="76"
timestamp="2000-09-22T04:45:00"
sender-location="http://ice.samico.com/ice/"
>
<ice-header>
<ice-sender sender-id="ssssssss-ssss-ssss-ssss-ssssssssssss"
name="sami co. ice subscriber"
role="subscriber"/>
</ice-header>
<ice-request request-id="76">
<ice-extension-request>
<down-time from="2000-09-24T22:00:00"
to="2000-09-25T04:00:00"/>
</ice-extension-request>
</ice-request>
</ice-payload>
|
To which the syndicator replys with a simple acknowledgement:
| Down-time Message Response |
|---|
<ice-payload ice.version="1.1"
payload-id="76"
timestamp="2000-09-22T04:45:03"
sender-location="http://ice.bruceco.com/ice/" >
<ice-header>
<ice-sender sender-id="bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
name="bruce co. ice syndicator"
role="syndicator" />
</ice-header>
<ice-response response-id="76">
<ice-code numeric="200" phrase="OK"/>
<ice-extension-response>
<down-time-ack numeric="1000" phrase="ok"/>
</ice-extension-response>
</ice-response>
</ice-payload>
|
Presumably, this message will translate into some sort of action on the Syndicator's part to ensure that deliveries are postponed for this subscriber until after the down-time window. These actions and the semantics of the messages themselves are entirely defined by the employing application and are outside of ICE.
Note that the solution just described could be applied in many similar cases. If the syndicator expects down-time and would like to prevent its subscribers from believing that the maximum update interval has been exceeded, it might use similar out-of-band notifications.
<!-- ============================================================ -->
<!-- -->
<!-- ICE 1.1 Document Type Definition -->
<!-- 15 November 1999 -->
<!-- -->
<!-- ============================================================ -->
<!-- ============================================================ -->
<!-- = For protocol level ice extensions, change the value of -->
<!-- = extended.protocol to "INCLUDE" and the value of -->
<!-- = standard.protocol to "IGNORE". Be SURE to also provide -->
<!-- = content models for the extension request and extension -->
<!-- = response elements. Also, be SURE to declare the elements -->
<!-- = and associated attribute lists for the extended requests -->
<!-- = and responses below. -->
<!-- = ( ARE YOU VERY SURE YOU WANT TO DO THIS? ?REALLY-REALLY? ) -->
<!-- ============================================================ -->
<!ENTITY % extended.protocol "IGNORE" >
<!ENTITY % standard.protocol "INCLUDE" >
<![%extended.protocol;[
<!-- ============================================================ -->
<!-- = Place extended protocol request content model in value of -->
<!-- = cm.extension-request below. -->
<!-- ============================================================ -->
<!ENTITY % cm.extension-request "EMPTY" >
<!-- ============================================================ -->
<!-- = Place extended protocol response content model in value of -->
<!-- = cm.extension-response below. -->
<!-- ============================================================ -->
<!ENTITY % cm.extension-response "EMPTY" >
]]>
<![%standard.protocol;[
<!ENTITY % cm.extension-request "EMPTY" >
<!ENTITY % cm.extension-response "EMPTY" >
]]>
<!ENTITY % cm.messages "ice-request+ |
ice-response+ |
ice-unsolicited-now |
ice-unsolicited-request+ |
ice-unsolicited-response+" >
<!ELEMENT ice-payload (ice-header, (%cm.messages;)) >
<!ATTLIST ice-payload
ice.version CDATA #REQUIRED
payload-id CDATA #REQUIRED
timestamp CDATA #REQUIRED
sender-location CDATA #IMPLIED
>
<!-- NOTE that in ICE 1.1 sender-location MUST be specified; it
is optional here for interoperability.
-->
<!ELEMENT ice-header (ice-sender, ice-receiver?, ice-user-agent?) >
<!ELEMENT ice-sender EMPTY >
<!ATTLIST ice-sender
name CDATA #REQUIRED
role (subscriber | syndicator)
#REQUIRED
sender-id CDATA #REQUIRED
>
<!ELEMENT ice-receiver EMPTY >
<!ATTLIST ice-receiver
name CDATA #REQUIRED
receiver-id CDATA #REQUIRED
>
<!ELEMENT ice-user-agent (#PCDATA) >
<!ELEMENT ice-code (#PCDATA) >
<!ATTLIST ice-code
message-id CDATA #IMPLIED
numeric CDATA #REQUIRED
package-id CDATA #IMPLIED
payload-id CDATA #IMPLIED
phrase CDATA #REQUIRED
xml:lang CDATA #IMPLIED
>
<!-- ============================================================ -->
<!-- Declaration of ICE requests. -->
<!-- ============================================================ -->
<!ENTITY % sub.requests "ice-cancel |
ice-get-catalog |
ice-get-package |
ice-get-sequence |
ice-offer |
ice-repair-item" >
<!ENTITY % syn.requests "ice-package+ |
ice-send-confirmations" >
<![%standard.protocol;[
<!ENTITY % com.requests "ice-change-subscription |
ice-code |
ice-get-events |
ice-get-status |
ice-nop |
ice-notify" >
]]>
<![%extended.protocol;[
<!ENTITY % com.requests "ice-change-subscription |
ice-code |
ice-get-events |
ice-get-status |
ice-nop |
ice-notify |
ice-extension-request" >
]]>
<!ELEMENT ice-request ( %sub.requests; |
%syn.requests; |
%com.requests; ) >
<!ATTLIST ice-request
request-id CDATA #REQUIRED
>
<!ELEMENT ice-cancel EMPTY >
<!ATTLIST ice-cancel
xml:lang CDATA #REQUIRED
reason CDATA #REQUIRED
subscription-id CDATA #REQUIRED
>
<!ELEMENT ice-change-subscription EMPTY >
<!ATTLIST ice-change-subscription
subscription-id CDATA #REQUIRED
>
<!-- ice-code defined above -->
<!ELEMENT ice-get-catalog EMPTY >
<!ELEMENT ice-get-events EMPTY >
<!ATTLIST ice-get-events
format NMTOKENS #IMPLIED
start CDATA #IMPLIED
stop CDATA #IMPLIED
subscription-id CDATA #IMPLIED
>
<!ELEMENT ice-get-package EMPTY >
<!ATTLIST ice-get-package
current-state CDATA #REQUIRED
parameter CDATA #IMPLIED
subscription-id CDATA #REQUIRED
>
<!ELEMENT ice-get-sequence (ice-package-state+) >
<!ATTLIST ice-get-sequence
current-state CDATA #REQUIRED
subscription-id CDATA #REQUIRED
>
<!ELEMENT ice-package-state EMPTY >
<!ATTLIST ice-package-state
package-id CDATA #REQUIRED
new-state CDATA #REQUIRED
>
<!ELEMENT ice-get-status EMPTY >
<!ATTLIST ice-get-status
subscription-id CDATA #IMPLIED
>
<!ELEMENT ice-nop EMPTY >
<!ELEMENT ice-notify (ice-text+) >
<!ATTLIST ice-notify
priority (1 | 2 | 3 | 4 | 5)
#REQUIRED
>
<![%extended.protocol;[
<!ELEMENT ice-extension-request %cm.extension-request >
]]>
<!ELEMENT ice-text (#PCDATA) >
<!ATTLIST ice-text
xml:lang CDATA #IMPLIED
>
<!-- ice-offer is declared below. -->
<!-- ice-package is declared below -->
<!ELEMENT ice-repair-item EMPTY >
<!ATTLIST ice-repair-item
current-state CDATA #REQUIRED
subscription-element CDATA #REQUIRED
subscription-id CDATA #REQUIRED
>
<!ELEMENT ice-send-confirmations EMPTY >
<!ATTLIST ice-send-confirmations
subscription-id CDATA #IMPLIED
>
<!-- ============================================================ -->
<!-- Declaration of ICE responses. -->
<!-- ============================================================ -->
<!ENTITY % uni.responses "ice-cancellation |
ice-catalog |
ice-location |
ice-offer |
ice-package+ |
ice-sequence |
ice-subscription" >
<![%standard.protocol;[
<!ENTITY % com.responses "ice-events |
ice-status" >
]]>
<![%extended.protocol;[
<!ENTITY % com.responses "ice-events |
ice-status |
ice-extension-response" >
]]>
<!ELEMENT ice-response (ice-code, (%uni.responses; |
%com.responses;)?) >
<!ATTLIST ice-response
response-id CDATA #REQUIRED
unsolicited-pending (false | true) "false"
>
<!ELEMENT ice-cancellation EMPTY >
<!ATTLIST ice-cancellation
cancellation-id CDATA #REQUIRED
subscription-id CDATA #REQUIRED
>
<!ELEMENT ice-catalog ( ice-contact,
( ice-offer-group | ice-offer )*
)
>
<!ATTLIST ice-catalog
description CDATA #IMPLIED
xml:lang CDATA #IMPLIED
name CDATA #IMPLIED
url CDATA #IMPLIED
>
<!ELEMENT ice-contact (#PCDATA | ice-text)* >
<!ATTLIST ice-contact
description CDATA #REQUIRED
xml:lang CDATA #IMPLIED
name CDATA #REQUIRED
url CDATA #IMPLIED
>
<!ELEMENT ice-offer-group (ice-offer-group+ | ice-offer+) >
<!ATTLIST ice-offer-group
description CDATA #REQUIRED
>
<!-- ice-offer declared below -->
<!ENTITY % cm.events "ice-event-log" >
<!ELEMENT ice-events (%cm.events;) >
<!ATTLIST ice-events
format CDATA #REQUIRED
start CDATA #IMPLIED
stop CDATA #IMPLIED
subscription-id CDATA #IMPLIED
>
<!ELEMENT ice-location EMPTY >
<!ATTLIST ice-location
target CDATA #REQUIRED
>
<!-- ice-offer is declared below. -->
<!-- ice-package is declared below. -->
<!ELEMENT ice-sequence (ice-package-state*) >
<!ATTLIST ice-sequence
subscription-id CDATA #REQUIRED
>
<!ELEMENT ice-status (ice-contact, ice-subscription+) >
<![%extended.protocol;[
<!ELEMENT ice-extension-response %cm.extension-response; >
]]>
<!ELEMENT ice-subscription (ice-offer) >
<!ATTLIST ice-subscription
current-state CDATA #IMPLIED
expiration-date CDATA #IMPLIED
expiration-priority (first | last) #IMPLIED
quantity-remaining CDATA #IMPLIED
subscription-id CDATA #REQUIRED
>
<!-- ============================================================ -->
<!-- Declaration of ICE unsolicited messages. -->
<!-- ============================================================ -->
<!ELEMENT ice-unsolicited-now EMPTY >
<!ATTLIST ice-unsolicited-now
request-id CDATA #REQUIRED
>
<!ELEMENT ice-unsolicited-request (%syn.requests; |
%com.requests;) >
<!ATTLIST ice-unsolicited-request
unsolicited-request-id CDATA #REQUIRED
>
<!ELEMENT ice-unsolicited-response (ice-code, (%com.responses;)?) >
<!ATTLIST ice-unsolicited-response
unsolicited-response-id CDATA #REQUIRED
>
<!-- ============================================================ -->
<!-- Declaration of ice-offer -->
<!-- ============================================================ -->
<!ELEMENT ice-offer ( ice-delivery-policy, ice-business-term* ) >
<!ATTLIST ice-offer
offer-id CDATA #IMPLIED
constraints-hash CDATA #IMPLIED
constraints-hash-method CDATA #IMPLIED
constraints-url CDATA #IMPLIED
description CDATA #REQUIRED
expiration-date CDATA #IMPLIED
product-name CDATA #IMPLIED
subscription-id CDATA #IMPLIED
atomic-use (false | true) "false"
editable (false | true) "false"
ip-status CDATA #IMPLIED
rights-holder CDATA #IMPLIED
show-credit (true | false) "false"
usage-required (true | false) "false"
type (protocol | subscription) "subscription"
>
<!ELEMENT ice-business-term ( #PCDATA |
ice-text |
ice-negotiable
)*
>
<!ATTLIST ice-business-term
xml:lang CDATA #IMPLIED
type ( credit |
licensing |
payment |
reporting ) #REQUIRED
url CDATA #IMPLIED
name CDATA #IMPLIED
id ID #IMPLIED
>
<!ELEMENT ice-delivery-policy (ice-delivery-rule+) >
<!ATTLIST ice-delivery-policy
startdate CDATA #IMPLIED
stopdate CDATA #IMPLIED
>
<!ELEMENT ice-delivery-rule (ice-negotiable*) >
<!ATTLIST ice-delivery-rule
mode (push | pull) #REQUIRED
monthday NMTOKENS #IMPLIED
weekday NMTOKENS #IMPLIED
startdate CDATA #IMPLIED
starttime CDATA #IMPLIED
stopdate CDATA #IMPLIED
duration CDATA #IMPLIED
min-update-interval CDATA #IMPLIED
max-update-interval CDATA #IMPLIED
min-num-updates CDATA #IMPLIED
max-num-updates CDATA #IMPLIED
url CDATA #IMPLIED
maxcount CDATA #IMPLIED
maxfreq CDATA #IMPLIED
mincount CDATA #IMPLIED
minfreq CDATA #IMPLIED
>
<!-- ============================================================ -->
<!-- Declaration of ice-negotiable -->
<!-- ============================================================ -->
<!ELEMENT ice-negotiable ( ice-text | ice-range )* >
<!-- The type attribute defined below MUST have ONE of the following
values:
ice-operation - signals ice operational parameter.
ice-extension - signals extended parameter.
x-- - where is replaced
by an ice-processor's domain name. negotiable
sets in this category are provided for private
use.
ice- - All forms of category names prefixed with
ice, icE, iCe, iCE, Ice, ... are reserved for
future standardization.
The following values are deprecated in ICE 1.1 and are
included only for minor version interoperability. Use
the built-in ice-range-defines instead.
These parameter names mean that this ice-negotiable applies to
their same-named counterpart in the containing ice-delivery-rule.
duration -
maxcount -
max-num-updates -
maxfreq -
max-update-interval
mincount -
min-num-updates -
minfreq -
min-update-interval
monthday -
startdate -
starttime -
stopdate -
weekday -
The max and min attributes are deprecated in ICE 1.1 and are
included only for minor version interoperability. Use
the built-in ice-range-defines instead.
-->
<!ATTLIST ice-negotiable
id ID #IMPLIED
type NMTOKEN #REQUIRED
max CDATA #IMPLIED
min CDATA #IMPLIED
>
<!ELEMENT ice-range ( ice-range-define?, ice-text*,
( ice-span | ice-enum )+
)
>
<!ATTLIST ice-range
id ID #IMPLIED
name CDATA #IMPLIED
description CDATA #IMPLIED
order ( numeric |
lexical |
time |
enumeration
) "numeric"
>
<!ELEMENT ice-range-define ( ice-span | ice-enum )+ >
<!ATTLIST ice-range-define
id ID #IMPLIED
name CDATA #IMPLIED
description CDATA #IMPLIED
>
<!-- ============================================================ -->
<!-- Declaration of ice-span -->
<!-- ============================================================ -->
<!ELEMENT ice-span ( ice-default-value? ,
ice-span-min? ,
ice-span-point* ,
ice-span-max?
)
>
<!ATTLIST ice-span
id ID #IMPLIED
ref IDREF #IMPLIED
name CDATA #IMPLIED
description CDATA #IMPLIED
status ( required |
negotiable |
accepted
) "negotiable"
order ( numeric |
lexical |
time |
enumeration
) "numeric"
>
<!ELEMENT ice-default-value (#PCDATA) >
<!ATTLIST ice-default-value
id ID #IMPLIED
ref IDREF #IMPLIED
name CDATA #IMPLIED
description CDATA #IMPLIED
>
<!ELEMENT ice-span-min ( #PCDATA | ice-limit )* >
<!ATTLIST ice-span-min
id ID #IMPLIED
ref IDREF #IMPLIED
name CDATA #IMPLIED
description CDATA #IMPLIED
>
<!ELEMENT ice-span-max ( #PCDATA | ice-limit )* >
<!ATTLIST ice-span-max
id ID #IMPLIED
ref IDREF #IMPLIED
name CDATA #IMPLIED
description CDATA #IMPLIED
>
<!ELEMENT ice-span-point ( #PCDATA | ice-limit )* >
<!ATTLIST ice-span-point
id ID #IMPLIED
ref IDREF #IMPLIED
name CDATA #IMPLIED
description CDATA #IMPLIED
>
<!ELEMENT ice-limit EMPTY >
<!ATTLIST ice-limit
id ID #IMPLIED
ref IDREF #IMPLIED
name CDATA #IMPLIED
description CDATA #IMPLIED
default CDATA #IMPLIED
>
<!-- ============================================================ -->
<!-- Declaration of ice-enum -->
<!-- ============================================================ -->
<!ELEMENT ice-enum ( ice-default-value, ice-enum-item+ ) >
<!ATTLIST ice-enum
id ID #IMPLIED
ref IDREF #IMPLIED
name CDATA #IMPLIED
description CDATA #IMPLIED
select CDATA #REQUIRED
status ( required |
negotiable |
accepted
) "negotiable"
order ( numeric |
lexical |
time |
enumeration
) "numeric"
>
<!ELEMENT ice-enum-item ( #PCDATA |
ice-extension |
ice-span |
ice-limit
)*
>
<!ATTLIST ice-enum-item
id ID #IMPLIED
ref IDREF #IMPLIED
>
<!ELEMENT ice-extension EMPTY >
<!ATTLIST ice-extension
id ID #IMPLIED
uuid CDATA #REQUIRED
name CDATA #IMPLIED
>
<!-- ============================================================ -->
<!-- Declaration of ice-package -->
<!-- ============================================================ -->
<!ENTITY % cm.content "ice-item-group | ice-item | ice-item-ref" >
<!ENTITY % cm.package "((ice-item-remove+, (%cm.content;)*) |
(%cm.content;)+)" >
<!ENTITY % attlist.item "
activation CDATA #IMPLIED
expiration CDATA #IMPLIED
content-filename CDATA #IMPLIED
content-transfer-encoding (base64 | x-native-xml)
'x-native-xml'
content-type CDATA 'application/octet-stream'
ip-status CDATA #IMPLIED
xml:lang CDATA #IMPLIED
license CDATA #IMPLIED
rights-holder CDATA #IMPLIED
show-credit CDATA #IMPLIED
subscription-element CDATA #IMPLIED
">
<!ENTITY % attlist.item-type "
ice-element ( ice-item |
ice-item-group |
ice-item-ref |
ice-item-remove
) 'ice-item'"
>
<!ELEMENT ice-package (%cm.package;) >
<!ATTLIST ice-package
activation CDATA #IMPLIED
atomic-use (false | true) "false"
confirmation (false | true) "false"
editable (false | true) "false"
exclusion CDATA #IMPLIED
expiration CDATA #IMPLIED
fullupdate (false | true) "false"
xml:lang CDATA #IMPLIED
new-state CDATA #REQUIRED
old-state CDATA #REQUIRED
package-id CDATA #REQUIRED
show-credit CDATA #IMPLIED
subscription-id CDATA #REQUIRED
ip-status CDATA #IMPLIED
license CDATA #IMPLIED
item-repair (false | true) "false"
rights-holder CDATA #IMPLIED
>
<!ELEMENT ice-item-remove EMPTY >
<!ATTLIST ice-item-remove
subscription-element CDATA #REQUIRED
ice-element CDATA #FIXED 'ice-item-remove'
name CDATA #IMPLIED
>
<!ELEMENT ice-item-group ((%cm.package;)+) >
<!ATTLIST ice-item-group %attlist.item;
ice-element CDATA #FIXED 'ice-item-group'
name CDATA #IMPLIED
item-group-id CDATA #REQUIRED
>
<!ENTITY % cm.item "#PCDATA" >
<!ELEMENT ice-item (%cm.item;) >
<!ATTLIST ice-item %attlist.item;
ice-element CDATA #FIXED 'ice-item'
name CDATA #REQUIRED
item-id CDATA #REQUIRED
>
<!ENTITY % cm.access "( ice-access-window?,
ice-access-control?
)" >
<!ELEMENT ice-access %cm.access; >
<!ATTLIST ice-access
name CDATA #IMPLIED
description CDATA #IMPLIED
id ID #IMPLIED
>
<!ENTITY % cm.item-ref "(ice-access)*" >
<!ELEMENT ice-item-ref %cm.item-ref; >
<!ATTLIST ice-item-ref %attlist.item;
url CDATA #REQUIRED
ice-element CDATA #FIXED 'ice-item-ref'
>
<!ENTITY % cm.access-control "(#PCDATA)" >
<!ELEMENT ice-access-control %cm.access-control; >
<!ATTLIST ice-access-control
id ID #IMPLIED
name CDATA #IMPLIED
description CDATA #IMPLIED
control-type ( password |
cookie |
custom ) #REQUIRED
user CDATA #IMPLIED
password CDATA #IMPLIED
access-reference CDATA #IMPLIED
extension-id CDATA #IMPLIED
>
<!ENTITY % cm.access-window "(ice-delivery-policy)" >
<!ELEMENT ice-access-window %cm.access-window; >
<!ATTLIST ice-access-window
id ID #IMPLIED
name CDATA #IMPLIED
description CDATA #IMPLIED
starttime CDATA #IMPLIED
stoptime CDATA #IMPLIED
>
<!-- ============================================================ -->
<!-- Declaration of default ice-event-log -->
<!-- ============================================================ -->
<!ELEMENT ice-event-log ((ice-event-msg | ice-event-info)*) >
<!ATTLIST ice-event-log
version CDATA #REQUIRED
>
<!ELEMENT ice-event-msg (ice-code?, ice-event-data?) >
<!ATTLIST ice-event-msg
other-id CDATA #IMPLIED
request CDATA #REQUIRED
request-id CDATA #REQUIRED
request-start CDATA #REQUIRED
request-type CDATA #IMPLIED
response CDATA #REQUIRED
response-id CDATA #IMPLIED
response-stop CDATA #REQUIRED
response-type CDATA #IMPLIED
role (requestor | responder)
#REQUIRED
subscription-id CDATA #IMPLIED
>
<!ELEMENT ice-event-info (ice-event-data?) >
<!ATTLIST ice-event-info
event CDATA #REQUIRED
event-start CDATA #REQUIRED
event-stop CDATA #REQUIRED
>
<!ELEMENT ice-event-data ANY >
<!-- ============================================================ -->
<!-- End of ICE 1.1 Document Type Definition -->
<!-- ============================================================ -->
The purpose of this Appendix is to set the version identification schema for revision management of the ICE Protocol and its specification releases. This Appendix is normative.
The scope of this Appendix includes all ICE Protocols and specification releases. Further this appendix limits its scope to only the semantics involved, and not to the actual programming or code development which it governs. It is expected that ICE will continue to evolve as new technologies and/or applications developed by others emerge. This section contemplates adaptation by future ICE authors of the results of these new technologies applicable to ICE. It further contemplates that selected improvements and additions to ICE will be necessary from time to time. This includes the deprecation and removal of obsolete features of the protocol. Thus an extensible mechanism for identifying and managing different versions of the ICE protocol is necessary.
The Revision Numbering Sequence for ICE is in decimal format with a decimal points separating integer value place holders as in the following example: 1.0 In general the decimal format is a digit string optionally followed by a sequence of a decimal point followed by a digit string:
| ICE Version Number format |
ICEVersion ::= MajorVersion ( MinorVersion )? MajorVersion ::= positiveDigit digit* MinorVersion ::= '.' digit* positiveDigit ::= 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 digit ::= positiveDigit | 0 |
There are two types of revisions: Major Revisions and Minor Revisions.
A Major Revision is a unique initial digit string preceding the first (optional) decimal point that indicates the Minor Version number. A Major Revision is always greater than zero.
A Minor Revision is a decimal point followed by an optional digit string. The minor version number follows the initial digit string. For example, a minor revision of ICE 1. is ICE 1.01; as is ICE 1.1. Notice that ICE 1.1 is the same as ICE 1.10.
The ICE Authoring Group (or its successor) will determine whether the augmentation of the Standard is of such scope and consequence that it mandates a Major or a Minor revision, as well as the time frame for its release.
Revisions to the Standard MUST include the following:
This statement has strong implications for changes to syntax and semantic function in ICE. In general syntactic changes MUST be compatible among minor versions sharing the same major version. Thus, augmentation of syntax, while possible MUST be optional and default to previous minor versions. Notice that this principle dictated the form of the syntactic extension of ice-business-term introduced in ICE 1.1. This was done specifically to ensure syntactic compatibility with all previous minor versions ( 1.0 and 1.01 ). Also note that the attributes, maxfreq and minfreq have been replaced and deprecated but not removed to preserve compatibility and interoperability. In general semantic changes must be designed to default to previously defined semantics in the absence of (upward) compatible syntactic indicators. And specifically, the semantics MAY define previously undefined function (e.g. the careful specification of negotiation in ICE 1.1 ), but MUST NOT change previously defined semantic function since this jeopardizes interoperability. This is the second reason that attributes are deprecated but not removed in minor versions sharing the same major version. When deprecating a function, the additional semantics of issuing a warning is permitted; but to assure interoperability, the function MUST NOT be removed.
Great care must be given to the determination of whether a particular enhancement necessitates categorization as a Minor or a Major Revision; as the above mechanisms illustrate.
Major Revisions to ICE MAY NOT necessarily include backward compatibility to previously released ICE Standards, independent of the currently available Revision.
A Major Revision is an opportunity for ICE to adopt new technology which may supersede (and obsolete) previous constructs released as part of older Revisions. An organization implementing a lesser revision may be excluded from participating with an organization which employs a greater Major Revision.
All Revisions MUST be accompanied by written documentation which illustrates a list of features relevant to the Revision and the issues, bugs, fixes or enhancements which were addressed as part of the Revision versus the most currently released Revision.
In order to maximize interoperability, the following ice.version resolution process SHOULD be employed by ICE processors desiring to know a targeted ICE processor's version number.
To discover a target processor's ice.version, an inquiring processor sends an ice-nop request using the syntax and semantics of its major version number with a zero minor version number. This request matches the syntax and (therefore) the semantics of an ICE processor with ice.version="&major-version.0". Note however, that the value of the ice.version attribute is set to the inquirers ICE version number. This guarantees that with the sole exception of the ice.version, every ICE processor with major version "&major-version" and ANY minor version can successfully parse the payload. A sample payload for ICE major version 1 is:
| Request is ice-nop with minor version = 0 syntax |
|---|
<?xml version="1.0"?>
<!DOCTYPE ice-payload
SYSTEM "http://www.gca.org/ice/dtds/ICE1_1.dtd"
>
<ice-payload
payload-id="1999-11-30T07:27:09@myenterprise.com"
timestamp="07:27:23,449"
ice.version="1.1" >
<ice-header>
<ice-sender
name="MyEnterprise Corporation"
role="syndicator" />
<ice-user-agent >
MyEnterprise Syndication Services. Please
contact Dan Koger for assistance in Syndication
matters at 1-800-ICE-CALL
</ice-user-agent >
</ice-header >
<ice-request
request-id="1999-11-30T07:29:15@myenterprise.com-1" >
<ice-nop />
</ice-request >
</ice-payload >
|
Note that the payload attribute, sender-location is not part of the payload header in this request because it is part of the semantics of ICE version 1.1 and is not used in this interchange. ICE processors at the 1.0 and 1.01 levels may not know how to process the sender-location attribute and conservative implementations MAY refuse to communicate.
There are only two responses possible to the request; an ice-code of "200 OK" or an ice-code of "320 Incompatible Version". Each response will have the ice.version attribute in the payload header set to the target's ice version number. At a successful conclusion of the interchange, both the target and inquiring processor know each other's version. Each can (intelligently) decide whether to proceed and at which minor version level of semantics to proceed.
This simple exchange allows the widest possible number of ICE processors to respond since ALL processors within a major version MUST be able to respond to minor version 0 requests within that major version.
This basic process MAY be beneficial for all major versions of ICE provided that future versions maintain the same basic syntactic structure for payloads, requests and responses; including the ice-nop operation. However, there can be NO assurance that these conditions will remain in the future.
At major version changes only is there likely to be potential for interoperability issues. To assure maximum interoperability, when such change is contemplated, significant advance notice would be prudent.
They are achieved by providing fall back semantics and a feature deprecation strategy that announces pending changes in feature support prior to removal. These semantics have been exploited to announce the pending removal of several attributes including "cancellation-id", "minfreq", "maxfreq", "mincount" and "maxcount".
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC