org.apache.muse.ws.notification
Interface NotificationProducer

All Superinterfaces:
Capability, Initialization, InitializationParameters, Shutdown, WsResourceCapability
All Known Implementing Classes:
SimpleNotificationProducer

public interface NotificationProducer
extends WsResourceCapability

NotificationProducer is an interface that represents the WS-Notification NotificationProducer port type; it is based on WS-N 1.3. It provides support for the NotificationProducer properties (all topic-related) as well as its two operations: GetCurrentMessage and Subscribe. It also has methods for managing the resource's topic set using Muse's Topic API.

Perhaps the most significant API for users of WS-N is the publish() method; this method allows users to send message content to subscribers without having to know anything about the maintenance of subscriptions and how to determine which messages are sent to which subscribers. The publish() method allows user code to focus on generating event content and then let the WS-N implementation determine how and where to put it on the wire.

Author:
Dan Jemiolo (danj)

Field Summary
static QName[] PROPERTIES
           
 
Method Summary
 void addSubscription(WsResource subscription)
          This method is for internal (service-side) code that wishes to add a subscription that has already been created (perhaps from data residing in a persistent data store) and does not require a call to subscribe().
 Topic addTopic(QName topicName)
          Creates a topic in the resource's topic set and adds it to the appropriate topic namespace.
 TopicNamespace addTopicNamespace(String namespace)
          Creates a topic namespace in the resource's topic set using the given URI.
 void deleteProperty(QName property)
           
 NotificationMessage getCurrentMessage(QName topicPath)
          Retrieves the last message published for a given topic.
 boolean getFixedTopicSet()
           
 Element[] getProperty(QName property)
           
 QName[] getPropertyNames()
          Concrete capability classes that define properties MUST override this method and provide the names of the properties.
 Topic getTopic(QName topicName)
           
 QName[] getTopicExpression()
           
 String[] getTopicExpressionDialect()
           
 TopicNamespace getTopicNamespace(String namespace)
           
 TopicSet getTopicSet()
           
 boolean hasTopic(QName topicName)
           
 void insertProperty(QName property, Element[] values)
           
 void publish(QName topicName, Element content)
          Creates a WS-N notification message with the given topic and message content and sends it to the appropriate subscribers.
 void publish(QName topicName, Element[] content)
           
 void publish(QName topicName, QName[] contentName, Object[] content)
           
 void publish(QName topicName, QName contentName, Object content)
          This is a convenience method that calls publish(QName, Element) after the given content object has been serialized to XML using the Muse serializer framework.
 void publish(QName topicName, XmlSerializable content)
          This is a convenience method that calls publish(QName, Element) after the XmlSerializable object has been serialized to XML.
 void publish(QName topicName, XmlSerializable[] content)
           
 void removeSubscription(EndpointReference subscriptionEPR)
          This method is for internal (service-side) code that wishes to remove a subscription so that messages are no longer published to its subscriber.
 WsResource subscribe(EndpointReference consumer, Filter filter, Date terminationTime, Policy policy)
          Registers a consumer resource to receive events that are published to a certain topic (along with other filtering rules).
 void updateProperty(QName property, Element[] values)
           
 
Methods inherited from interface org.apache.muse.ws.resource.WsResourceCapability
getWsResource
 
Methods inherited from interface org.apache.muse.core.Capability
getActions, getCapabilityURI, getEnvironment, getLog, getMessageHandler, getPersistence, getResource, initializeCompleted, prepareShutdown, setCapabilityURI, setEnvironment, setLog, setMessageHandlers, setPersistence, setResource
 
Methods inherited from interface org.apache.muse.core.Initialization
hasBeenInitialized, initialize
 
Methods inherited from interface org.apache.muse.core.InitializationParameters
getInitializationParameter, getInitializationParameters, setInitializationParameters
 
Methods inherited from interface org.apache.muse.core.Shutdown
hasBeenShutdown, shutdown
 

Field Detail

PROPERTIES

static final QName[] PROPERTIES
Method Detail

