Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.muse.ws.notification
Interface NotificationProducer

All Superinterfaces:
  Capability, Initialization, InitializationParameters, Shutdown, WsResourceCapability, org.apache.muse.ws.resource.WsResourceCapabilityProperties

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(java.lang.String namespace)` Creates a topic namespace in the resource's topic set using the given URI.
`NotificationMessage` | `getCurrentMessage(QName topicPath)` Retrieves the last message published for a given topic.
`boolean` | `getFixedTopicSet()`
`Topic` | `getTopic(QName topicName)`
`QName[]` | `getTopicExpression()`
`java.lang.String[]` | `getTopicExpressionDialect()`
`TopicNamespace` | `getTopicNamespace(java.lang.String namespace)`
`TopicSet` | `getTopicSet()`
`boolean` | `hasTopic(QName topicName)`
`void` | `publish(QName topicName, org.w3c.dom.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, org.w3c.dom.Element[] content)`
`void` | `publish(QName topicName, QName[] contentName, java.lang.Object[] content)`
`void` | `publish(QName topicName, QName contentName, java.lang.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, java.util.Date terminationTime, Policy policy)` Registers a consumer resource to receive events that are published to a certain topic (along with other filtering rules).

Methods inherited from interface org.apache.muse.ws.resource.WsResourceCapability
`deleteProperty, getProperty, getPropertyNames, getWsResource, insertProperty, updateProperty`

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

    public static final QName[] PROPERTIES

Method Detail

### addSubscription

    public 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

    public 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

    public TopicNamespace addTopicNamespace(java.lang.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

    public 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

    public boolean getFixedTopicSet()
                             throws BaseFault

  Returns:
    True if the resource's topic set cannot be modified after it has been initialized.
  Throws:
    `BaseFault`

### getTopic

    public Topic getTopic(QName topicName)

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

### getTopicExpression

    public QName[] getTopicExpression()
                               throws BaseFault

  Returns:
    The names of all of the topic that are supported by this resource.
  Throws:
    `BaseFault`

### getTopicExpressionDialect

    public java.lang.String[] getTopicExpressionDialect()
                                                 throws BaseFault

  Returns:
    All of the topic expression dialects that are supported by this resource.
  Throws:
    `BaseFault`

### getTopicNamespace

    public TopicNamespace getTopicNamespace(java.lang.String namespace)

  Parameters:
    `namespace` -
  Returns:
    The TopicNamespace representing the given URI, or null if no such TopicNamespace exists.

### getTopicSet

    public TopicSet getTopicSet()

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

### hasTopic

    public boolean hasTopic(QName topicName)

  Parameters:
    `topicName` -
  Returns:
    True if the resource supports the given topic.

### publish

    public void publish(QName topicName,
                        org.w3c.dom.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

    public void publish(QName topicName,
                        org.w3c.dom.Element[] content)
                 throws SoapFault

  Throws:
    `SoapFault`

### publish

    public 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

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

  Throws:
    `SoapFault`

### publish

    public void publish(QName topicName,
                        QName contentName,
                        java.lang.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

    public void publish(QName topicName,
                        QName[] contentName,
                        java.lang.Object[] content)
                 throws SoapFault

  Throws:
    `SoapFault`

### removeSubscription

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

### subscribe

    public WsResource subscribe(EndpointReference consumer,
                                Filter filter,
                                java.util.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`

Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD