Publish/Subscribe 1.0 is an interface specification that supports the core components and concepts of the Publish/Subscribe message exchange pattern with OGC Web Services. The Publish/Subscribe pattern complements the Request/Reply pattern specified by many existing OGC Web Services. This specification may be used either in concert with, or independently of, existing OGC Web Services to publish data of interest to interested Subscribers.

Publish/Subscribe 1.0 primarily addresses subscription management capabilities such as creating a subscription, renewing a subscription, and unsubscribing.  However, this standard also allows Publish/Subscribe services to advertise and describe the supported message delivery protocols such as SOAP messaging, ATOM, and AMQP.  Message delivery protocols should be considered to be independent of the Publish/Subscribe 1.0 standard.  Therefore, OGC Publish/Subscribe only includes metadata relating to message delivery protocols in sufficient detail to allow for different implementations of Publish/Subscribe 1.0 to interoperate. 

This specification defines Publish/Subscribe functionality independently of the binding technology (e.g., KVP, SOAP, REST). Extensions to this specification may realize these core concepts with specific binding technologies.

The following are keywords to be used by search engines and document catalogues.

ogcdoc pubsub core specification

The OGC® Abstract Specification does not require any changes to accommodate the technical contents of this document.

No future work is currently anticipated.

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

The following organizations submitted this Document to the Open Geospatial Consortium (OGC):

National Center for Atmospheric Research (NCAR)

National Research Council of Italy (CNR)

International Geospatial Services Institute (iGSI) GmbH

CubeWerx, Inc.

Cooperative Institute for Research in the Atmosphere (CIRA)

All questions regarding this submission should be directed to the editor or the submitters:

1.    Scope

This OGC standard defines core concepts and mechanisms for enabling the Publish/Subscribe messaging pattern with OGC Web Services. Publish/Subscribe may be used independently of or in conjunction with the Request/Reply messaging pattern.

This standard defines a common Publish/Subscribe conceptual framework and functionality, independently of specific binding technologies (e.g., KVP, SOAP, REST).

Reliable delivery of messages (i.e. assurance that messages that are sent are actually delivered) is out of scope for this specification, as reliable delivery techniques are dependent on the delivery method. Extensions to this specification may specify requirements and conformance for reliable delivery.

Authorization, authentication, and access control are not addressed in this specification. Extensions to this specification may specify requirements and conformance for security-related functionality.

2.    Conformance

Conformance with this standard shall be checked using the relevant tests specified in Annex A (normative) of this document. The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site^[1].

This standard distinguishes several conceptual roles for entities participating in Publish/Subscribe interactions: Sender, Receiver, Subscriber, and Publisher (defined in Clause 4). However, this standard only defines conformance requirements for the following Standardization Target Types.

• Publisher – entity that offers publications to Subscribers.
• Receiver– entity that receives messages from Senders (e.g. a Publisher).

This standard defines the Conformance Classes summarized in Table 1 and shown in Figure 1.

Requirements and conformance test URIs defined in this document are relative to

http://www.opengis.net/spec/pubsub/1.0/.

The relationships between conformance classes are shown below in Figure 1.

All requirements-classes and conformance-classes described in this  document are owned by the standard(s) identified.

3.    References

This OGC Publish/Subscribe 1.0 Core standard consists of the present document. An associated XML Schema is provided for consistency among extensions to this standard. For this standard, the provided XML Schema may be considered informative.

The complete OGC Publish/Subscribe 1.0specification is identified by OGC URI http://www.opengis.net/spec/pubsub/1.0. It is available for download from http://www.opengeospatial.org/standards/pubsub. The informative XML Schema is posted on-line at http://schemas.opengis.net/pubsub/1.0 as part of the OGC schema repository.

The following normative documents contain provisions, which, through reference in this text, constitute provisions of this document. For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. For undated references, the latest edition of the normative document referred to applies.

ISO/TS 19103:2005, Geographic information — Conceptual schema language

OGC 06-121r3, OGC Web Services Common Specification, OGC® Implementation Standard 1.1.0 (9 February 2007)

W3C XML Schema Part 1, XML Schema Part 1: Structures, W3C Recommendation (2 May 2001)

W3C XML Schema Part 2, XML Schema Part 2: Datatypes, W3C Recommendation (2 May 2001).

4.    Terms and Definitions

This document uses the terms defined in Sub-clause 5.3 of [OGC 06-121r3], which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this standard.

For the purposes of this document, the following additional terms and definitions apply.

4.1           Message

A container within which data (such as XML, binary data, or other content) is transported. Messages may include additional information beyond data, including headers or other information used for routing or security purposes.

4.2           Publication

A uniquely identified aggregation of messages published by a Publisher over time. A Publisher may offer any number of publications that Subscribers may subscribe to.

4.3           Publisher

An entity that offers publications to Subscribers; supports subscription management (subscribe, unsubscribe) and is responsible for filtering and matching messages of interest to active subscriptions.

4.4           Receiver

An entity that receives messages from Senders; may (but need not) be the original Subscriber.

4.5           Sender

Entity that sends messages to Receivers; may (but need not) be the initial creator/producer of the data in the message payload.

4.6           Subscriber

Entity that creates a subscription at a Publisher; may (but need not) be the Receiver of delivered messages.

4.7           Subscription

Expression of interest in all or part of a publication offered by a Publisher. When a subscription has been created, the Publisher delivers messages that match the subscription criteria to the Receiver defined in the subscription.

5.    Conventions

5.1    Abbreviations

In this document the following abbreviations and acronyms are used or introduced:

HTTP             Hypertext Transfer Protocol

MEP               Message Exchange Pattern

OGC               Open Geospatial Consortium

OMG              Object Management Group

UML               Unified Modeling Language (an object modeling language)

XML               eXtensible Markup Language

5.2    UML Notation

All symbols used in this document are UML 2 (Unified Modeling Language) as defined by OMG and accepted as a publicly available standard by ISO in its earlier 1.3 version.