addSubscription

void addSubscription(WsResource subscription)
This method is for internal (service-side) code that wishes to add a subscription that has already been created (perhaps from data residing in a persistent data store) and does not require a call to subscribe(). It should not be exposed to remote clients - the subscribe() method is already available for the purpose of remote subscription.

Parameters:
subscription -

addTopic

Topic addTopic(QName topicName)
               throws BaseFault
Creates a topic in the resource's topic set and adds it to the appropriate topic namespace. If the topic namespace does not exist, it is created.

Parameters:
topicName - The name of the topic, where the namespace matches the topic namespace the topic belongs to and the local part is a path that defines the topic's hierarchy (the path may also be a simple name, no slashes).
Returns:
The Topic that was created and added to the resource's topic set.
Throws:
BaseFault

addTopicNamespace

TopicNamespace addTopicNamespace(String namespace)
                                 throws BaseFault
Creates a topic namespace in the resource's topic set using the given URI.

Returns:
The TopicNamespace that was created and added to the resource's topic set.
Throws:
BaseFault

getCurrentMessage

NotificationMessage getCurrentMessage(QName topicPath)
                                      throws TopicExpressionDialectUnknownFault,
                                             InvalidTopicExpressionFault,
                                             TopicNotSupportedFault,
                                             MultipleTopicsSpecifiedFault,
                                             NoCurrentMessageOnTopicFault
Retrieves the last message published for a given topic.

NOTE:The term 'current' is only helpful if you think of the published messages being stored in a stack, with the last one on top. This is the 'current message'. In reality, implementations are not likely to store an in-memory copy of every message that is published, but it is a useful mental model.

Parameters:
topicPath - The name of the Topic whose last message you wish to retrieve.
Returns:
The last message that was published on the given topic.
Throws:
TopicExpressionDialectUnknownFault
InvalidTopicExpressionFault
TopicNotSupportedFault
MultipleTopicsSpecifiedFault
NoCurrentMessageOnTopicFault

getFixedTopicSet

boolean getFixedTopicSet()
                         throws BaseFault
Returns:
True if the resource's topic set cannot be modified after it has been initialized.
Throws:
BaseFault

getTopic

Topic getTopic(QName topicName)
Parameters:
topicName -
Returns:
The Topic with the given namespace and name, or null if no such Topic exists.

getTopicExpression

QName[] getTopicExpression()
                           throws BaseFault
Returns:
The names of all of the topic that are supported by this resource.
Throws:
BaseFault

getTopicExpressionDialect

String[] getTopicExpressionDialect()
                                   throws BaseFault
Returns:
All of the topic expression dialects that are supported by this resource.
Throws:
BaseFault

getTopicNamespace

TopicNamespace getTopicNamespace(String namespace)
Parameters:
namespace -
Returns:
The TopicNamespace representing the given URI, or null if no such TopicNamespace exists.

getTopicSet

TopicSet getTopicSet()
Returns:
The resource's entire topic set, which contains topic namespaces and (within those) topics.

hasTopic

boolean hasTopic(QName topicName)
Parameters:
topicName -
Returns:
True if the resource supports the given topic.

publish

void publish(QName topicName,
             Element content)
             throws SoapFault
Creates a WS-N notification message with the given topic and message content and sends it to the appropriate subscribers. The implementation will do all of the work of figuring out which subscribers should get the message based on its topic and/or content.

Parameters:
topicName - The WS-N topic associated with the message. This is optional (it can be null).
content - The XML fragment that will be put under the wsnt:Message section of the notification message. This is also called the 'payload'.
Throws:
SoapFault

publish

void publish(QName topicName,
             Element[] content)
             throws SoapFault
Throws:
SoapFault

publish

void publish(QName topicName,
             XmlSerializable content)
             throws SoapFault
This is a convenience method that calls publish(QName, Element) after the XmlSerializable object has been serialized to XML.

Throws:
SoapFault

publish

