i. Abstract

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 historically specified by many 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 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 an extension to the OGC Publish/Subscribe (PubSub) 1.0 Core to allow for Publish/Subscribe communications usingthe SOAP protocol.

ii. Keywords

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

Ogcdoc pubsub core standard soap soap protocol binding

iii. Preface

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

No future work 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.

iv. Submitting organizations

The following organizations submitted this Document to the Open Geospatial Consortium Inc.

National Center for Atmospheric Research (NCAR)

National Research Council of Italy (CNR)

v. Submitters

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 using the SOAP protocol.  This standard utilizes core concepts and mechanisms from the OGC® Publish/Subscribe Interface Standard 1.0 Core.

This standard does not address access control.

2.    Conformance

This OGC interface standard defines conformance classes for Publish/Subscribe behaviour with a SOAP protocol binding, as shown in Table 1. Requirements for the following standardization target types are considered (described further in Clause 4):

·      Publisher – an entity that can be used to manage subscriptions.

This document establishes several requirements classes shown below in Table 1. Requirements and conformance test URIs defined in this document are relative to http://www.opengis.net/spec/pubsub/1.0/.

According to the target type hierarchy, this specification defines the following conformance levels:

Conformance with this standard shall be checked using all 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].

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 SOAP Protocol Binding standard consists of the present document and an XML Schema.

The complete OGC Publish/Subscribe 1.0 specification 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 XML Schema is posted on-line at http://schemas.opengis.net/pubsub/1.0 as part of the OGC schema repository. In the event of a discrepancy between this document and schema repository versions of the XML Schema files, the schema repository shall be considered authoritative.

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 (9 February 2009)

W3C XML Namespaces, Namespaces in XML, W3C Recommendation (14 January 1999)

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).

W3C WS-Addressing Core, Web Services Addressing 1.0 – Core, W3C Recommendation (9 May 2006)

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

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

W3C SOAP, Simple Object Access Protocol (SOAP) 1.2, W3C Note (27 April 2007)

W3C WSDL, Web Services Description Language (WSDL) 1.1, W3C Note (15 Mar 2001)

IETF RFC 2616, Hypertext Transfer Protocol – HTTP/1.1, IETF Request for Comments (June 1999)

OGC 13-131, OGC Publish/Subscribe 1.0 Core, OGC® Implementation Standard

OASIS WS-BaseFaults, Web Services Base Faults 1.2, OASIS Standard (1 April 2006)

OASIS WS-ReliableMessaging, Web Services Reliable Messaging 1.2 (2 February 2009)

4.    Terms and Definitions

This document uses the terms defined in Sub-clause 5.3 of [OGC 06-121r8], 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.

This document primarily uses terms and definitions from OGC Publish/Subscribe Core. The terms and definitions given in the other normative references also apply. 

4.1   Reliable Publisher

A publisher of messages that offers capabilities to detect and recover from message delivery losses, whether caused by network failures, software failures, hardware failures, or other causes.

5.    Conventions

5.1    Abbreviations

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

HTTP             Hypertext Transfer Protocol

HTTPS           Secure Hypertext Transfer Protocol

OGC               Open Geospatial Consortium

OMG              Object Management Group

PubSub            Publish/Subscribe

SOAP              Simple Object Access Protocol

UML               Unified Modeling Language (an object modeling language)

WSA               Web Services Addressing

WSN               Web Services Notification

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.

5.4    XML Namespace Conventions

This standard uses a number of namespace prefixes throughout; they are listed in the following table. Note that the choice of any namespace prefix is not semantically significant.

6.    SOAP Publish/Subscribe Overview

This document is an extension of the OGC Publish/Subscribe Core 1.0 document using SOAP web services.

This document specifies Publish/Subscribe capabilities using the WS-BaseNotification specification from OASIS.  This specification extends WS-BaseNotification operations to include discovery and metadata operations such as GetCapabilities.