All classes in this standard are extensible and may be extended with application- or domain-specific content via Extension blocks.

            The UML shown in this standard is considered conceptual and abstract, and should not be interpreted as an implementation strategy for bindings that extend and implement this standard. For example, TM_Instant from ISO 19108 is used to represent time instants for conceptual clarity, but bindings and implementations of this standard may realize TM_Instant as a GML TimeInstant, an ISO 8601 date string, or any other representation that is consistent with TM_Instant.

5.3    Referencing Conventions

This standard references UML classes from other specifications. When referencing UML classes not defined in this standard, the class name will be qualified with the document of origin. For example, a reference to the ISO 19108 TM_Instant is referenced as:

            TM_Instant [see ISO/TS 19103:2005]

Many referenced UML classes are instantiated as XML schema, such as the GML realization of ISO TC211 standards. This standard only normatively references UML representations.

6.    Publish/Subscribe Overview

Two primary parties characterize the publish/subscribe model: a Publisher that is publishing information and a Subscriber that is interested in all or part of the published information. The publish/subscribe messaging model is distinguished from the request/reply model by the use of an ongoing, persistent, expression of interest (a subscription) and the asynchronous delivery of messages that match a subscription.

The entity subscribing for published information (the Subscriber) and the entity to which data is delivered (the Receiver) are often one and the same. However, they are distinguished in this standard to allow for these roles to be segregated in cases such as a system component mass-subscribing on behalf of the ultimate Receivers of messages.

Similarly, while the Publisher and Sender roles may be segregated they are often implemented as the same entity. Senders may be unaware of the ultimate recipients of their messages and of the architecture of the system into which they deliver messages, such as with multi-cast delivery or ATOM feeds.

While multiple entities (Publisher, Subscriber, Sender, and Receiver) are distinguished in this Clause, requirements are only allocated against Publishers and Receivers in this standard.

6.1    Publish/Subscribe workflow

The publish/subscribe workflow is depicted in Figure 2.

The first step to initiate a publish/subscribe message exchange is the creation of a subscription. A subscription defines which messages available at the Publisher are of interest to the Subscriber. The Subscriber is an entity that creates a subscription on behalf of a Receiver using the Subscribe operation on a Publisher (1.0). If the Publisher accepts the subscribe request, it creates a subscription (1.1) and returns a response informing the requester of the outcome of its request – either success or an exception (1.2).

When a subscription is submitted, a Subscriber may supply filter criteria. Filter expressions evaluate to a boolean value for each individual message. Those messages that evaluate to true for all filter expressions on a subscription are considered to have matched. Filter criteria can filter by message content (such as XPath or OGC Filter Specification), by message metadata (such as header content), or by other criteria.

Whenever a new message is available to the Publisher, it attempts to match it against each subscription (2.0). If the message matches the filter criteria of a subscription the Publisher initiates Sender delivery to the location and/or Receiver specified for the subscription (2.1). Messages are delivered asynchronously as they become available on the Publisher.

Every subscription has a defined time at which it expires. When that time is reached the Publisher terminates the subscription. The Renew operation may be utilized (3.0) to set a new termination time for a subscription. If the Publisher accepts the request, the new termination time is set on the subscription and the Publisher returns a response (3.1) informing the Subscriber of the outcome of the request.

Termination of a subscription may be requested any time after the subscription was created using the Unsubscribe operation (4.0). If the Publisher accepts the request, it terminates the subscription (4.1) and returns a response (4.2) informing the Subscriber of the outcome of the request.

7.    Requirements Class: Basic Receiver

This Requirements Class specifies the basic operation of a Receiver:

Notify– delivery of a message to the Receiver.  In the context of Publish/Subscribe this is often the delivery of a message that matches the filter criteria of a given subscription.

7.1    Notify operation

The Notify operation is offered by a Receiver to allow the delivery of a message.

In the context of Publish/Subscribe a Sender may use the Notify operation to deliver a message that matches the filter criteria of a subscription to the Receiver associated with that subscription.  Some pull-based message delivery methods, such as ATOM, do not require that the Receiver to implement this requirements class for message delivery.

7.1.1    Request

The Notify operation is based on the fundamental datagram pattern, where a single message is sent from one system entity to another (the Receiver), without expecting a response.  Therefore, it need not be the same as the Request/Response message exchange pattern.

7.1.2    Response

No response is expected/defined for the Notify operation.

7.1.3    Exceptions

No exception is defined for the Notify operation.

8.    Requirements Class: Basic Publisher

This Requirements Class specifies the basic Publish/Subscribe operations of a Publisher:

Subscribe- allows for the creation of subscriptions against publications offered by a Publisher;

Renew- allows for the renewal of a subscription on a Publisher; and

Unsubscribe- allows for removal of a subscription on a Publisher.

Additionally this Requirements Class specifies Publish/Subscribe capabilities metadata that is offered in response to a GetCapabilities operation, whether offered as a Publish/Subscribe GetCapabilities as defined in Clause 9 or through a GetCapabilities operation defined by another OGC Web Service - such as the OGC Web Feature Service (WFS). This Requirements Class does not define a GetCapabilities operation, only the capabilities metadata that is offered by a Publish/Subscribe service.

All classes defined in this standard are extensible and may therefore contain additional parameters that can be used and/or defined by an extension.

8.1    Capabilities metadata

Capabilities metadata for a Publisher is defined in three parts: filtering capabilities (Clause 8.1.1), delivery capabilities (Clause 8.1.2), and published contents (Clause 8.1.3).

These components are each offered as the result of a GetCapabilities operation, either defined by the Standalone Publisher Requirements Class (Clause 9) or another OGC web service. In the latter case an existing GetCapabilities operation is extended with Publisher metadata.

            This Standard does not specify mechanisms for incorporating Publisher capabilities metadata into other OGC web services

Publish/Subscribe conformance classes are advertised with the Profile section of the ServiceIdentification portion of Capabilities documents.

8.1.1    FilterCapabilities