void publish(QName topicName,
             XmlSerializable[] content)
             throws SoapFault
Throws:
SoapFault

publish

void publish(QName topicName,
             QName contentName,
             Object content)
             throws SoapFault
This is a convenience method that calls publish(QName, Element) after the given content object has been serialized to XML using the Muse serializer framework.

Parameters:
topicName - The WS-N topic associated with the message. This is optional (it can be null).
contentName - The name of the root element of the payload. This will be passed to Serializer.toXML() when converting the content value to XML.
content - The value that will be converted to XML and then put under the wsnt:Message section of the notification message. This is also called the 'payload'.
Throws:
SoapFault

publish

void publish(QName topicName,
             QName[] contentName,
             Object[] content)
             throws SoapFault
Throws:
SoapFault

removeSubscription

void removeSubscription(EndpointReference subscriptionEPR)
This method is for internal (service-side) code that wishes to remove a subscription so that messages are no longer published to its subscriber. It should not be exposed to remote clients - the WS-RL capabilities can be added to the subscription resource type so that subscriptions can be removed remotely.

Parameters:
subscription -

subscribe

WsResource subscribe(EndpointReference consumer,
                     Filter filter,
                     Date terminationTime,
                     Policy policy)
                     throws InvalidFilterFault,
                            TopicExpressionDialectUnknownFault,
                            InvalidTopicExpressionFault,
                            TopicNotSupportedFault,
                            InvalidProducerPropertiesExpressionFault,
                            InvalidMessageContentExpressionFault,
                            UnacceptableInitialTerminationTimeFault,
                            UnrecognizedPolicyRequestFault,
                            UnsupportedPolicyRequestFault,
                            NotifyMessageNotSupportedFault,
                            SubscribeCreationFailedFault
Registers a consumer resource to receive events that are published to a certain topic (along with other filtering rules). Registration results in the creation of a subscription resource, which exposes the WS-N SubscriptionManager port type and can be managed as a regular WS-RF implied resource. Once subscription is complete, the event consumer will receive notifications on the topic until the subscription is terminated (via WS-RL) or the producer shuts down.

Parameters:
consumer - The EPR of the resource that will receive the notifications from the producing resource. This does not have to be the same component that is making the subscribe() request. An orchestrating service may be subscribing for the consumer.
filter - Optional filter that allows for messages to be published if they meet a certain criteria. Filter types include topic names, message patterns (XPath), and current state (WSRP doc).
policy - Optional filter that allows for more complex analysis on the conditions needed to send a message. The implementation must provide one or more policy languages (dialects) that clients can use to express how and when a message that is published to a topic should be sent. If this parameter is null, no policy is applied.
terminationTime - Because subscriptions are WS-resources, they may be terminated with scheduled termination (specifically, the WS-RL TerminationTime property). If this parameter is null, no termination time is set.
Returns:
The new subscription resource.
Throws:
InvalidFilterFault
TopicExpressionDialectUnknownFault
InvalidTopicExpressionFault
TopicNotSupportedFault
InvalidProducerPropertiesExpressionFault
InvalidMessageContentExpressionFault
UnacceptableInitialTerminationTimeFault
UnrecognizedPolicyRequestFault
UnsupportedPolicyRequestFault
NotifyMessageNotSupportedFault
SubscribeCreationFailedFault

deleteProperty

void deleteProperty(QName property)
                    throws BaseFault
Throws:
BaseFault

getProperty

Element[] getProperty(QName property)
                      throws BaseFault
Throws:
BaseFault

getPropertyNames

QName[] getPropertyNames()
Concrete capability classes that define properties MUST override this method and provide the names of the properties.

Returns:
The names of the resource properties defined by this capability.

insertProperty

void insertProperty(QName property,
                    Element[] values)
                    throws BaseFault
Throws:
BaseFault

updateProperty

void updateProperty(QName property,
                    Element[] values)
                    throws BaseFault
Throws:
BaseFault


Copyright © 2005-2011 Apache Web Services - Muse. All Rights Reserved.