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.0October 18, 2001 11:12:00
1.010.011.012.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.servicejade@example.com86400true
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.service100
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.service100
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.servicepublishstock-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.servicecancel
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.com1090334equity.quote.service
net-change-pct > 5.0
2002-03-10T08:00:00-08:00
0ACTIVE
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]