This document does not mandate a single, specific version of SOAP to be used in message exchanges. This enables established systems that intend to implement OWS Publish/Subscribe functionality to require any version of SOAP for Publisher operations. For maximum interoperability, it is recommended that SOAP Publish/Subscribe services support SOAP version 1.2 (see W3C SOAP) for requests and responses.

Information on version mismatch can also be communicated per actual message exchange – see http://www.w3.org/TR/soap12-part1/#version for further details.

For maximum interoperability it is suggested that SOAP implementations be compliant with the OASIS WS-Interoperability (WS-I) Basic Profile.

For disambiguation, the following table lists SOAP and [OASIS WS-BaseNotification] terms and their corresponding Publish/Subscribe concepts.

Terms as defined by WS-BaseNotification will be explicitly marked as such in this document. If no qualifier (such as “Publish/Subscribe” or “OASIS WS-BaseNotification”) is provided for a given term, the Publish/Subscribe terminology is assumed.

7.    Requirements Class: SOAP Basic Receiver extends Basic Receiver

This Requirements Class specifies the basic operation of a SOAP Basic Receiver:

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

7.1    Notify operation

The Notify operation from WS-BaseNotification NotificationConsumer interface is implemented by a Receiver to allow the delivery of SOAP messages.  This interface is specified in [OASIS WS-BaseNotification] Clause 3.

7.1.1    Response

There is no response from the Notify operation.

7.1.2    Exceptions

No exceptions are defined for the Notify operation.

8.    Requirements Class: SOAP Basic Publisher extends Basic Publisher

This Requirements Class specifies the basic Publish/Subscribe operations of a Publisher using the SOAP protocol.  The SOAP operations in this Requirements Class are implemented as operations from the NotificationProducer interface from [OASIS WS-BaseNotification]:  

Subscribe– allows for the creation of subscriptions against publications offered by a Publisher.  This is implemented as the Subscribe operation from [OASIS WS-BaseNotification];

Renew– allows for the renewal of a subscription on a Publisher. This is implemented as the Renew operation from [OASIS WS-BaseNotification]; and

Unsubscribe– allows for removal of a subscription on a Publisher. This is implemented as the Unsubscribe operation from [OASIS WS-BaseNotification].

This Requirements Class extends the Publish/Subscribe Core Basic Publisher, and as such also returns capabilities metadata that is offered in response to a GetCapabilities operation. Therefore this capabilities metadata may either be offered as a Publish/Subscribe GetCapabilities operation as described in the Publish/Subscribe Core Standalone Publisher requirements class or through a GetCapabilities operation defined by another OGC Web Service such as the OGC Web Feature Service (WFS).  

8.1    Usage of WS-BaseNotification

OGC Publish/Subscribe filtering information is sent in the /wsn-b:Subscribe/wsn-b:/Filter/wsn-b:MessageContent section of the request.  In this case, the Dialect attribute on the wsn-b:MessageContent element shall be set appropriately to represent the filtering dialect.  The content of the Dialect attribute should be one of the FilterCapabilities identifiers advertised by the Publisher in the GetCapabilities operation.

Subscribe requests must also include the pubsub:publicationIdentifier element as a child of the wsn-b:Subscribe element.

8.2    Subscribe Operation

8.2.1    Subscription

The following table summarizes how the Publish/Subscribe Subscription is realized in SOAP.

8.3    Renew Operation

The semantics for the termination time set in the request are the same in OGC Publish/Subscribe and [OASIS WS-BaseNotification]. [OASIS WS-BaseNotification] also specifies that an exception is thrown if the requested termination time is not in the future.

However, use of the xsi:nil attribute with value “true” on the wsn-b:Renew/wsn-b:TerminationTime to request an infinite duration (see [OASIS WS-BaseNotification] section 6.1.1) is prohibited.

Renew requests must include the pubsub:publicationIdentifier element as a child of the wsn-b:Renew element.

