Form Output APEX Working Group B. Wyman Internet-Draft D. Werner Expires: September 30, 2002 firstRain, Inc. April 1, 2002 Content-Based Publish-Subscribe over APEX draft-wyman-apex-pubsub-00 Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http:// www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on September 30, 2002. Copyright Notice Copyright (C) The Internet Society (2002). All Rights Reserved. Abstract This memo describes the Content-Based Publish-Subscribe service over APEX. The Content-Based Publish-Subscribe service is designed as an extension to the APEX Publish-Subscribe service, allowing applications to subscribe to specific content within a defined topic, rather than the entire topic. Wyman & Werner Expires September 30, 2002 [Page 1] Internet-Draft APEX PubSub April 2002 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . 4 2. Conventions used in this Document . . . . . . . . . . . 5 3. Overview of the Content-Based Publish-Subscribe System . 6 3.1 Application Roles in the Content-Based Pub-Sub System . 6 3.2 Architecture Overview . . . . . . . . . . . . . . . . . 7 3.3 Operations in the Content-Based PubSub System . . . . . 9 3.3.1 Creating Topics . . . . . . . . . . . . . . . . . . . . 9 3.3.2 Deleting Topics . . . . . . . . . . . . . . . . . . . . 10 3.3.3 Subscribing to Content . . . . . . . . . . . . . . . . . 10 3.3.4 Publishing Messages . . . . . . . . . . . . . . . . . . 11 4. Date and Time Format in the Pub-Sub System . . . . . . . 12 5. Messages, Subscriptions, and Publication . . . . . . . . 13 5.1 Messages in the Content-Based Publish-Subscribe System . 13 5.2 Message Format . . . . . . . . . . . . . . . . . . . . . 13 5.2.1 Message Headers . . . . . . . . . . . . . . . . . . . . 14 5.3 Message Schema . . . . . . . . . . . . . . . . . . . . . 15 5.3.1 Format of Message Schema . . . . . . . . . . . . . . . . 15 5.3.2 Default Message Schema . . . . . . . . . . . . . . . . . 16 5.4 Message Selection . . . . . . . . . . . . . . . . . . . 17 5.4.1 Message Selector Classes . . . . . . . . . . . . . . . . 17 5.5 Selector Schema . . . . . . . . . . . . . . . . . . . . 18 5.5.1 Default Selector Schema . . . . . . . . . . . . . . . . 20 5.6 Message Selectors . . . . . . . . . . . . . . . . . . . 20 5.7 Distribution of Message Selection Functionality . . . . 21 5.8 The Subscribe Operation . . . . . . . . . . . . . . . . 22 5.8.1 Rejection of a Subscription Request . . . . . . . . . . 24 5.8.2 Canceling a Subscription . . . . . . . . . . . . . . . . 25 5.9 Publishing a Message . . . . . . . . . . . . . . . . . . 27 5.9.1 Rejection of a Published Message . . . . . . . . . . . . 27 5.10 Message Delivery . . . . . . . . . . . . . . . . . . . . 27 5.10.1 The "InRe" APEX Option . . . . . . . . . . . . . . . . . 27 5.10.1.1 Using the "InRe" Option in the Pub-Sub System . . . . . 28 6. Topic Management . . . . . . . . . . . . . . . . . . . . 32 6.1 The Well-Known Topic . . . . . . . . . . . . . . . . . . 32 6.2 The Topics Topic . . . . . . . . . . . . . . . . . . . . 32 6.2.1 Listing Topics . . . . . . . . . . . . . . . . . . . . . 35 6.2.2 Topic Updates . . . . . . . . . . . . . . . . . . . . . 35 6.2.3 Creating Topics with the Createtopic Operation . . . . . 36 6.3 The Subscriptions Topic . . . . . . . . . . . . . . . . 38 6.3.1 Access Control and the Subscriptions Topic . . . . . . . 39 7. Initial Registrations . . . . . . . . . . . . . . . . . 41 7.1 Registration Template for Message Selector Classes . . . 41 7.2 Registration: Message Selector Class 'RFC-2254' . . . . 41 7.3 Registration: Message Selector Class 'JMS' . . . . . . . 42 7.4 Registration Template for Well-Known Topics . . . . . . 43 7.5 Registration: The Topics Topic . . . . . . . . . . . . . 44 Wyman & Werner Expires September 30, 2002 [Page 2] Internet-Draft APEX PubSub April 2002 7.6 Registration: The Subscriptions Topic . . . . . . . . . 44 7.7 Registration: The "InRe" APEX Option . . . . . . . . . . 44 8. DTDs and XML Schemas . . . . . . . . . . . . . . . . . . 46 8.1 The Content-Based Publish-Subscribe DTD . . . . . . . . 46 8.2 The Content-Based Pub-Sub Schema . . . . . . . . . . . . 47 8.3 The 'Topics' Topic Schema . . . . . . . . . . . . . . . 49 8.4 The 'Subscriptions' Topic Schema . . . . . . . . . . . . 50 9. Security Considerations . . . . . . . . . . . . . . . . 52 References . . . . . . . . . . . . . . . . . . . . . . . 53 Authors' Addresses . . . . . . . . . . . . . . . . . . . 54 A. Error Codes . . . . . . . . . . . . . . . . . . . . . . 55 B. Notes to this Memorandum . . . . . . . . . . . . . . . . 56 B.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 C. Acknowledgements . . . . . . . . . . . . . . . . . . . . 57 Full Copyright Statement . . . . . . . . . . . . . . . . 58 Wyman & Werner Expires September 30, 2002 [Page 3] Internet-Draft APEX PubSub April 2002 1. Introduction The APEX publish-subscribe system described in [1] specifies a framework for distributing content from individual publishers to a large number of potential subscribers. Within a publish-subscribe framework, it is anticipated that an excess of messages will be generated that are not of interest to all subscribers. The case of NNTP illustrates this problem. Undesired messages may be filtered upon receipt by subscribing applications. However, the delivery of undesired messages, particularly in large-scale deployments of a publish-subscribe system, will result in unnecessary network traffic. The content-based publish-subscribe system described in this memo extends the topic-based publish-subscribe system defined in [1] to provide content-based subscription to information within particular topics. Content-based subscription allows applications to receive only messages of interest within particular topics, reducing overall network usage by the service and increasing usability of the service. This memo describes a framework for implementing a content-based publish-subscribe system over APEX. The content-based publish- subscribe system described herein is designed as a set of extensions to the topic-based publish-subscribe system defined in [1]. The operations defined in [1] are incorporated by the content-based pub-sub system. The subscribe operation of [1] is extended to provide for content-based subscriptions, and the cancel operation of [1] is extended to provide for management of multiple subscriptions to a single topic. Additional error codes are defined with respect to these operations. This memo introduces the concept of a well-known topic, and a well- known topic is defined for use in describing, listing and modifying topics. Wyman & Werner Expires September 30, 2002 [Page 4] Internet-Draft APEX PubSub April 2002 2. Conventions used in this Document 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 [2]. Wyman & Werner Expires September 30, 2002 [Page 5] Internet-Draft APEX PubSub April 2002 3. Overview of the Content-Based Publish-Subscribe System The content-based publish-subscribe system described in this memo incorporates concepts from the Blocks Extensible Exchange Protocol (BEEP) Core [3], the Application Exchange (APEX) Core [4], and the APEX Publish-Subscribe Service [1]. For purposes of clarity, the remainder of this section introduces the broader concept of the publish-subscribe system without reference to these underlying protocols and concepts. For the remainder of this document, the APEX Publish-Subscribe Service described in [1] will be referred to as the Topic-Based Pub- Sub system. 3.1 Application Roles in the Content-Based Pub-Sub System The content-based pub-sub system is described in terms of individual roles within the system. For the purposes of this document, the overall system architecture will be referred to as the pub-sub system or the content-based pub-sub system. The roles within the system are the Content Provider, the Subscriber, and the Pub-Sub Service. Applications implementing the content-based pub-sub system will implement one or more of these roles. Each role is described briefly below. The content provider generates content for distribution through the pub-sub system. Content providers send structured content to one or more instances of the pub-sub service. Content providers generate content and propagate that content through the pub-sub system by sending it to an instance of the pub-sub service. The subscriber sends subscription requests to an instance of the pub- sub service and, subject to acceptance of a particular subscription request, receives content from the pub-sub service. The actual content received will be determined by the subscription and the message selection process as described below. The pub-sub service acts as both a subscription manager and a content distribution agent. Applications implementing the pub-sub service role must (1) accept subscription requests from subscribers and, subject to any applicable authentication or access control policies, accept or reject subscription requests; and (2) distribute content to valid subscribers. The actual content sent to each subscriber by the pub-sub service will be determined by the subscription and through the message selection process as addressed below. Wyman & Werner Expires September 30, 2002 [Page 6] Internet-Draft APEX PubSub April 2002 The content-based pub-sub system is described in the context of these individual application roles. It is important to note, however, that applications implementing some aspect of the pub-sub system may act in different roles in different circumstances. For example, an application implementing the pub-sub service role may itself act as a subscriber, subscribing to and receiving content from another instance of the pub-sub service. Similarly, an application acting in the subscriber role may act as a content producer if the end-user of the application wishes to publish a message to the service. 3.2 Architecture Overview The architecture of the content-based pub-sub system provides for communication among applications implementing the several application roles. There are two primary communications in the content-based pub-sub system: messages are sent from content providers to pub-sub services; and pub-sub services send messages to subscribers. +----------+ +---------+ +----------+ | content | | | | | | provider |---------->| pub-sub |---------->|subscriber| | | | service | | | +----------+ | | +----------+ | | +----------+ | | +----------+ | content | | | | | | provider |---------->| |---------->|subscriber| | | | | | | +----------+ +---------+ +----------+ Content providers may generate messages from any content source, and subscribers may dispose of messages in any manner they choose. For example, a content provider may simply be a gateway between a raw content source, such as email or web pages, to the pub-sub service, e.g., Wyman & Werner Expires September 30, 2002 [Page 7] Internet-Draft APEX PubSub April 2002 +----------+ +----------+ | | formal | | raw | content | messages | pub-sub | content | provider |---------->| service | ---->| | | | e.g., |(inbound | | | email | gateway) | | | ---->| | | | web | | | | ---->| | | | +----------+ +----------+ Similarly, a subscriber may act as a gateway between the pub-sub service and an external service such as NNTP or email, e.g., +----------+ +----------+ | | | | outbound | pub-sub | messages |subscriber| content | service |---------->| |----> | | |(outbound | e.g., | | | gateway) | email | | | |----> | | | | news | | | |----> | | | | +----------+ +----------+ The application roles defined in above Section 3.1 are not strict, and it is anticipated that an application implementing a particular role within the content-based pub-sub system may implement different roles at different times. For example, an application implementing the pub-sub service role may itself act as a subscriber, subscribing to content through another instance of the pub-sub service and receiving messages from that service, e.g., Wyman & Werner Expires September 30, 2002 [Page 8] Internet-Draft APEX PubSub April 2002 +---------+ subscribes +---------+ +----------+ incoming | | to topics | | | | content | Pub-sub | or content | Pub-sub |--------->|subscriber| ---->| service |<-----------| service | | | | A | receives | B | +----------+ ---->| | messages | | | |----------->| | +----------+ ---->| |----------->| | | | | |----------->| |--------->|subscriber| | | | | | | +---------+ +---------+ +----------+ 3.3 Operations in the Content-Based PubSub System 3.3.1 Creating Topics Topics are created in the content-based pub-sub system through operation of a particular instance of the pub-sub service. The topic-based pub-sub service described in [1] uses the "createtopic" operation to create topics within an instance of the pub-sub service (see [1] at Sections 2.1, 4.2). This "createtopic" operation is preserved and extended in the content-based pub-sub system and topics may be created using this operation, subject to any authentication or access control policy implemented in the pub-sub service. In addition to the "createtopic" operation, in the content-based pub- sub system topics may be created through some automatic response to messages published to the Topics topic (see below Section 6.2). Any such facility for automatic topic creation is left to the implementing application. In the content-based pub-sub system, when a topic is created on an instance of the pub-sub service, the service should publish a message to the Topics topic indicating that a new topic is available (see below Section 6.2). The createtopic operation is extended from the operation described in [1] to include topic-management features used in the content-based pub-sub system. In particular, the createtopic message includes information describing the publisher or publishers to the topic; information describing the topic itself; the message schema for the topic (see below Section 5.3); and optionally the selector schema for the topic (see below Section 5.5). In this manner the createtopic operation reflects the structure of messages published to the Topics Wyman & Werner Expires September 30, 2002 [Page 9] Internet-Draft APEX PubSub April 2002 topic (see below Section 6.2). Each of these concepts will be addressed in detail in the sections that follow. An example of a createtopic operation including this additional information is provided in below Section 6.2.3. 3.3.2 Deleting Topics Topics are deleted in the content-based pub-sub system through the operation of a particular instance of the pub-sub service. The topic-based pub-sub service described in [1] uses the "deletetopic" operation to delete topics within an instance of the pub-sub service (see [1] at Sections 2.2, 4.3). The "deletetopic" operation is preserved in the content-based pub-sub system and topics may be deleted using this operation, subject to any authentication or access control policy implemented in the pub-sub service. Similarly, topics may be deleted through some automatic response to messages published to the Topics topic (see below Section 6.2.2). Any such facility for automatic topic deletion is left to the implementing application. In the content-based pub-sub system, when a topic is deleted on an instance of the pub-sub service, the pub-sub service must publish a message to the Topics topic to indicate to any applicable subscribers that the topic has been canceled (see below Section 6.2.2). This notification is achieved through publication of a message to the Topics topic with the disposition "cancel" (see below Section 6.2.2). 3.3.3 Subscribing to Content The subscribe operation described in [1] is preserved in the Content- based pub-sub system. The operation is extended to provide a facility for subscribing to particular content within a named topic (see below Section 5.8) and to provide a facility for identifying individual subscriptions (below Section 5.8), in the likely event that a subscriber maintains more than one subscription to a particular topic. Similarly, the operations for canceling subscriptions described in [1] at Sections 2.5, 4.6 are preserved in the content-based pub-sub system. The content-based pub-sub system adds a facility for identifying individual subscriptions within the cancel operation (see below Section 5.8.2). Wyman & Werner Expires September 30, 2002 [Page 10] Internet-Draft APEX PubSub April 2002 The content-based pub-sub system places some additional restrictions on subscription, and as a result this memo introduces several new error messages that may be sent in response to subscription requests. The conditions giving rise to these error conditions are described in below Section 5.8.1. 3.3.4 Publishing Messages The "data" operation used for publishing messages described in [1] at Sections 3, 4.7 is preserved in the content-based pub-sub system. Message publication is described in below Section 5.9 but is unchanged from the topic-based pub-sub system of [1]. The content-based pub-sub system places some additional restrictions on publication, and as a result this memo introduces several new error messages that may be sent in response to message publication. The conditions giving rise to these error conditions are described in below Section 5.9.1. Wyman & Werner Expires September 30, 2002 [Page 11] Internet-Draft APEX PubSub April 2002 4. Date and Time Format in the Pub-Sub System In order to standardize the use of timestamps for publish and subscribe operations, the content-based pub-sub system uses the format defined in the Internet Draft "Date and Time on the Internet: Timestamps" . Wyman & Werner Expires September 30, 2002 [Page 12] Internet-Draft APEX PubSub April 2002 5. Messages, Subscriptions, and Publication 5.1 Messages in the Content-Based Publish-Subscribe System Messages are the basic unit of information in the pub-sub system. For each topic, messages must adhere to a defined format. The message format may include a topic-specific message structure, which is described by the message schema, and message header information. 5.2 Message Format Messages are structured using XML [6]. Messages must follow the Content-Based Pub-Sub Schema defined in below Section 8.2. In the pub-sub system, messages include a series of message headers, and a content element containing the message body, e.g., Example, Inc. 11.0 October 18, 2001 11:12:00 1.0 10.0 11.0 12.0 The message body itself, contained within the "content" element, is specified by the message schema. Message headers and the message schema are defined in the sections that follow. Note that the above example uses the date-time format described in above Section 4 for the header fields "publication-date" and "expiration-date" as required by this specification. In the body of Wyman & Werner Expires September 30, 2002 [Page 13] Internet-Draft APEX PubSub April 2002 the message, however, the "last-trade-datetime" field uses a human- readable string for the date-time field. The requirement of above Section 4 applies only to the fields explicitly defined by this specification and for use by the pub-sub system. 5.2.1 Message Headers Message header information is used by the content-based pub-sub system to manage the publication and distribution of messages. Message headers use the structure described in the Content-Based Pubsub Schema (below Section 8.2) and use a distinct namespace. The namespace identifies those elements defined in the Content-Based Pubsub Schema, and also serves to distinguish the message-header (control) elements from the message body. If a content provider does not provide optional message header information, the pub-sub service receiving the message may infer default values for header information. Default values for header information may be defined by specific implementations. Message header information must include the following: o the message topic; o the publisher of the message; and o a timestamp indicating the date of publication. Message header information may optionally include: o a timestamp indicating the expiration date of the message; o a message identification number, which is unique within the scope of a particular message publisher and topic; and o a revision number, which is used to indicate the version of the particular message. The message-content element that encapsulates the message headers is the root message element for the purposes of APEX. As such, the APEX transID field (see [4] at Section 6.1) will be included in the message-content element. This field is used by APEX and is not used in processing messages in the content-based pub-sub system. The message topic is the name of the topic to which the message is published. Wyman & Werner Expires September 30, 2002 [Page 14] Internet-Draft APEX PubSub April 2002 The publication date indicates the date of original publication, and may be used to determine freshness of the message. The expiration date indicates the date after which the message will no longer be valid. The expiration date may be specified as an absolute date and time, or may be specified as '0', in which case the message is to be distributed once and then immediately expires, or '*', which indicates that the message never expires. The message identification number uniquely identifies a message, within the scope of a particular publisher and a particular topic. The revision number is used to identify the sequence of a revised message. If a content provider wishes to replace an existing message prior to the expiration of that message, it may publish a message to the same topic with the same message identification number and with a higher revision number. Revision numbers follow the general numbering scheme for message and sequence IDs described in [3], that is, revision numbers must be non- negative integers within the range 0-2,147,483,647. There is no provision for cyclic revision numbers and it is suggested that no more than 2,147,483,646 revisions be made to a particular message. 5.3 Message Schema In order to provide content-based services, the content-based pub-sub service requires that within a topic, messages adhere to a common format. The message schema describes the format of messages published to a particular topic. 5.3.1 Format of Message Schema The message schema defines the elements and attributes of messages to be published to a particular topic. The message schema is described using the XML Schema structural definition syntax [7]. Message schema may be defined in-line in the body of the message, or may be defined through reference to an external XML Schema document. For example, the definition of the message schema for the message example in above Section 5.2 would be as follows: Wyman & Werner Expires September 30, 2002 [Page 15] Internet-Draft APEX PubSub April 2002 In the event that the schema is provided in an external document, that document may be referenced via a Uniform Resource Identifier (URI) included as an attribute of the message-schema element, e.g., 5.3.2 Default Message Schema If a message schema is not provided for a particular topic, applications implementing some role in the pub-sub system may infer a simple message schema for messages published to that topic. The default message schema includes a root element "message-content". The message body, in its entirety, will be enclosed within the root element. The definition of the default message schema would be represented as follows: (C.f. [7] at Section 5.5). Wyman & Werner Expires September 30, 2002 [Page 16] Internet-Draft APEX PubSub April 2002 5.4 Message Selection The content-based pub-sub system is designed to allow subscription to specific content within defined topics. Content-based subscriptions are realized through the use of message selectors, which are defined as filters applied to the structural elements of a message. When a subscriber wishes to receive content from the pub-sub service, the subscriber sends a subscription request to the pub-sub service including a topic name and a message selector. The Subscribe operation is described in more detail in below Section 5.8. Message selectors apply a query against defined elements of a message. Message selectors are defined with respect to the selector schema, described in below Section 5.5. The syntax and semantics of message selectors are defined through message selector classes. 5.4.1 Message Selector Classes Message selector classes define the syntax and semantics used in message selectors. Examples of possible selector classes include the string representation of LDAP search filters, as defined in RFC 2254 [8] (see below Section 7.2), and a modified syntax of SQL92 [9] (c.f. [10]). The specification of a message selector class must define: o the name of the selector class; and o the syntax and semantics of the message selector class. A message selector class registration template (below Section 7.1) organizes this information. Message selector classes may be registered if desired, but there is no requirement that a message selector class be registered before being used. Support for particular message selector classes is implementation- dependent. There is no requirement that applications within the content-based pub-sub system support any particular message selector classes. This memo defines two message selector classes for general use: Message selector class "RFC-2254" is based on the String Representation of LDAP Search Filters, RFC-2254 [8]. This message selector class is defined in below Section 7.2. Wyman & Werner Expires September 30, 2002 [Page 17] Internet-Draft APEX PubSub April 2002 Message selector class "JMS" is based on the message selector syntax used in the Java Message Service [10], which is itself based on a modified syntax of SQL92 [9]. This message selector class is defined in below Section 7.3. 5.5 Selector Schema The selector schema is used to describe the elements of a message that may be used in message selection. Like the message schema (above Section 5.4), selector schema is defined using the XML Schema structural definition syntax [7], e.g., Selector schema may be provided in-line as described above, or may be incorporated through reference to an external XML schema document. External documents may be referenced by including the URI as an attribute of the selector-schema element, e.g., C.f. above Section 5.3.1. The selector schema is provided by applications acting in the pub-sub service role when describing topics (see below Section 6.2). Applications supporting content-based message selection may either provide an explicit selector schema or may use the message schema, which functions as the default selector schema. Actual message selection is performed by applications implementing the pub-sub service role in the content-based pub-sub system. Prior to selecting messages, applications acting in this role may perform some pre-processing on message content. For this reason, the selector schema may include elements not defined in the message schema. The definition of a selector schema is associated with a particular topic on a particular instance of the pub-sub service, and must refer to a particular message selector class. For example, an application acting in the pub-sub service role might Wyman & Werner Expires September 30, 2002 [Page 18] Internet-Draft APEX PubSub April 2002 allow subscribers to select stock price messages based on the industry group of the issuer, e.g., where the industry group is not included in the content of the message itself, but is determined through some action of the pub-sub service. Similarly, applications performing message selection may support selection over only some of the elements contained in the message schema. For this reason, the selector schema may omit some elements defined in the message schema. The selector schema may include message header fields included in the root "message-content" element. For example, an application acting in the pub-sub service role might allow subscribers to select messages based on the message publisher, e.g., The available selector schema, if any, for a particular topic must be defined by an instance of the pub-sub service in a message published to the "Topics" topic (see below Section 6.2). Descriptions of available selector schema for a particular topic must indicate the message selector class or classes that may be used to generate message selectors using the described selector schema (see below Section 6.2.1). Wyman & Werner Expires September 30, 2002 [Page 19] Internet-Draft APEX PubSub April 2002 5.5.1 Default Selector Schema The selector schema is used to describe the message elements available for use in defining message selectors. The selector schema may include elements not included in the message schema or may omit certain elements of the message schema. In the event that an application acting in the pub-sub service role wishes to support message selection over the message schema in its entirety, the message schema itself may be used as the selector schema. In this event, a separate selector schema need not be specifically defined. However, applications providing content-based message selection functionality that rely on the default selector schema must still enumerate one or more message selector classes for use in generating message selectors. For example, an application providing message selection might list the selector schema as follows: 5.6 Message Selectors Message selectors are sent in the subscribe operation to subscribe to particular content within a named topic. The subscribe operation is described in more detail in below Section 5.8. In the event that a message selector is not sent in the subscribe operation, the subscription will match all messages published to the particular topic. The message selector itself is defined with respect to the selector schema provided by the pub-sub service, and the message selector class provided for a particular selector schema by the pub-sub service. Message selectors are defined within the body of a "subscribe" operation in the "select" element. The select element must include an attribute referring to the message selector class. The body of the select element will contain the message selector. For example, a message selector using the "RFC-2254" message selector class might be defined to select stock price messages, e.g., Wyman & Werner Expires September 30, 2002 [Page 20] Internet-Draft APEX PubSub April 2002 &(symbol='XMPL') (|(net-change-pct > 5.0)(net-change-pct < -5.0)) which would select all messages including the symbol 'XMPL' in which the price moved more than 5 percent up or down. Similarly, the same message selector defined using the 'JMS' message selector might be defined as: symbol='XMPL' AND (net-change-pct > 5.0 OR net-change-pct < -5.0) If a subscriber sends a subscription request to an instance of the pub-sub service omitting the "select" element, the subscriber will receive all messages published to the topic from the service. This is the equivalent of a topic-based subscription. 5.7 Distribution of Message Selection Functionality Support for message selector classes is managed individually by each application implementing the pub-sub service role in the content- based pub-sub system. In a distributed network, each application implementing the pub-sub service role may support the same set of message selector classes as a preceding application, or may support a different set of selector classes, including the null set, e.g., +----------+ subscribes +----------+ +-----+ messages | | to topic | |--------->| | from | Pub-sub |<-----------| Pub-sub | selected |sub.1| content | service | receives | service | messages | | providers | A | all | B | only +-----+ ---->| | messages | | ---->| does not | for the | supports | +-----+ ---->| support | topic | message |--------->| | | message |----------->| selectors| selected |sub.2| | selectors|----------->| | messages | | | |----------->| | only +-----+ +----------+ +----------+ In this manner, the content-based pub-sub system allows administrative domains to establish local redistribution applications that function in the subscriber role, receiving all messages posted to a particular topic, and act in the pub-sub service role, Wyman & Werner Expires September 30, 2002 [Page 21] Internet-Draft APEX PubSub April 2002 implementing content-based message selection services for local subscribers. 5.8 The Subscribe Operation The subscribe operation in the content-based pub-sub system is derived from the similar operation in the topic-based pub-sub system (see [1] at Section 2.4, 4.5). In the content-based pub-sub system, the subscribe operation is extended to include a "select" element containing the message selector (see above Section 5.6). The content-based pub-sub system also introduces the concept of subscription identification. Because the content-based pub-sub system provides for subscription to content within a particular topic, it is anticipated that a subscriber may wish to maintain more than one subscription to a particular topic. For this reason, each subscription is assigned an identification number. Finally, in the content-based pub-sub system a subscriber may optionally request to receive cached messages from the server, or to receive only new messages (i.e. messages received subsequent to the processing of the subscription by the pub-sub service). In order to receive cached messages from an instance of the pub-sub service, the subscribe operation must include the "cached" attribute of the subscribe element with a non-empty value. If the subscription request does not include the "cached" attribute, instances of the pub-sub service should not deliver cached messages. When an application acting in the subscriber role wishes to subscribe to content within a particular topic, the application sends a subscription request to the pub-sub service including a message selector in the body of the "select" element, e.g., Wyman & Werner Expires September 30, 2002 [Page 22] Internet-Draft APEX PubSub April 2002 +-------+ +-------+ | | -- data -------> |pub-sub| | appl. | |svc. | | | <--------- ok -- | | +-------+ +-------+ C: equity.quote.service jade@example.com 86400 true symbol IN ('XMPL', 'TEST', 'SMPL') AND (net-change-pct > 5.0 OR net-change-pct < -5.0) S: The service immediately responds with a reply operation containing the same transaction identifier and the assigned subscription identifier, e.g., Wyman & Werner Expires September 30, 2002 [Page 23] Internet-Draft APEX PubSub April 2002 +-------+ +-------+ | | <------- data -- |pub-sub| | appl. | |svc. | | | -- ok ---------> | | +-------+ +-------+ C: 100 S: The subscription identifier is assigned by the pub-sub service. For each instance of the pub-sub service, a subscription identifier must be unique within the scope of the subscriber endpoint. Once a subscription request has been accepted by the pub-sub service, the service may begin sending messages to the subscriber. Messages will be selected for a particular subscription based on the message selector used in that subscription. In all other respects, the subscription will be treated as described in [1]. If the subscribe operation has included the "cached" attribute and the pub-sub service caches messages, the service may immediately forward all cached messages for the topic to the subscriber (subject to any content-based message selection as described herein). 5.8.1 Rejection of a Subscription Request When an application acting in the pub-sub service role receives a subscription request, it may respond with an error code or with a success code as described in [1] at Section 4.5. In the content-based pub-sub system, the pub-sub service must reject malformed subscription requests. Malformed subscription requests are subscription requests that either (1) use a message selector class not supported by the instance of the pub-sub service for the particular topic, or (2) include an incorrect message selector, that is, a message selector that cannot be correctly applied to the selector schema. Wyman & Werner Expires September 30, 2002 [Page 24] Internet-Draft APEX PubSub April 2002 If the subscription request uses a message selector class that is not supported by the service, a "reply" element having code 566 will be sent to the originator. If the subscription request includes an incorrect message selector, a "reply" element having code 567 will be sent to the originator. Note that if both errors are present in a subscription request, either error response may be returned. The above error responses will only be sent following processing of the subscription request, which may be interrupted upon detection of an error condition. 5.8.2 Canceling a Subscription Subscriptions may be canceled by the subscriber or by the pub-sub service at any time through the "cancel" operation (see [1] at Sections 2.5, 4.6). In the content-based pub-sub service, the "cancel" operation is extended to include the subscription identifier (see above Section 5.8). When a subscriber wishes to cancel an outstanding subscription, it sends a "cancel" operation to the pub-sub service including the subscription identifier, e.g., +-------+ +-------+ | | -- data -------> |pub-sub| | appl. | |svc. | | | <--------- ok -- | | +-------+ +-------+ C: equity.quote.service 100 S: Wyman & Werner Expires September 30, 2002 [Page 25] Internet-Draft APEX PubSub April 2002 The pub-sub service then processes the cancel operation as described in [1] at Section 4.6. When the pub-sub service wishes to terminate a subscription, it sends a "cancel" operation to the subscriber, including the subscription identifier, e.g., +-------+ +-------+ | | <------- data -- |pub-sub| | appl. | |svc. | | | -- ok ---------> | | +-------+ +-------+ C: equity.quote.service 100 S: The topic and subscription-id attributes are optional in the context of the cancel operation. The content-based pub-sub system provides some default alternative behavior in the event that one or more of these attributes is not present. In the event that a "cancel" operation is transmitted by an application (either a subscriber or the pub-sub service) without indicating a subscription identifier, and the subscriber maintains one or more subscriptions to the named topic, the pub-sub service should cancel all outstanding subscriptions to that topic from the subscriber endpoint. This default behavior is optional, and implementations may define alternative default behavior to handle this event. In the event that an application (either the subscriber or the pub- sub service) sends a generic "cancel" operation containing neither a topic name nor a subscription identifier, the pub-sub service should cancel all outstanding subscriptions to all topics from the subscriber endpoint. This default behavior is similarly optional, Wyman & Werner Expires September 30, 2002 [Page 26] Internet-Draft APEX PubSub April 2002 and implementations may define alternative default behvior to handle this event. If an application (either the subscriber or the pub-sub service) sends a "cancel" operation that cannot be properly mapped to an existing topic and subscription identifier, a "reply" element having code 568 will be returned. 5.9 Publishing a Message Messages are published to the pub-sub service by content providers as described in [1] at Section 3. The general publication operation described in [1] is unchanged in the content-based pub-sub system. 5.9.1 Rejection of a Published Message The pub-sub service may reject a message published by an application if the message does not conform to the message schema defined for the topic. The pub-sub service may also reject a published message if the publisher is not permitted to publish to the topic, pursuant to any implemented authentication or access control policy. If the published message does not conform to the message schema defined for the topic, e.g. if the message omits a "required" element or attribute, a "reply" element having code 561 will be sent to the originator. 5.10 Message Delivery It is anticipated that in the operation of the pub-sub system, a single message may satisfy more than one subscription of a particular endpoint. In this event, the normal operation of the pub-sub system would be to deliver multiple copies of the same message to the same user. In order to mitigate this problem, the pub-sub service may use the "InRe" option to indicate multiple subscription identifiers. The "InRe" option is an APEX option as described in [4] at Section 5. 5.10.1 The "InRe" APEX Option Below Section 7.7 contains the APEX option registration for the "InRe" option. The "InRe" option is designed to allow APEX endpoints to provide application-specific data or processing instructions outside of the Wyman & Werner Expires September 30, 2002 [Page 27] Internet-Draft APEX PubSub April 2002 body of a particular APEX message. The "InRe" option acts as a recipient-specific envelope for APEX messages. The "InRe" option may contain any arbitrary application-specific content, which is processed by the recipient endpoint. The sole restriction on content in the "InRe" option is that it must be in XML format. This allows the "InRe" option to be used by multiple applications by defining specific "InRe" option contents. 5.10.1.1 Using the "InRe" Option in the Pub-Sub System In the pub-sub system, the "InRe" option is used to facilitate message delivery and to prevent or limit multiple delivery of a single message. The "InRe" option contains one or more subscription identifiers indicating the subscription or subscriptions satisfied by the message, e.g., +-------+ +-------+ | | <------- data -- |pub-sub| | appl. | |svc. | | | -- ok ---------> | | +-------+ +-------+ C: [ content omitted for brevity ] S: In the above example, the message satisfies two subscriptions of the given user, which are identified as '100' and '101'. Rather than send two copies of the message, the pub-sub service uses the "InRe" Wyman & Werner Expires September 30, 2002 [Page 28] Internet-Draft APEX PubSub April 2002 option to indicate each subscription that is satisfied by the message. Through the pub-sub system, a single user may receive a single message in response to more than one subscription. Depending on the implementation, this information may be available to the pub-sub server before the message is delivered. In this event, the "InRe" option allows the server to reduce overall network traffic by sending the recipient only a single message with the content marked for two subscriptions. Similarly, the APEX core allows multiple recipients of a single APEX message (see [4] at Section 4.4.4). If a particular message satisfies subscriptions of more than one user, and this information is available to the pub-sub server prior to transmission of a message, the server may dispatch the message to the relay with multiple "recipient" elements. In this event, the "InRe" option allows the pub-sub server to indicate, for each recipient, the subscription or subscriptions satisfied by the message. In this case, the pub-sub service would send a single message to the APEX relay containing multiple recipient elements, each containing an "InRe" option, e.g., +-------+ +-------+ |pub-sub| -------- data -> | | |svc. | | relay | | | <- ok ---------- | | +-------+ +-------+ C: [ content omitted for brevity ] S: Upon receiving the message, the relay (or through the APEX relay mesh, multiple relays) would dispatch a message to each individual subscriber endpoint, e.g., +-------+ +-------+ | | -------- data -> | | | relay | | user1 | | | <- ok ---------- | | +-------+ +-------+ C: [ content omitted for brevity ] S: Wyman & Werner Expires September 30, 2002 [Page 30] Internet-Draft APEX PubSub April 2002 The "InRe" option can thereby minimize the aggregate number of messages sent by the pubsub server. In addition, use of the "InRe" option allows anonymity among individual subscribers by limiting the recipient-specific envelope data to the particular recipient. Wyman & Werner Expires September 30, 2002 [Page 31] Internet-Draft APEX PubSub April 2002 6. Topic Management 6.1 The Well-Known Topic Within the content-based pub-sub system, we introduce the concept of a well-known topic (WKT). The well-known topic is a message topic in the content-based pub-sub system that adheres to a well-defined, registered message structure. Well-known topics are identified using the syntax "WKT=topicname". The "WKT=" prefix for topic names is reserved for registered well-known topics. In addition to defined schema, well-known topics may optionally include some recommended or required message processing. The specification of a well-known topic must define: o the name of the topic; o the message schema of the topic; and o if applicable, any topic-specific processing requirements. A registration template (below Section 7.4) organizes this information. This document introduces the well-known topics "WKT=Topics", referred to as the Topics topic, and "WKT=Subscriptions", referred to as the Subscriptions topic. The Topics topic and the Subscriptions topic are described in the sections that follow. 6.2 The Topics Topic The Topics topic ("WKT=Topics") is used within the content-based pub- sub system for topic description and topic management. The Topics topic provides a facility for an instance of the pub-sub service to enumerate available topics and to modify or cancel existing topics. Messages published to the Topics topic adhere to the defined message schema for the topic. Messages published to the Topics topic (with the exception of cancellation messages as described below) describe a topic, including the message schema and selector schema if applicable. For example, a message to the Topics topic describing a stock price topic might be published as follows: equity.quote.service publish stock-service@example.com This service provides delayed stock price information for issues traded on the U.S. public markets. Wyman & Werner Expires September 30, 2002 [Page 33] Internet-Draft APEX PubSub April 2002 The Topics topic is more fully described in the Topics topic Schema (below Section 8.3). Applications implementing the pub-sub service role in the content- based pub-sub system are responsible for publishing messages to the Topics topic. For each topic available within the particular instance of the pub-sub service, the service will publish a message to the Topics topic describing the topic, including the message schema and selector schema if applicable. Messages published to the Topics topic follow the Topics topic Schema (below Section 8.3). Messages must include information describing: o the name of the topic; o the disposition of this topics message, indicating whether this is a notice of publication or a notice of cancellation; o optionally, meta-information describing the topic and listing publishers to the topic; o the message schema of messages to be published to the topic, if applicable; and o if the instance of the pub-sub service provides content-based message selection services, the selector schema for the topic and any available message selector classes. If an instance of the pub-sub service supports content-based message selection services, it must specify the selector schema and the available message selector classes for a particular topic within messages published to the Topics topic describing that topic. Within the body of a message published to the Topics topic, the selector schema is enclosed in a "selector-schema" element containing the attribute "class" which describes the message selector class that may be used to create message selectors using the selector schema. Messages published to the Topics topic may include more than one selector schema element if appropriate, specifying different message selector classes or different selector schema. Wyman & Werner Expires September 30, 2002 [Page 34] Internet-Draft APEX PubSub April 2002 6.2.1 Listing Topics In the topic-based pub-sub system described in [1], the "listtopics" operation is used to list available topics on an instance of the pub- sub service. When an instance of the pub-sub service receives a "listtopics" command, it responds with a list of available topics (see [1] at Sections 2.3, 4.4). The "listtopics" operation is available through the content-based pub-sub system. However, the content-based pub-sub system uses the Topics topic to provide an alternative mechanism for listing available topics. When an application wishes to receive a list of available topics from an instance of the pub-sub service, it subscribes to the Topics topic. The application may optionally subscribe to the Topics topic using a message selector as described in above Section 5.8. The syntax of the subscribe operation is described in [1] at Sections 2.4, 4.5. 6.2.2 Topic Updates When a topic is modified or canceled by some operation of the pub-sub service, the pub-sub service must publish a message to the Topics topic indicating the modification to or cancellation of the topic. When a topic has been canceled on an instance of the pub-sub service, the pub-sub service will publish a message to the Topics topic indicating the name of the topic and indicating the disposition "cancel". This message serves as a notice to subscribers to the Topics topic that the named topic has been canceled by the instance of the pub-sub service. Messages published to the Topics topic indicating cancellation of a topic must include the disposition "cancel". If a prior message has been published to the Topics topic regarding the particular topic, the message indicating cancellation should use the same message number as the previous message, and a higher revision number. For example, a message to the Topics topic canceling the topic described in above Section 6.2 might be published as follows: Wyman & Werner Expires September 30, 2002 [Page 35] Internet-Draft APEX PubSub April 2002 equity.quote.service cancel When a topic has been modified on an instance of the pub-sub service, the pub-sub service will publish a message to the Topics topic describing the topic and indicating the disposition "publish". Modification messages are identical in form to messages describing topics as addressed in above Section 6.2.1. If a message has previously been published to the Topics topic regarding a particular topic which is subsequently modified, the modification message will be published by the pub-sub service with the same message identification number and a higher revision number (see above Section 5.2.1). Subscribing applications receiving the topic modification notice should replace the previous message with the revised message. If an application subscribes to the Topics topic subsequent to the modification of a topic, it should receive the most recent available message regarding the topic as determined by the revision number. 6.2.3 Creating Topics with the Createtopic Operation As noted above, the content-based pub-sub system is implemented as a set of extensions to the topic-based pub-sub system described in [1]. The topic-based pub-sub system provides the createtopic operation for use in creating topics (see [1] at Sections 2.1, 4.2. In the content-based pub-sub system, the createtopic operation is adopted and extended to include additional information for topic management and message selection. The createtopic operation is an adjunct to the process described above for creating topics (via messages published to the Topics topic, see above Section 6.2). The information included in the createtopic operation is similar to that used in messages published to the topics topic, with the exception of the element, which is implied by the operation itself. Similarly, the element used in Wyman & Werner Expires September 30, 2002 [Page 36] Internet-Draft APEX PubSub April 2002 messages published to the Topics topic need not be included in the createtopic operation, since the operation itself includes an attribute describing the topic name (see [1] at Sections 2.1, 4.2. The createtopic operation may include other information used in messages published to the Topics topic, i.e.: o one or more publishers to the topic; o a brief description of the topic; o the message schema of the topic; and o the selector schema for the topic. Each optional element described above may be included as a sub- element of the createtopic operation, e.g. C: stock-service@example.com This service provides delayed stock price information for issues traded on the U.S. public markets. [ content omitted for brevity ] [ content omitted for brevity ] S: Wyman & Werner Expires September 30, 2002 [Page 37] Internet-Draft APEX PubSub April 2002 C.f. [1] at Sections 2.1, 4.2. Although the and elements are not required in the createtopic operation, they may be included for consistency with a message published to the Topics topic. In the content-based pub-sub system, the Topics topic is used for topic management. Therefore when a topic is created using the createtopic operation, it is expected that the service on which the topic is created would generate a message on the Topics topic to notify users about the new topic. 6.3 The Subscriptions Topic The Subscriptions topic ("WKT=Subscriptions") is used within the content-based pub-sub system to provide subscription information to users, based on their APEX endpoint. The Subscriptions topic offers read-only access to subscriptions maintained by an instance of the pub-sub service. Creation and cancellation of subscriptions are processed as described in above Section 5.8. The Subscriptions topic is used to access a user's current subscription information, without reliance on a local copy of that data. This allows users to view or manage their subscription information from multiple locations or multiple machines. Messages are published to the subscriptions topic by the pub-sub service in response to subscription requests by a particular user or endpoint. Messages on the subscriptions topic must adhere to the Subscriptions topic schema (see below Section 8.4). Messages published to the Subscriptions topic must include: o the subscriber endpoint; o the subscription ID assigned to the subscription; o the topic name; o the message selector used in creating the subscription; o the origination date of the subscription; and o the duration of the subscription. Messages published to the Subscriptions topic may optionally include a "current-status" element reflecting the current status of the subscription. The current status element is defined in the Wyman & Werner Expires September 30, 2002 [Page 38] Internet-Draft APEX PubSub April 2002 Subscriptions topic Schema (see below Section 8.4). Use of the current status element is optional in the content-based pub-sub system, and the use and maintenance of status information is left to particular implementations. jade@example.com 1090334 equity.quote.service net-change-pct > 5.0 2002-03-10T08:00:00-08:00 0 ACTIVE 6.3.1 Access Control and the Subscriptions Topic In processing subscription requests to the Subscriptions topic, instances of the pub-sub service must assign a default selector schema matching the "subscriber" element of the Subscriptions topic to the subscriber's APEX endpoint. Any selector schema provided by the user in subscribing to the Subscriptions topic must be combined with this default selector to form the selector used in processing the subscription. However, it is possible to override this default behavior by providing a substitute list of subscriber endpoints to be used in processing the subscription. The goal of these restrictions is to allow users to retrieve their own subscription information, but limit their access to other endpoints' subscription information. Because the Subscriptions topic contains potentially sensitive Wyman & Werner Expires September 30, 2002 [Page 39] Internet-Draft APEX PubSub April 2002 information, and because the framework allows the possibility of retrieving other users' subscription information, it is recommended that implementations of the content-based pub-sub system restrict access to this topic by user endpoint or by some means. In general, subscription information should be available only to the subscribing endpoint or to a system administrator. Wyman & Werner Expires September 30, 2002 [Page 40] Internet-Draft APEX PubSub April 2002 7. Initial Registrations 7.1 Registration Template for Message Selector Classes When a message selector class is registered, the following information must be supplied: Selector Class Identification: specify the NMTOKEN or URI that authoritatively identifies this selector class. Description: specify a description of the selector class and the syntax used. This section is for reference purposes only. Message Selector Syntax: specify the syntax and semantics of the selector class. This specification may incorporate an existing specification by reference. Contact Information: specify the postal and electronic contact information for the author of this message selector class. 7.2 Registration: Message Selector Class 'RFC-2254' Selector Class Identification: "RFC-2254" Description: The "RFC-2254" Message Selector Class is based on the String Representation of LDAP Search Filters, RFC 2254 [8]. This message selector class describes a generalized identifier-based Boolean search syntax. Message Selector Syntax: The "RFC-2254" Message Selector Class is defined by the following grammar, following the ABNF grammar defined in RFC-2234 [11]. The selector format uses a prefix notation. Wyman & Werner Expires September 30, 2002 [Page 41] Internet-Draft APEX PubSub April 2002 selector = "(" selectorcomp ")" selectorcomp = and / or / not / item and = "&" selectorlist or = "|" selectorlist not = "!" selector selectorlist = 1*selector item = simple / present / substring simple = identifier selectortype value selectortype = equal / approx / greater / less equal = "=" approx = "~=" greater = ">=" less = "<=" present = identifier "=*" substring = identifier "=" [initial] any [final] initial = value any = "*" *(value "*") final = value identifier = 1*CHAR value = 1*CHAR For purposes of mapping message schema identifiers to message selector identifiers, any element or attribute name is considered a valid identifier. Any named attribute or entity will be matched against identifiers used in message selectors. In the event that more than one element or attribute name matches an identifier used in a message selector, all instances of the element or attribute will be compared to the tested value. A single matching instance of the test value and the element or attribute will be considered a successful match. When processing arbitrary mime-typed content, this class will use text processing for the text/* types (e.g. text/html) and will not process application or binary content types. Contact Information: c.f., the Author's Addresses section of this memo. 7.3 Registration: Message Selector Class 'JMS' Selector Class Identification: "JMS" Description: The "JMS" message selector class is derived from the Java Message Service (JMS) message selection service, defined in [10] at pp. 37-43. Wyman & Werner Expires September 30, 2002 [Page 42] Internet-Draft APEX PubSub April 2002 Message Selector Syntax: The syntax of Java Message Service message selectors is preserved, and is incorporated by reference ([10] pp. 37-43). For purposes of the content-based pub-sub service over APEX and this message selector class "JMS", identifiers ([10] at pp. 38- 89) may be any element or attribute of a defined message schema (see above Section 5.3). For purposes of mapping message schema identifiers to message selector identifiers, any element or attribute name is considered a valid identifier. Any named attribute or entity will be matched against identifiers used in message selectors. In the event that more than one element or attribute name matches an identifier used in a message selector, all instances of the element or attribute will be compared to the tested value. A single matching instance of the tested value and the element or attribute will be considered a successful match. When processing arbitrary mime-typed content, this class will use text processing for the text/* types (e.g. text/html) and will not process application or binary content types. Contact Information: c.f., the Author's Addresses section of this memo. 7.4 Registration Template for Well-Known Topics When a well-known topic is registered, the following information must be supplied: Topic Identification: specify the NMTOKEN or URI that authoritatively identifies this topic. Common Name Identification: specify the common or short name for this topic. Message Schema: specify the message schema for this topic. Additional Processing Requirements: optionally specify any additional processing requirements for use with the topic. Contact Information: specify the postal and electronic contact information for the author of this topic definition. Wyman & Werner Expires September 30, 2002 [Page 43] Internet-Draft APEX PubSub April 2002 7.5 Registration: The Topics Topic Topic Identification: http://www.firstrain.com/WKT=Topics Common Name Identification: WKT=Topics Message Schema: c.f., the Topics topic Schema, below Section 8.3. Additional Processing Requirements: none Contact Information: c.f., the Author's Addresses section of this memo. 7.6 Registration: The Subscriptions Topic Topic Identification: http://www.firstrain.com/WKT=Subscriptions Common Name Identification: WKT=Subscriptions Message Schema: c.f., the Subscriptions topic Schema, below Section 8.3. Additional Processing Requirements: In processing subscription requests to the Subscriptions topic, instances of the pub-sub service must assign a default selector schema matching the "subscriber" element of the Subscriptions topic to the subscriber's APEX endpoint. Any selector schema provided by the user in subscribing to the Subscriptions topic must be combined with this default selector to form the selector used in processing the subscription. However, in the event that the subscription request includes a substitute element matching the "subscriber" element of the Subscriptions topic, the default behavior will be overridden by the user-supplied value. Contact Information: c.f., the Author's Addresses section of this memo. 7.7 Registration: The "InRe" APEX Option The "InRe" APEX option registration follows the APEX Option Registration Template, [4] at Section 7.1. Option Identification: InRe Present in: APEX's "recipient" element Wyman & Werner Expires September 30, 2002 [Page 44] Internet-Draft APEX PubSub April 2002 Contains: any arbitrary application-specific content (in XML format) Processing Rules: none; the "InRe" option is used by the recipient endpoint to process application-specific data. Contact Information: c.f., the Author's Addresses section of this memo. Wyman & Werner Expires September 30, 2002 [Page 45] Internet-Draft APEX PubSub April 2002 8. DTDs and XML Schemas The content-based publish-subscribe DTD is an extension of the APEX pub-sub DTD defined in [1] at Section 6.1. The "createtopic" operation is extended to include optional elements describing a topic. The "subscribe" and "cancel" elements which are modified for use in the content-based pub-sub system are contained in the Content- Based Pub-Sub Schema (below Section 8.2). In the below DTD, which reflects the subscribe and cancel operations described in [1], these elements are unchanged. 8.1 The Content-Based Publish-Subscribe DTD %APEXCORE; Wyman & Werner Expires September 30, 2002 [Page 46] Internet-Draft APEX PubSub April 2002 8.2 The Content-Based Pub-Sub Schema Wyman & Werner Expires September 30, 2002 [Page 48] Internet-Draft APEX PubSub April 2002 8.3 The 'Topics' Topic Schema Wyman & Werner Expires September 30, 2002 [Page 49] Internet-Draft APEX PubSub April 2002 8.4 The 'Subscriptions' Topic Schema Wyman & Werner Expires September 30, 2002 [Page 50] Internet-Draft APEX PubSub April 2002 Wyman & Werner Expires September 30, 2002 [Page 51] Internet-Draft APEX PubSub April 2002 9. Security Considerations For a discussion of security considerations within the content-based publish-subscribe system, see [1] at Section 7. Wyman & Werner Expires September 30, 2002 [Page 52] Internet-Draft APEX PubSub April 2002 References [1] Schwartz, M., Rose, M. and K. Carlberg, "The APEX Publish- Subscribe Service", draft-schwartz-apex-pubsub-02 (work in progress), October 2001. [2] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [3] Rose, M., "The Blocks Extensible Exchange Protocol Core", RFC 3080, March 2001. [4] Rose, M., Crocker, D. and G. Klyne, "The Application Exchange Core", draft-ietf-apex-core-06 (work in progress), January 2002. [5] Newman, C. and G. Klyne, "Date and Time on the Internet: Timestamps", draft-ietf-impp-datetime-05 (work in progress), November 2001. [6] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler, "Extensible Markup Language (XML) 1.0 (2nd ed)", W3C REC-xml, October 2000, . [7] Fallside, D., "XML Schema Part 0: Primer", W3C REC-xmlSchema, May 2001, . [8] Howes, T., "The String Representation of LDAP Search Filters", RFC 2254, December 1997. [9] X/Open Group, "X/Open CAE Specification Data Management: Structured Query Language (SQL), Version 2", March 1996. [10] Hapner, M., Burridge, R. and R. Sharma, "Java Message Service, Version 1.0.2", Java Message Service Specification 1.0.2b, Nov 1999. [11] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997. Wyman & Werner Expires September 30, 2002 [Page 53] Internet-Draft APEX PubSub April 2002 Authors' Addresses Bob Wyman firstRain, Inc. 134 West 29th Street New York, NY 10001 US Phone: +1 212 616 8700 Fax: +1 212 290 2734 EMail: bobwyman@firstrain.com URI: http://www.firstrain.com Duncan Werner firstRain, Inc. 134 West 29th Street New York, NY 10001 US Phone: +1 212 616 8700 Fax: +1 212 290 2734 EMail: dwerner@firstrain.com URI: http://www.firstrain.com Wyman & Werner Expires September 30, 2002 [Page 54] Internet-Draft APEX PubSub April 2002 Appendix A. Error Codes The following describe error codes that may be reported by the content-based pub-sub system, and the conditions that may raise each error. Error Reference Condition ===== ========= ========= 561 Section 5.9.1 Response to a publish operation: invalid message structure. 566 Section 5.8.1 Response to a subscription request: unsupported message selector class. 567 Section 5.8.1 Response to a subscription request: incorrect message selector. 568 Section 5.8.2 Response to a cancel operation: invalid topic name and subscription identifier. Wyman & Werner Expires September 30, 2002 [Page 55] Internet-Draft APEX PubSub April 2002 Appendix B. Notes to this Memorandum B.1 This document is a work in progress. The authors expect that a number of changes will be incorporated into further drafts, including: o development of a unified APEX/PubSub Internet Draft that incorporates into a single document the Topic-Based Pub-Sub and Content-Based Pub-Sub systems; o provision for the use of RDF sytnax and RDF schema; o strategies for scalability and network management; and o the use of XPath and XQuery syntax in message selection. Wyman & Werner Expires September 30, 2002 [Page 56] Internet-Draft APEX PubSub April 2002 Appendix C. Acknowledgements The authors gratefully acknowledge the contributions of: Marshall Rose, Graham Klyne, Mike Schwartz, Jade, Salim, and Lanae Weir. Wyman & Werner Expires September 30, 2002 [Page 57] Internet-Draft APEX PubSub April 2002 Full Copyright Statement Copyright (C) The Internet Society (2002). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Wyman & Werner Expires September 30, 2002 [Page 58]