Pubscribe Developer Guide

The Developer Guide provides instructions for using many of the features that are included in Pubscribe. If you are new to this project, you should start with the Getting Started and the Tutorial before reading this guide. They provide a good starting point for learning how to use Pubscribe.

The Developer guide often refers to different parts of the Web Services Notifications (WSN) specifications that are defined by the OASIS standards body. You should become familiar with these specifications and refer to them as needed.

The Developer Guide guide often refers to Apache WSRF, Apache Axis, Apache Tomcat, Apache Ant, and Apache XMLBeans. Instructions for these packages are included as required and are not meant to replace the formal documentation for these projects. Consult them as necessary.

Pubscribe is an implementation of the WSN family of specifications that are defined by the OASIS standards body. The specifications describe how to expose the publish/subscribe pattern using Web services in a way that is scalable from simple devices to enterprise messaging systems. The specifications include:

• WS-BaseNotification - Defines the participants and messages needed to support basic notifications. A notification consumer can subscribe to one or more notifications that are supported by a notification producer. When a notification is published to a producer, the producer sends SOAP notification messages to all consumers who are currently subscribed for that particular notification. There is also optional support for enterprise scale messaging.
• WS-Topics - Defines how a hierarchy of notification topics can be described and how XPath-like topic expressions can be used to reference one or more topics in the topic hierarchy.
• WS-BrokeredNotification - Defines how a simple resource can offload the responsibilities of managing subscriptions to another entity called a broker. Having a broker aggregate messages from many resources also enables the ability to provide different notification channels through the use of topics.

Pubscribe builds on top of Apache WSRF and provides three deliverables:

• APIs for WSN topic spaces, subscriptions, etc...
• Implementations of the operations defined by the WS-BaseNotification specification
• A SubscriptionManager service that exposes WS-Resources that represent subscriptions
  Note

  APIs and operation implementations are not currently provided for the WS-BrokeredNotification specification.

Notification Producer

A resource that acts as a notification producer implements the WSN NotificationProducer portType. The resource has a TopicSet object associated with it. This topic set represents the set of topics to which the resource may publish notifications and to which consumers may subscribe. As the service developer of the producer resource, you are responsible for adding the topics you wish to support to the topic set using Pubscribe APIs.

When a Subscribe request is received, subscribe creates a new Subscription Resource which is exposed via the built-in SubscriptionManager service. The Subscription Resource provides operations which allow clients to cancel, pause, or resume the associated subscription. To publish a notification to a topic, you must call the publish method on the Topic object, passing it a DOM Node or XMLBeans XmlObject that represents the XML message to be published. Pubscribe will then take care of wrapping the message in a SOAP envelope and sending it to all consumers who are subscribed to the associated Topic.

Notification Consumer

A resource that acts as a notification consumer implements the NotificationConsumer portType. This portType includes only one operation - Notify. Producers invoke the Notify operation when they send notifications to the consumer resource. In addition to the actual notification message, the Notify operation also includes the topic expression to which the message was published and the EPR of the producer resource that generated the message. These additional components allow the consumer to correlate the message with a particular subscription.

Topic expressions are XPath-like expressions that refer to one or more topics. The Subscribe operation includes a topic expression that specifies which topic(s) the client would like to subscribe to. The WS-Topics specification defines three topic expression dialects of varying complexity - Simple, Concrete, and Full. Pubscribe includes full support for all three dialects, which means that any producer Resources you expose via Pubscribe can advertise to clients support for all three dialects.

A set of tools and integrations are provided that facilitate developing WSRF/WSN-compliant Web services. They are provided to help developers focus on defining their WS Resource and Notification Topics without having to deal with low-level implementation details.

The tools and integrations include:

• A WSRF/WSN WSDL template for writing WSRF/WSN-compliant WSDLs
• A Wsdl2Java tool for generating Java Classes from a WSDL.
• An integration with Apache XMLBeans for generating custom types defined in the WSDL
• an integration with Apache Axis for automatically deploying WS Resources