The response semantics for the Renew operation are the same in OGC Publish/Subscribe and [OASIS WS-BaseNotification]. In both cases the response indicates that the subscription identified in the request (explicitly in the case of OGC Publish/Subscribe, implicitly in the case of [OASIS WS-BaseNotification]) has been updated to terminate at the requested point in time.

[OASIS WS-BaseNotification] supports functionality to differentiate and handle different time on the client and server roles (NotificationProducer, SubscriptionManager). OGC Publish/Subscribe does not make this distinction.

8.4    Unsubscribe operation

Unsubscribe requests must include the pubsub:publicationIdentifier element as a child of the wsn-b:Unsubscribe element.

8.5    Exception and Fault Usage

In the event that a Publisher encounters an error while processing a request or receives an invalid request, it shall generate a SOAP Fault.  Exceptions defined by Publish/Subscribe Core and Publish/Subscribe extensions are encoded as an ExceptionReport in the FaultCause section of each SOAP Fault.  SOAP Faults types and usage are described in [OASIS WS-BaseNotification] and associated specifications. Therefore the Fault type (such as UnacceptableTerminationTimeFault) and ExceptionReport type (such as TerminationUnacceptable) portions of each issued Fault may be considered independent.  Each Exception will be of the appropriate type as described in Publish/Subscribe Core.

For the Subscribe, Unsubscribe, and Renew operations the following Fault and Exception codes are used. 

Topic-related Exceptions are mapped below for completeness as they are defined in [OASIS WS-BaseNotification], but are not utilized in this Standard.

8.5.1    SOAP Fault Examples

A sample SOAP 1.1 fault encoding is as follows:

<soap11:Envelope xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
     xmlns:wsrf-bf=”http://docs.oasis-open.org/wsrf/bf-2”
     xmlns:soap11=”http://schemas.xmlsoap.org/soap/envelope/” 
     xmlns:wsa=”http://www.w3.org/2005/08/addressing”
     xmlns:wsnt=”http://docs.oasis-open.org/wsn/b-2”
     xmlns:pubsub=”http://www.opengis.net/pubsub/1.0”
     xsi:schemaLocation=”http://schemas.xmlsoap.org/soap/envelope/ http://schemas.xmlsoap.org/soap/envelope/
     http://www.opengis.net/pubsub/1.0 http://schemas.opengis.net/pubsub/1.0.0/pubsubAll.xsd
     http://docs.oasis-open.org/wsn/b-2 http://docs.oasis-open.org/wsn/b-2.xsd”>
     <soap11:Header>
         <wsa:Action>http://docs.oasis-open.org/wsn/fault</wsa:Action>
     </soap11:Header>
     <soap11:Body>
         <soap11:Fault>
             <faultcode>soap11:Client</faultcode>
             <faultstring>The publication identifier ‘xyz’ is invalid</faultstring>
             <detail>
                 <wsnt:SubscribeCreationFailedFault>
                     <wsrf-bf:Timestamp>
                         2005-05-04T20:18:44.970Z
                     </wsrf-bf:Timestamp>
                     <wsrf-bf:Description>
                         The publication identifier ‘xyz’ is invalid
                     </wsrf-bf:Description>
                     <wsrf-bf:FaultCause>
                         <ows:ExceptionReport version=”1.0.0” xmlns:ows=”http://www.opengis.net/ows/1.1”>
                             <ows:Exception exceptionCode=”InvalidPublicationIdentifier” locator=”xyz”>
                                 <ows:ExceptionText>
                                     The publication identifier ‘xyz’ is invalid
                                 </ows:ExceptionText>
                             </ows:Exception>
                         </ows:ExceptionReport>
                     </wsrf-bf:FaultCause>
                 </wsnt:SubscribeCreationFailedFault>
             </detail>
         </soap11:Fault>
     </soap11:Body>
 </soap11:Envelope>

A sample SOAP 1.2 example is as follows:

