apache > ws.apache

## Apache Muse - WS-BaseNotification - NotificationProducer Capability

Spec name and port type: WS-BaseNotification v1.3, NotificationProducer (WSDL)

Capability URI: http://docs.oasis-open.org/wsn/bw-2/NotificationProducer

Description: This capability implements the WSN publish-subscribe system so that resources can notify listeners as to events that have occurred. Through the Subscribe operation, clients can register to receive notifications about a subset (or all) of the events that happen to the resource. Subscribing to these notifications results in the creation of a Subscription WS-resource, the lifetime of which can be controlled by the requesting client. These subscriptions are managed by Muse's resource manager but are referenced by this capability in order to send out notifications to the right listeners at the right time.

One cannot add this capability without also deploying the SubscriptionManager resource type. More details are provided in Behavior and Limitations.

Java interface: org.apache.muse.ws.notification.NotificationProducer

> JAR file: muse-wsn-api.jar

Default Java implementation: org.apache.muse.ws.notification.impl.SimpleNotificationProducer

> JAR file: muse-wsn-impl.jar

Action on initialize(): Registers itself as a listener on ResourceManager change events (resource creation and destruction) so it can update its internal cache of subscription references as needed. Verifies that the SubcriptionManager resource type has been deployed. Initializes the resource's topic set from a file, if one exists.

Action on initializeCompleted(): Creates a topic for each resource property exposed by the resource type. If the type exposes either of the WSRL capabilities, the WSRL termination topic is also created.

Action on prepareShutdown(): None.

Action on shutdown(): None.

Non-Core Dependencies:

- http://docs.oasis-open.org/wsn/bw-2/SubscriptionManager
- http://docs.oasis-open.org/wsrf/rlw-2/ScheduledTermination
- The Abstract WSRF Capability

Behavior and Limitations: Calls to subscribe() result in the creation of a subscription resource; in the default implementation, these subscriptions are persisted as XML files on disk and will be reloaded if the application's container reboots. The type representing subscriptions is any resource type deployed with the WSN SubscriptionManager capability. If no such resource type is deployed, the capability will fail to initialize, because the type is necessary in order to represent subscriptions in a standards-compliant way.
This capability provides a publish() method that allows users to send payload content to subscribers without knowing anything about the internal subscription management data structures, how many subscribers there are, etc. Users provide an optional topic and the payload (content under wsnt:Message), and the capability will handle the packaging of the notification and pushing it out to the consumers. Messages without a topic will be published to subscribers whose subscription filter matches the message's XML content.
The default implementation of WSN NotificationProducer includes all three standard filter types. Use of the message pattern filter may hurt performance, as it requires an XPath evaluation on each message that is published. The resource property filters will vary in performance depending on how many properties are being checked at the time of the notification; these filters inherently involve dynamic (mutable) properties, so a cache of equality test results is not likely to help. Topic filters provide the best performance because they only require a simple equality check against the filter's topic name and the message's topic name; the trade-off with topic filters is that they require more work at design time.

Initialization parameters:

- topic-set - The relative path of an XML file containing the topic set that the resource type should publish. It does not have to include WSRP topics or WSRL topics, as these are added automatically.