The FilterCapabilities data type describes the filtering-related capabilities of a Publisher. A Publisher may support specific filter languages, such as the OGC Filter Encoding Spec or XPath, that is used by a Subscriber to define a subset of messages of interest on a subscription. In order to support the creation of filtered subscription requests, the Publisher provides metadata about the filter languages it supports, if any.

The FilterLanguage type contains information about the filter languages that the Publisher supports for matching messages against subscriptions.

FilterLanguage identifiers are provided to the Subscribeoperation along with the actual filter specified in that language. For example, the Subscribe operation may be executed with the XPath filter language identifier (e.g., “http://www.w3.org/TR/xpath”) along with the specific XPath (e.g., “/messageType1”) that defines the messages of interest. The OGC Filter Encoding Specification (see ISO 19143 / OGC 09-026) is an example of a filter language that may be relevant for a Publisher associated with a Web Feature Service (WFS).

FilterLanguage identifiers are advertised for specific publications as part of the Publications data type. Publishers may choose to support a different set of filter languages for each publication. FilterLanguage identifiers advertised in FilterCapabilities need not be associated with any publication offered by the Publisher, such as cases where no publications are offered or the set of offered publications varies over time.

8.1.2    DeliveryCapabilities

A Publisher must support a set of delivery methods that a Subscriber can use to define a method for delivering messages of interest on a subscription. The DeliveryCapabilities type describes the set of delivery methods supported by a Publisher, such as ATOM, AMQP, or SOAP over HTTP.

The DeliveryMethod type contains information on a single method by which a Publisher can deliver messages.

8.1.3    Publications

The contents offered by a Publisher are described in the Publications type. The Publications type includes all of the offered publications that Subscribers can subscribe to. The Publication type contains information on an individual publication.

Publication content types specify the media/MIME type of the published content. A publication may be offered in multiple formats, such as ‘application/xml’ and ‘application/json’.

Publication bounding boxes carry the same meaning as that used for [OGC 06-121r3]. Specifically, publications may have any number of bounding boxes whose union describes the extent of the published contents.

8.2    Exception usage

In the event that a Publisher encounters an error while processing a request or receives an invalid request, it shall generate an OWS Exception indicating that an error has occurred. The form of the error response is specified by the ExceptionReport defined in Clause 8 of the OWS Common Specification [OGC 06-121r3].

The mandatory version parameter is used to indicate the version of the service exception report, which shall be “1.0.0”. The optional language may be used to indicate the language used. The code list for the language parameter is defined in [IETF RFC 4646].

Individual exception messages are contained within the OWS ExceptionText. The mandatory code is used to associate an exception code with the accompanying message. The optional locator may be used to indicate where an exception was encountered in the request that generated the error.

Multiple exceptions may be reported in a single exception report so implementations should endeavor to report as many exceptions as necessary to clearly describe a problem.

8.3    Subscribe operation

The Subscribe operation is offered by the Publisher to allow Subscribers to subscribe for messages. To invoke the Subscribe operation, a Subscriber sends a Subscribe request message to the Publisher. The Publisher then processes the request and determines if the proposed subscription is acceptable. If so, the Publisher creates a subscription and returns a SubscribeResponse. If it is not acceptable or problems occur while processing the request, the Publisher returns an exception.

8.3.1    Subscription

Subscribers express their interest in a specific set of messages that are available to a Publisher with a subscription. When a subscription has been submitted to a Publisher, the Publisher delivers messages that match the subscription criteria to the location defined by the subscription.

A Publisher creates a subscription when it accepts a Subscribe request. The subscription has a well-defined termination time. That time is an absolute point in time in the future.

The termination time defines the point in time at which the Publisher terminates the subscription. A subscription can be terminated at any time by explicitly requesting its termination (see Unsubscribe in Clause 8.4). In addition, the termination time of a subscription can be updated to a different time (see Renew in Clause 8.5) at a later point in time.

The subscription filter is used to express the interest in a certain set of messages. The filter itself is an expression evaluating to a boolean value. Filter languages may support logical combinations of filter expressions, such as the OGC Filter Encoding Specification (see ISO 19143 / OGC 09-026).

A subscription has the properties shown in the following figure.

The lifecycle of a subscription is shown in Figure 8. The matching process takes place against all active subscriptions whenever a new message is available to the Publisher.

The Publisher performs matching by evaluating the filter against the new message. If the boolean value of the filter evaluates to “true” for a message, then the message matches the subscription. If no filter is defined, all messages match for the publication defined in the subscription. When a message matches, the Publisher is responsible for delivering it to the Receiver specified in the subscription.

            The Basic Publisher conformance class requires that the Publisher attempt to deliver matching messages once. This does not prevent repeated attempts to deliver the message or the use of additional mechanisms to guarantee the message delivery. The delivery method and/or transport mechanism may provide additional delivery guarantees for messages.

The Publisher starts matching new messages against a subscription once that subscription has been created. This can happen at any time after it received the request to create that subscription, and must happen before a SubscribeResponse is returned. Therefore, the Receiver specified for a new subscription should be ready to receive incoming messages before the Subscriber has received the SubscribeResponse.

Likewise, the Publisher stops matching new messages against a subscription once it has been terminated. Message matching and message delivery are independent; message matching will cease after termination, but messages that have previously matched may still be delivered.

8.3.2    Request

A Subscriber sends a Subscribe request to the Publisher in order to create a new subscription.

The deliveryLocation parameter defines the system endpoint where the Publisher should send messages that match the filter criteria of the requested subscription. The deliveryLocation parameter is optional, as in some cases the Publisher may assign a deliveryLocation to the subscription rather than accept a deliveryLocation from a Subscriber. Extensions to the Basic Publisher conformance class (e.g. bindings) may specialize the use of this parameter.

For example, in WS-BaseNotification[2] it is mandatory to specify an endpoint in a Subscribe request. In a RESTful binding with ATOM-based delivery, the Publisher might create an ATOM feed to which all messages matching a given subscription are sent. In the latter case, the Publisher determines the delivery location and will raise an Exception if one is provided in the Subscribe request.

When a Subscribe request includes a deliveryMethod it must be among those listed in the DeliveryCapabilities section of the PublisherCapabilities document.

The terminationTime parameter defines the requested time when a subscription terminates. That time must be an absolute time in the future. The Publisher may choose to reject the requested termination time with an Exception.

The filter parameter in a Subscribe request defines which messages match the requested subscription, i.e., it defines the subset of messages available in a publication that are of interest to the Subscriber.

The filterLanguageId parameter defines the language using for encoding the Filter in the Subscribe request. The supported filter languages are advertised in the supportedFilterLanguage of each Publication, and in the FilterCapabilities of the Publisher.

The contentType parameter defines the format of the data contents for the subscription. Must be from the list of content types for the publication, advertised in the Publications of the service instance. It can be omitted if there is only one content type advertised for the Publication.

8.3.3    Response

If the request is accepted and no Exception is raised, the Publisher creates a new subscription with information from the Subscribe request, determines any other information not provided by the Subscriber (such as delivery location, termination, etc.) and returns a SubscribeResponse. The SubscribeResponse includes the complete and valid subscription that was created.

8.3.4    Exceptions

Exceptions raised as a result of the Subscribe operation are described below.

8.4    Unsubscribe operation

The Unsubscribe operation allows Subscribers to terminate a subscription. To invoke the Unsubscribe operation, a client sends an Unsubscribe request message to the Publisher. The Publisher then processes the request and determines if it is acceptable. If so, the Publisher terminates the subscription identified in the request and returns an Unsubscribe operation response. If it is not acceptable or problems occur while processing the request, the Publisher returns an exception.

8.4.1    Request

The Unsubscribe request identifies the subscription that the client wants to terminate, as shown in Figure 11.

8.4.2    Response

If the request is accepted and no Exception is raised, the Publisher terminates the subscription and ceases message matching. Undelivered messages that matched before termination may be delivered after termination.

8.4.3    Exceptions

Exceptions raised as a result of the Unsubscribe operation are described below. Unsuccessful Unsubscribe requests do not change any subscription state.

8.5    Renew operation

The Renew operation allows subscribers to set the termination time on a subscription to a new time. This new time may be before or after the current termination time.

            A subscription that has already been terminated (either automatically expired or explicitly via the Unsubscribe operation) cannot be renewed.

To invoke the Renew operation, a client sends a Renew request message to the Publisher. The Publisher then processes the request and determines if the proposed termination time is acceptable.

If so, the Publisher updates the subscription and returns a RenewResponse. If it is not acceptable or problems occur while processing the request, the Publisher returns an exception.

8.5.1    Request

A client sends a Renew request to the Publisher in order to update the termination time of an existing subscription.

8.5.2    Response

If the request is accepted and no Exception is raised, the Publisher accepts the request, updates the termination time of the subscription, and returns a RenewResponse.

            This Requirements Class does not define any content to be returned in a RenewResponse. Extensions may include more information, such as further information about the updated subscription.

8.5.3    Exceptions

Exceptions raised as a result of the Renew operation are described below. Unsuccessful Renew requests do not change any subscription state, in particular termination time.

9.    Requirements Class – Standalone Publisher extends Basic Publisher

This Requirements Class enables standalone publishing, wherein Publishers offer metadata concerning Publisher capabilities. This Requirements Class requires that a Publisher implement two operations:

GetCapabilities- allows for the discovery of Publisher metadata, including offered publications, service capabilities, and service provider information; and

GetSubscription- allows for the retrieval of subscription information.

The Standalone Publisher includes a Publish/Subscribe GetCapabilities operation extended from OWS Common [OGC 06-121r3] that integrates FilterCapabilities, DeliveryCapabilities, and Publications metadata as specified in Clause 8.1.

9.1    GetCapabilities operation

The GetCapabilities operation allows clients to retrieve the capabilities metadata (also called the “capabilities document”) of a Publisher. This includes supported functionality (e.g. filter functionality, or functionality defined in other Publish/Subscribe Requirements Classes) requirements for use (e.g. that Subscribers authenticate themselves to the service) and content information (e.g., formal description of published contents).

The Publish/Subscribe GetCapabilitiestype derives from the OWS Common GetCapabilitiestype described in Table 3 of [OGC 06-121r3].

9.1.1    Request

The Publish/Subscribe GetCapabilities request extends the OWS Common GetCapabilitiesType with limited information.

9.1.2    Response

If the request is accepted and no Exception is raised, the Publisher returns a PublisherCapabilities. PublisherCapabilities is an extension of the OWS Common Capabilities document that adds filter capabilities, delivery capabilities, and publications/contents metadata. These additional portions of the Capabilities document are specified in the FilterCapabilities, DeliveryCapabilities, and Publication clauses in Clause 8.1.

9.1.3    Exceptions

Exception behavior for the GetCapabilities operation is defined in Table 8 and Clause 8 of the OWS Common Specification [OGC 06-121r3].

9.2    GetSubscription operation

A Subscriber invokes the GetSubscription operation in order to retrieve information on one or more subscriptions.

            Terminated subscriptions are not returned. Publishers may return an empty list if all the requested subscriptions have expired or were explicitly terminated via the Unsubscribe operation.

To invoke the GetSubscription operation, a client sends a GetSubscription request message to the Publisher. The Publisher then processes the request and determines if it is acceptable. If so, the Publisher returns a GetSubscription operation response. If it is not acceptable or problems occur while processing the request, the Publisher returns an exception.

9.2.1    Request

A client sends a GetSubscription request to the Publisher in order to retrieve the active subscriptions. The Publisher needs to determine if the request is acceptable. In order to do so, the Publisher performs syntactic as well as semantic checks regarding the request.

9.2.2    Response

If the request is accepted and no Exception is raised, the Publisher returns the requested active subscriptions in a GetSubscriptionResponse. If no subscription identifiers are specified in the request, the Publisher returns all active subscriptions (see the state diagram in Figure 8).

9.2.3    Exceptions

Exceptions raised as a result of the GetSubscription operation are described below.

10.    Requirements Class – Pausable Publisher extends Basic Publisher

The Pausable Publisher Requirements Class enables subscription pausing, wherein Publishers may be directed to pause and resume message delivery for a subscription. Message matching for a paused subscription continues unchanged, but matching messages are not delivered until the subscription is resumed. This Requirements Class requires that a Publisher implement two operations:

Pause- allows for the pausing of an unpaused subscription, which pauses message delivery; and

Resume- allows for the resumption of a paused subscription, which resumes message delivery.

            Pausing and resuming of subscriptions is independent of subscription termination. Paused subscriptions are subject to subscription termination (through expiry or other means) in an identical manner to active subscriptions.

When a paused subscription is resumed, the Publisher delivers all matched but undelivered messages for the subscription. Message delivery (as well as message matching) may also be halted with the Unsubscribe and Subscribe operations, except that matching messages that arrive between the Unsubscribe and the new Subscribe call will be lost.

            Pausable Publishers deliver messages for resumed subscriptions on a best-effort basis. Not all messages are guaranteed to be delivered upon resumption of the subscription. Storage limitations and other practical considerations may prevent the delivery of some messages that arrived while a subscription is paused. A future revision of this Standard may specify delivery guarantees, but none are currently made.

In cases of asynchronous message delivery, some messages may be in transit when the Pause operation is executed. When this occurs, message delivery may continue after the Pause operation is successfully completed and the Publisher has ceased initiating the delivery of messages.

The valid subscription states and transitions between states are shown in Figure 19. Execution of the Pause operation is equivalent to executing a pause state transition. Similarly, execution of the Resume operation is equivalent to executing a resume state transition.

Paused subscriptions only differ from active subscriptions in terms of message delivery. Therefore, they are valid targets and valid responses from all operations that include active subscriptions, such as GetSubscription responses.

10.1    Pause operation

10.1.1    Request

The Pause request includes a single property that identifies the subscription to be paused.

10.1.2    Response

If the request is accepted and no Exception is raised, the Publisher pauses the subscription and returns a PauseResponse. The PauseResponse is returned when the relevant subscription has been successfully paused.

10.1.3    Exceptions

Exceptions raised as a result of the Pause operation are described below. Unsuccessful Pause requests do not change any subscription state.

10.2    Resume operation

10.2.1    Request

The Resume request includes a single property that identifies the subscription to be resumed. All messages that have matched for a subscription but have not yet been delivered will be delivered when the Resume operation is completed.

10.2.2    Response

If the request is accepted and no Exception is raised, the Publisher resumes the subscription and returns a ResumeResponse. The ResumeResponse is returned when the relevant subscription has been successfully resumed.

10.2.3    Exceptions

Exceptions raised as a result of the Resume operation are described below. Unsuccessful Resume requests do not change subscription state.

11.    Requirements Class – Message Batching Publisher extends Basic Publisher

The Message Batching Publisher Requirements Class specifies capabilities for Subscribers to communicate message-batching directives. Message batching allows Subscribers to specify desired message delivery at a different rate than the messages are natively generated. This includes cases where frequent, small messages are published that can be consumed more efficiently in batches by the Receiver.

11.1    Batching criteria

Message-batching criteria are optionally set by providing a BatchingCriteria object to the Subscribe operation. The batching criteria supported include:

•   Time period (e.g. every 5 minutes, every hour); and
•   Batch size (e.g. every 20 messages, every 150 messages).

More than one criterion may be supplied at once. When multiple criteria are supplied, the first criterion that applies triggers the delivery of the batch.

Messages matching a BatchingCriteria are accumulated and withheld by the Publisher. When either the number of messages equals maxMessageCount or the time passed since the last delivery exceeds maxDelay, all the withheld messages are delivered.  Subscription termination will trigger the batch delivery of any withheld (undelivered) messages for that subscription.

If the maxDelayperiod is reached without any withheld messages to deliver, no message delivery will take place. No message batch will ever be delivered with more messages than maxMessageCount. 

For example, in the case where a Subscriber submitted a subscription via the Subscribe operation with batching criteria indicating a maxDelay of 10 minutes and a maxMessageCount of 30 the Publisher would withhold the messages for this publication until 30 matching messages become available or 10 minutes pass, whichever occurs first.

  The use of this conformance class in conjunction with the Heartbeat Publisher conformance class can result in batched heartbeats. Subscribers are recommended to exercise caution when both message batching and heartbeats are used in conjunction.

11.2    Exceptions

Exceptions raised as a result of the Subscribe operation are described below.

12.    Requirements Class – Heartbeat Publisher extends Basic Publisher

The Heartbeat Publisher Requirements Class specifies capabilities to ensure that the Receiver is sent notifications on a regular basis. This Requirements Class enables Receivers to detect outages due to network failures, Publisher failures, or other issues preventing communication of messages for an active subscription. This Requirements Class addresses end-to-end subscription delivery life, and as such is a capability that is most useful when the original Publisher or Sender is capable of issuing heartbeats.

12.1    Heartbeat criteria

Subscribers may optionally specify a rate for heartbeat messages to be issued by the Publisher.

HeartbeatMessages are messages sent on a regular period, each of which includes the heartbeat issuance time from the Publisher. The arrival of these messages indicates that the Publisher was able to deliver messages as of that time, as observed by the Publisher’s clock when it initiated the delivery of the HeartbeatMessage.

            HeartbeatMessages may be represented as a header entry, unique message, or other representation depending on the delivery method.

12.2    Exceptions

Exceptions raised as a result of the Subscribe operation are described below.

13.    Requirements Class – Brokering Publisher extends Standalone Publisher

A Brokering Publisher, or broker, is an intermediary between Subscribers and other Publishers which have been previously registered with the broker. The broker is not the original producer of messages, but only acts as a message middleman, re-publishing messages received from other Publishers and decoupling them from their Subscribers. This Requirements Class requires that a Publisher implement the operations:

RegisterPublisher- allows the connection of an external Publisher to the broker; and

RemovePublisher- allows the disconnection of a Publisher from the broker.

A broker is a distinct third party that acts as a communication intermediary between the source and the target of a communication, mediating their interfaces and in some cases adding new behavior. A broker may aggregate the messages into different publications, may provide the same publications with a with different delivery methods, or otherwise process the messages (e.g. converting their format). A broker may also provide advanced messaging features such as load balancing. However, a broker should not advertise capabilities on behalf of another Publisher, unless the latter provides identical guarantees (e.g. heartbeat capabilities).

Examples of Brokering Publisher applications include the following.

Publisher Aggregation – a broker subscribes to several Publishers and relays their publications (without modification) to interested Subscribers, acting like a Proxy to multiple Publishers. Optionally, the broker may adapt the service interface (binding) of the aggregated Publishers.

Publication Aggregation – a broker receives messages generated by several Publishers (e.g. dumb sensors) and publishes them to the interested Subscribers as a single publication.

This Requirement Class does not mandate any specific behavior to be implemented by a Brokering Publisher, in particular as regards the support to Delivery Capabilities, Filtering Capabilities, and Publications of connected Publishers. Implementations of this Requirement Class are free to interact with the connected Publishers as appropriate for their specific application. Interactions may include subscribing, loading and/or proxying capabilities documents, or other behavior. Future extensions to this Requirement Class may standardize the behavior of Brokering Publishers in specific application scenarios.

            WS-Notification has a similar abstraction, the NotificationBroker, as defined in WS-BrokeredNotification[3].

Figure 27 illustrates the typical broker interaction. The broker behaves like a Basic Publisher in the core Publish/Subscribe. However, the broker relays messages received from an external Publisher, which is assumed to have been previously registered.

The broker provides additional functionalities that support the management of brokered Publishers. The operations described herein allow external Publishers to be registered to and removed from the broker.

13.1    RegisterPublisher operation

The RegisterPublisher operation is used to connect the broker to a given Publisher. As a result of this operation, the broker capabilities may change (e.g. exposing part or all of the FilterCapabilities, DeliveryCapabilities, and Publications of the brokered Publisher); the specification of such changes is out of the scope of this Requirements Class.

13.1.1    Request

The following diagram and table list the request parameters for the RegisterPublisher operation:

13.1.2    Response

If the request is accepted and no Exception is raised, the broker retrieves the capabilities document, verifies that the document is a valid Publish/Subscribe capabilities document, and returns a RegisterPublisherResponse. If there is a failure retrieving or verifying the capabilities document, an Exception is raised.

13.1.3    Exceptions

Exceptions raised as a result of the RegisterPublisher operation are described below.

13.2    RemovePublisher operation

The RemovePublisheroperation removes a Publisher from the broker. As a result of this operation, the broker capabilities may change (e.g. removing the Publications, FilterCapabilities, DeliveryCapabilities of the removed Publisher); the specification of such changes is out of the scope of this Requirements Class.

13.2.1    Request

The following figure and table list the parameters for the RemovePublisheroperation:

13.2.2    Response

If the request is accepted and no Exception is raised, the broker accepts the request, removes the specified Publishers and returns a RemovePublisherResponse.

13.2.3    Exceptions

Exceptions raised as a result of the RemovePublisher operation are described below.

13.3    GetCapabilities operation

In addition to the three parts offered by Standalone Publishers: filtering capabilities (Clause 8.1.1), delivery capabilities (Clause 8.1.2), and published contents (Clause 8.1.3) Brokering Publishers add RegisteredPublishers: the set of registered Publishers.

13.3.1    RegisteredPublishers

The set of registered Publishers on a broker is described with the RegisteredPublishers type. RegisteredPublishers is returned as part of the PublisherCapabilities type as a result of the GetCapabilities operation.

14.    Requirements Class – Publication Manager extends Basic Publisher

The Publication Manager Requirements Class supports the creation, removal, and subscriptions to user-defined publications that are derived from an existing publication. This Requirements Class requires that a Publisher implement two operations:

CreatePublication- allows for the creation of a new derived publication based upon an existing publication with an optional filter; and

RemovePublication- allows for the removal of a derived publication.

A derived publication is a publication that is created by applying an optional additional filter and/or processing expression to messages aggregated within an existing publication. As with any publication, a Subscriber may subscribe to a derived publication. Derived publications allow subscription filters to be shared among a large number of Subscribers rather than having each Subscriber create a subscription with the same filter and/or processing transformation. This capability can be useful in cases such as large enterprises where different filtering and processing criteria on publications is required for different sets of Subscribers in order to satisfy policy and/or legal requirements.

This clause describes operations that support the management of derived publications. The operations described herein allow derived publications to be created and removed from the system.

14.1    Publication Types

The DerivedPublication type is a specialized type of publication that is a distinct type of offered publication. Specifically, an offered publication is published content in its original form, whereas DerivedPublications are derived from a processed and/or filtered form of another publication. Therefore, there may be any number of DerivedPublications that apply processing or filtering to a single base publication. DerivedPublication identifiers are accepted as publication identifiers to all Publish/Subscribe operations and are included among publications results in GetCapabilities and other relevant operationresponses.  DerivedPublications themselves may be used as a base publication when creating a new DerivedPublication, and it is therefore possible to create a hierarchy of publications with a single base publication at its root.

This Requirements Class also adds an extension to the Publication type to allow Publishers to advertise the supported processing languages for each base Publication. The mechanism for advertising the supported processing languages is similar to that of supported filter languages. Therefore, as with filter languages, a set of supported processing languages is advertised in the GetCapabilities response and each Publication lists the set of processing languages allowed for each specific Publication.

14.1.1    ProcessingCapabilities

The ProcessingCapabilities data type describes the processing-related capabilities of a Publisher. A Publisher may support specific processing languages, such as XSLT, or WCPS. In order to support the creation of processed derived publications, the Publisher provides metadata about the processing languages it supports, if any.

The ProcessingLanguage type contains information about the processing languages that the Publisher supports for processing matching messages before the delivery.

ProcessingLanguage identifiers are provided to the CreatePublicationoperation along with the actual processing expression specified in that language. For example, the CreatePublicationoperation can be executed with the WCPS processing language identifier (e.g., “http://www.opengis.net/wcps/1.0”) along with the specific expression that defines the process of interest.

ProcessingLanguage identifiers are advertised for specific publications as part of the DerivedPublications data type. Publishers may choose to support a different set of processing languages for each publication. ProcessingLanguage identifiers advertised in ProcessingCapabilities need not be associated with any publication offered by the Publisher, such as cases where no publications are offered or the set of offered publications varies over time.

14.2    CreatePublication operation

The CreatePublication operation is used to create a filtered view of a publication offered by a publisher. The salient parameters for the operation are a base publication identifier, an optional filter that is used to identify the active set of messages, and an optional processing expression. A derived publication with only filtering applied may be considered conceptually equivalent to a stored query.

While filtering allows for a subset of messages from the base publication to be offered, processing expressions change the nature of the delivered messages (relative to the base publication) in some fashion. One example of processing capabilities would be a Web Coverage Processing Service (WCPS) augmented with Publish/Subscribe that allows for the creation of derived publications with WCPS processing expressions. Subscribers may then subscribe to a derived publication and receive the processed messages. Processing is applied to messages by the Publisher prior to being made available as part of the derived publication.

14.2.1    Request

The following diagram and table list the request parameters for the CreatePublication operation:

14.2.2    Response

If the request is accepted and no Exception is raised, the Publisher creates a new DerivedPublication and returns a CreatePublicationResponse.

14.2.3    Exceptions

Exceptions raised as a result of the CreatePublication operation are described below.

14.3    RemovePublication operation

The RemovePublication operation deletes one or more derived publications from the system.

14.3.1    Request

The following figure and table list the parameters for the RemovePublication operation:

DerivedPublications may be created using other DerivedPublications as the base publication. However, any publications with active DerivedPublications cannot be removed until their child DerivedPublications have first been removed.

DerivedPublications are publications, and as such the Publisher shall follow normal subscription termination procedures as described in Clause 8.3.1 when a DerivedPublication is removed to which active subscriptions are associated.

14.3.2    Response

If the request is accepted and no Exception is raised, the Publisher removes the specified DerivedPublication and returns a RemovePublicationResponse.

14.3.3    Exceptions

Exceptions raised as a result of the RemovePublication operation are described below.

15.    Requirements Class – Capabilities Filtering extends Basic Publisher

15.1    Introduction

Clause 8.1 of this standard and Clause 7.4 of OGC 06-121r3 define the response to a GetCapabilities request. The response is composed of a number of sections including a Publications section, which lists the publications offered for subscription by a Publisher, otherwise known as a content section. This Publications section can become quite large, hindering the efficient transmission of a capabilities document over the Internet. For example, a Publisher may offer many thousands of publications resulting in a large and cumbersome capabilities document. The content section of OGC web services may include multiple items, in this case individual publications.

This clause defines syntactic and semantic extensions to the GetCapabilities operation in order to support very large Publications sections. Specifically, this clause defines additional parameters for the GetCapabilities request that allow a client to:

• control the number of items that appear in the Publications section;
• page through a Publications section that includes a large number of items; and
• specify query predicates, including spatial and temporal predicates, which allow a client to control which items are listed in the Publications section.

15.2    Request

Table 3 in Clause 7 of OGC 06-121r3 defines the standard set of request parameters for the GetCapabilities operation. Table 39 below defines additional parameters for the GetCapabilities operation that enables support for large Publications sections.

The default maximum number of content items returned is 15 unless specified otherwise by the count parameter described in Table 39. As this conformance class addresses the requirements of web services with large numbers of content items, this means that clients executing the GetCapabilities operation will not be overwhelmed by large Capabilities responses before being able to discover the functional capabilities.

15.3    Response

Without the parameters defined in Table 39, the GetCapabilities operation behaves as described in OGC 06-121r3 and generates a complete Publications section as defined in Clause 9.1.4 of this standard and Clause 7.4 of OGC 06-121r3. The response to a GetCapabilities filtering query will always be a valid Capabilities document. The parameters in Table 39, if specified, only affect what items appear in the Publications section of the response. Contents filtering will not take effect if the GetCapabilities request excludes the Publications section from appearing in the response via the sections parameter described in OGC 06-121r3.

15.4    Examples

The following request fragments exemplify (in a KVP encoding) how the parameters in Table 39 affect the behavior of the GetCapabilities operation.

Example 1: Excluded Publications section

…&sections=ServiceIdentification,ServiceProvider&searchTerms=blue,ox&…

In this example, the searchTerms parameter is ignored since the request specifically excludes the Publications section (as specified by sections=ServiceIdentification,ServiceProvider).

Example 2: Publications section paging

…&sections=Publications &count=10&startIndex=11&…

In this example, only the Publications section is presented in the response and the Publications section contains 10 items (i.e., items 11 through 20).

Example 3: Publications section filtering

…&sections=Publications &searchTerms=restaurants&bbox=43.57,-79.64,43.89,-79.12&…

In this example, only the Publications section is presented, and the records that contain the search term “restaurants” and lie within the rough boundary of Toronto, Ontario, Canada.

Example 4: Publications section filtering

…&sections=Contents&searchTerms=javascript&start=01-01-2013&end=06-30-2013&…

In this example, only the Publications section is presented, and the records that contain the search term “javascript” and have a salient date in the first 6 months of 2013.

15.5    Exceptions

Exceptions raised as a result of the GetCapabilities operation are described below.

Annex A Abstract Test Suite (Normative)

A Publish/Subscribe implementation must satisfy the following system characteristics to be conformant with this specification.

Test, requirement, requirements class, and conformance class identifiers below are relative to http://www.opengis.net/spec/pubsub/1.0/.

The minimum set of conformance classes an implementation needs to pass are either Basic Receiver (section A.1) or Basic Publisher (section A.2)

A.1      Conformance class: Basic Receiver

A.2      Conformance class: Basic Publisher

Test: /conf/core/basic-publisher/getcapabilities-conf-class-listing

Test: /conf/core/basic-publisher/getcapabilities-filtercapabilities

Test: /conf/core/basic-publisher/unique-filter-languages

Test: /conf/core/basic-publisher/deliverycapabilities

Test: /conf/core/basic-publisher/unique-delivery-method

Test: /conf/core/basic-publisher/publications

Test: /conf/core/basic-publisher/publication-valid-filter-language

Test: /conf/core/basic-publisher/publication-valid-delivery-method

Test: /conf/core/basic-publisher/publication-unique-publication-id

Test: /conf/core/basic-publisher/valid-exceptions

Test: /conf/core/basic-publisher/exception-version

Test: /conf/core/basic-publisher/subscribe

Test: /conf/core/basic-publisher/subscribe-assign-unique-id

Test: /conf/core/basic-publisher/subscribe-default-termination-time

Test: /conf/core/basic-publisher/match-active-subscriptions

Test: /conf/core/basic-publisher/match-inactive-subscriptions

Test: /conf/core/basic-publisher/interrupt-matching

Test: /conf/core/basic-publisher/termination

Test: /conf/core/basic-publisher/filter-id

Test: /conf/core/basic-publisher/valid-filter-id

Test: /conf/core/basic-publisher/content-type

Test: /conf/core/basic-publisher/subscribe-exceptions

Test: /conf/core/basic-publisher/unsubscribe

Test: /conf/core/basic-publisher/halt-matching

Test: /conf/core/basic-publisher/unsubscribe-exception-state

Test: /conf/core/basic-publisher/unsubscribe-exceptions

Test: /conf/core/basic-publisher/renew

Test: /conf/core/basic-publisher/renew-update-termination-time

Test: /conf/core/basic-publisher/renew-exception-state

Test: /conf/core/basic-publisher/renew-exceptions

A.3      Conformance class: Standalone Publisher

Test: /conf/core/standalone-publisher/getcapabilities

Test: /conf/core/standalone-publisher/getsubscription

Test: /conf/core/standalone-publisher/getsubscription-all-subscriptions

Test: /conf/core/standalone-publisher/getsubscription-exceptions

A.4      Conformance class: Pausable Publisher

Test: /conf/core/pausable-publisher/pause

Test: /conf/core/pausable-publisher/pause-halt-delivery

Test: /conf/core/pausable-publisher/pause-unchanged-paused-subscription

Test: /conf/core/pausable-publisher/pause-exceptions

Test: /conf/core/pausable-publisher/resume

Test: /conf/core/pausable-publisher/resume-resume-delivery

Test: /conf/core/pausable-publisher/resume-unchanged-active-subscription

Test: /conf/core/pausable-publisher/resume-exceptions

A.5      Conformance class: Message Batching Publisher

Test: /conf/core/message-batching-publisher/subscribe-message-batching

Test: /conf/core/message-batching-publisher/withheld-delivery

Test: /conf/core/message-batching-publisher/reset-batching

Test: /conf/core/message-batching-publisher/subscription-termination

Test: /conf/core/message-batching-publisher/pausing

Test: /conf/core/message-batching-publisher/subscribe-exceptions

A.6      Conformance class: Heartbeat Publisher

Test: /conf/core/heartbeat-publisher/subscribe-heartbeat

Test: /conf/core/heartbeat-publisher/publish-heartbeat

Test: /conf/core/heartbeat-publisher/pausing

Test: /conf/core/heartbeat-publisher/subscribe-exceptions

A.7      Conformance class: Brokering Publisher

Test: /conf/core/brokering-publisher/registerpublisher

Test: /conf/core/brokering-publisher/registerpublisher-connect

Test: /conf/core/brokering-publisher/registerpublisher-exceptions

Test: /conf/core/brokering-publisher/removepublisher

Test: /conf/core/brokering-publisher/removepublisher-exceptions

Test: /conf/core/brokering-publisher/getcapabilities-registered-publishers

A.8      Conformance class: Publication Manager

Test: /conf/core/publication-manager/getcapabilities-processingcapabilities

Test: /conf/core/publication-manager/getcapabilities-unique-processinglanguage

Test: /conf/core/publication-manager/publication-valid-processinglanguage

Test: /conf/core/publication-manager/createpublication

Test: /conf/core/publication-manager/createpublication-publication-id

Test: /conf/core/publication-manager/createpublication-assign-properties

Test: /conf/core/publication-manager/createpublication-assign-identifier

Test: /conf/core/publication-manager/createpublication-filter-id

Test: /conf/core/publication-manager/createpublication-valid-filter-id

Test: /conf/core/publication-manager/createpublication-processinglanguage-id

Test: /conf/core/publication-manager/createpublication-valid-processinglanguage-id

Test: /conf/core/publication-manager/createpublication-exceptions

Test: /conf/core/publication-manager/removepublication

Test: /conf/core/publication-manager/removepublication-nesting

Test: /conf/core/publication-manager/removepublication-base-publication-removal

Test: /conf/core/publication-manager/subscribe-derived-publications

Test: /conf/core/publication-manager/derived-publication-identifiers

Test: /conf/core/publication-manager/removepublication-exceptions

A.9      Conformance class: Capabilities Filtering

Test: /conf/core/capabilities-filtering-publisher/getcapabilities-content-sort

Test: /conf/core/capabilities-filtering-publisher/getcapabilities-content-filter

Test: /conf/core/capabilities-filtering-publisher/getcapabilities-search

Test: /conf/core/capabilities-filtering-publisher/getcapabilities-exceptions

Annex B Publish/Subscribe Interfaces (Informative)

This standard defines operations that can be combined in interfaces as follows:

Annex C Revision history

[1] www.opengeospatial.org/cite

[2] OASIS WS-BaseNotification, Web Services Base Notification, OASIS Standard 1.3 (1 October 2006).

[3] OASIS WS-BrokeredNotification, Web Services Brokered Notification, OASIS Standard 1.3 (1 October 2006).