<soap12:Envelope 
     xmlns:soap12=”http://www.w3.org/2003/05/soap-envelope” 
     xmlns:wsa=”http://www.w3.org/2005/08/addressing” 
     xmlns:wsrf-bf=”http://docs.oasis-open.org/wsrf/bf-2” 
     xmlns:wsrf-r=”http://docs.oasis-open.org/wsrf/r-2”
     xmlns:wsnt=”http://docs.oasis-open.org/wsn/b-2”
     xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” 
     xsi:schemaLocation=”http://schemas.xmlsoap.org/soap/envelope/  http://schemas.xmlsoap.org/soap/envelope/
     http://www.opengis.net/pubsub/1.0 http://schemas.opengis.net/pubsub/1.0.0/pubsubAll.xsd
     http://www.w3.org/2003/05/soap-envelope http://www.w3.org/2003/05/soap-envelope
     http://docs.oasis-open.org/wsrf/r-2 http://docs.oasis-open.org/wsrf/r-2.xsd
     http://docs.oasis-open.org/wsn/b-2 http://docs.oasis-open.org/wsn/b-2.xsd”> 
     <soap12:Header> 
         <wsa:Action>http://docs.oasis-open.org/wsn/fault</wsa:Action> 
     </soap12:Header> 
     <soap12:Body>
         <soap12:Fault> 
             <soap12:Code> 
                 <soap12:Value>soap12:Sender</soap12:Value> 
             </soap12:Code> 
             <soap12:Reason> 
                 <soap12:Text xml:lang=”en”>The publication identifier ‘xyz’ is invalid</soap12:Text> 
             </soap12:Reason> 
             <soap12:Detail> 
               <wsnt:SubscribeCreationFailedFault>
                     <wsrf-bf:Timestamp>
                         2005-05-04T20:18:44.970Z
                     </wsrf-bf:Timestamp>
                     <wsrf-bf:Description>
                         The publication identifier ‘xyz’ is invalid
                     </wsrf-bf:Description>
                     <wsrf-bf:FaultCause>
                         <ows:ExceptionReport version=”1.0.0” xmlns:ows=”http://www.opengis.net/ows/1.1”>
                             <ows:Exception exceptionCode=”InvalidPublicationIdentifier” locator=”xyz”>
                                 <ows:ExceptionText>
                                     The publication identifier ‘xyz’ is invalid
                                 </ows:ExceptionText>
                             </ows:Exception>
                         </ows:ExceptionReport>
                     </wsrf-bf:FaultCause>
                 </wsnt:SubscribeCreationFailedFault>
             </soap12:Detail> 
         </soap12:Fault> 
     </soap12:Body> 
 </soap12:Envelope>  

9.    Requirements Class: SOAP Standalone Publisher extends SOAP Basic Publisher, Standalone Publisher

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

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.

Standalone SOAP Publishers expose two operations for Publish/Subscribe metadata: GetCapabilitiesand GetSubscription.  The GetCapabilitiesoperation is utilized directly from OWS Common Specification version 1.1 [OGC 06-121r3]. 

9.1    Exception and Fault Usage

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

Exception behavior for the GetSubscription operation is described in Table 6.

10.    Requirements Class: SOAP Pausable Publisher extends SOAP Basic Publisher, Pausable Publisher

This Requirements Class specifies the basic Publish/Subscribe operations of a Pausable Publisher using the SOAP protocol:

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.

These operations are implemented as the PauseSubscription and ResumeSubscription operations from the PausableSubscriptionManager interface described in [OASIS WS-BaseNotification].

11.    Requirements Class: SOAP Message Batching Publisher extends SOAP Basic Publisher, Message Batching Publisher

A SOAP Message Batching Publisher accepts pubsub:MessageBatchingCriteria information as part of the Subscribe operation as defined in the Publish/Subscribe 1.0 XML schemas.

12.    Requirements Class: SOAP Heartbeat Publisher extends SOAP Basic Publisher, Heartbeat Publisher

A SOAP Heartbeat Publisher accepts pubsub:HeartbeatCriteria information as part of the Subscribe operation, and publishes heartbeat messages as pubsub:Heartbeat messages as defined in the Publish/Subscribe 1.0 XML schemas.

13.    Requirements Class – SOAP Brokering Publisher extends SOAP Basic Publisher, Brokering Publisher

This Requirements Class specifies the basic Publish/Subscribe operations of a Brokering Publisher using the SOAP protocol.  The SOAP operations in this Requirements Class are implemented as operations from interfaces from [OASIS WS-BrokeredNotification]:

RegisterPublisher– allows the connection of an external Publisher to the Broker.  This is implemented as the RegisterPublisher operation from the NotificationBroker interface from [OASIS WS-BrokeredNotification]; and

RemovePublisher– allows the disconnection of a Publisher from the Broker.  This is implemented as the DestroyRegistration operation from the PublisherRegistrationManager interface from [OASIS WS-BrokeredNotification].

13.1    Exception and Fault Usage

For the RegisterPublisher, and RemovePublisher operations the following Fault and Exception codes are used.

14.    Requirements Class – SOAP Publication Manager extends SOAP Basic Publisher, Publication Manager

This Requirements Class specifies the operations of a Publication Manager using the SOAP protocol:

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.

14.1    Exception and Fault Usage

Exception behavior for the CreatePublication and RemovePublicationoperations is described in Table 8.

15.    Requirements Class – SOAP HTTP Delivery Publisher extends SOAP Basic Publisher

This Requirements Class specifies a method by which Publishers deliver messages using HTTP POST with SOAP/XML content.  Messages are delivered to a SOAP endpoint (SOAP Basic Receiver) using the Notify operation from the NotificationConsumer interface described in [OASIS WS-BaseNotification].

16.    Requirements Class – SOAP Reliable Publisher extends SOAP Basic Publisher

A SOAP Reliable Publisher is a type of Publisher that sends messages reliably using [OASIS WS-ReliableMessaging]. Basic Publishers only support a single attempted delivery of messages and do not specify behavior where messages are lost in transit.

Annex A
(Normative)

Abstract Test Suites

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 SOAP Basic Receiver (section A.1) or SOAP Basic Publisher (section A.2)

A.1      Conformance class: SOAP Basic Receiver

Test: /conf/soap/basic-receiver/notify

A.2      Conformance class: SOAP Basic Publisher

Test: /conf/soap/basic-publisher/envelope-body

Test: /conf/soap/basic-publisher/getcapabilities-service-metadata

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

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

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

Test: /conf/soap/basic-publisher/subscribe/dialect-set

Test: /conf/soap/basic-publisher/subscribe/dialect-valid

Test: /conf/soap/basic-publisher/subscribe/publication-id

Test: /conf/soap/basic-publisher/renew-nil-termination-time

Test: /conf/soap/basic-publisher/unsubscribe/publication-id

Test: /conf/soap/basic-publisher/fault-issuance

Test: /conf/soap/basic-publisher/fault-detail

A.3      Conformance class: SOAP Standalone Publisher

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

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

A.4      Conformance class: SOAP Pausable Publisher

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

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

A.5      Conformance class: SOAP Message Batching Publisher

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

A.6      Conformance class: SOAP Heartbeat Publisher

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

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

A.7      Conformance class: SOAP Brokering Publisher

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

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

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

Test: /conf/soap/brokering-publisher/fault-issuance

A.8      Conformance class: SOAP Publication Manager

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

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

A.9      Conformance class: SOAP HTTP Delivery Publisher

Test: /conf/soap/http-delivery/notify

Test: /conf/soap/http-delivery/post

Test: /conf/soap/http-delivery/action-header

A.10   Conformance class: SOAP Reliable Publisher

Annex B Revision history

[1] www.opengeospatial.org/cite