Notification Producer

This section provides instructions for configuring notification topics for a notification producer resource. Each resource that is configured to be a notification producer (implements the WSN NotificationProducer portType) has an associated TopicSet object. The TopicSet respresents the set of topics to which the producer may send notifications. Notification consumers can subscribe to any of these topics to receive notifications from the producer whenever notifications are published to those topics. As the service developer of the notification producer resource, you are responsible for adding the topics you want to support to your topic set. Additionally, you must ensure all topics you add to your topic set are defined in a topic namespace in the topic namespace registry. A topic namespace defines a hierarchy of topics within a certain namespace.

The topic namespace registry is Pubscribe's global registry of of topic namespaces (aka topic spaces). A topic namespace defines a hierarchy of topics within a certain namespace. The WS-Topics specification defines an XML schema for a topic namespace. Here is an example of a TopicSpace document:

			
<TopicSpace name="TopicSpaceExample1"
  targetNamespace="http://example.org/topicSpace/example1"
  xmlns:tns="http://example.org/topicSpace/example1"
  xmlns:xyz="http://example.org/anotherNamespace"
  xmlns="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-Topics-1.2-draft-01.xsd">
  <Topic name="t1">
    <Topic name="t2" messageTypes="xyz:m1 tns:m2"/>
    <Topic name="t3" messageTypes="xyz:m3"/>
  </Topic>
  <Topic name="t4">
    <Topic name="t5" messageTypes="tns:m3"/>
    <Topic name="t6">
      <AliasRef dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Concrete">tns:t1/t3</AliasRef>
    </Topic>
  </Topic>
</TopicSpace>			

Specifications that define topics will usually define the associated TopicSpace XML document(s). For example the WSDM MUWS and MOWS specs both define a TopicSpace document that defines all of the topics they support. In the case of custom topics (i.e. topics that you define youself), you'll need to write your own TopicSpace document(s). The TopicNamespaceRegistry bean defintion in your wsrf-config.xml is where you should add entries for all specification-defined and custom topic namespaces. This bean definition looks as follows:

			
  <bean id="TopicNamespaceRegistry" class="org.apache.ws.notification.topics.TopicNamespaceRegistry">
    <constructor-arg>
      <set>
        <value>classpath:org/apache/ws/notification/topics/v2004_06/ResourceLifetime-TopicSpace.xml</value>
        <!-- value>classpath:your-custom-topicSpace.xml</value -->
      </set>
    </constructor-arg>
  </bean>

Notice the set of values that is passed to the constructor of the TopicNamespaceRegistry bean. Each of these values is the URL of a TopicSpace XML document. The URL may be either a file, http, or classpath URL. Classpath URLs are handy because they allow you to deploy your TopicSpace documents in the WEB-INF/lib or WEB-INF/classes directories in the Pubscribe webapp. For more information about topic namespaces, please refer to the WS-Topics specification.

Your topic set can either be initialized via the WSRF configuration file or programmatically via APIs. Using the configuration file is the recommended method, because you will be able to modify your topic set without recompiling code. In either case, each topic to be added to the topic set is specified via a topic expression.

Your wsrf-cofig.xml should contain a bean definition for your producer resource that looks something like the following:

  <bean id="YourProducerResource" class="org.example.YourProducerResource" singleton="false">
    <property name="topicSet">
      <bean class="org.apache.ws.notification.topics.impl.TopicSetImpl">
        <constructor-arg>
          <set>
            <bean class="org.apache.ws.notification.topics.expression.SimpleTopicExpression">
              <constructor-arg><value>{http://example.org/topics/}RootTopic</value></constructor-arg>
            </bean>
            <bean class="org.apache.ws.notification.topics.expression.ConcreteTopicExpression">
              <constructor-arg><value>{http://example.net/topics/}foo/SubTopic</value></constructor-arg>
            </bean>
          </set>
        </constructor-arg>
      </bean>
    </property>
  </bean>

The topicSet property is a bean which defines your producer's topic set. This bean's constructor takes a set of TopicExpression beans. You should add one TopicExpression bean to this set for each topic you want to add to your topic set. To specify a root topic, use the org.apache.ws.notification.topics.expression.SimpleTopicExpression class as shown above. To specify a subtopic, use the org.apache.ws.notification.topics.expression.ConcreteTopicExpression class as shown above. Both the SimpleTopicExpression and ConcreteTopicExpression classes have a constructor which takes a QName that specifies the "topic path". The QName is represented as a string using the syntax "{namespaceURI}localPart".

To add topic to your topic set programmatically, use the addTopicExpression method on your producer resource's TopicSet. For example:

  yourResource.getTopicSet().addTopicExpression( new SimpleTopicExpression( new QName( "http://example.org/topics/", "RootTopic" ) ) );

For a topic set that is defined as fixed, all topics should be added to the topic set either via the WSRF configuration file or in the resource's init method. However, for topic sets that are not fixed, it is acceptable to add new topics to the set during runtime. For more information about topic sets, please refer to the WS-BaseNotification and WS-Topics specifications.

As per the WS-ResourceProperties specification, resource property value change topics can be defined that correspond to specific mutable resource properties. Consumers can subscribe to these topics to be notified whenever the values of the associated properties change. The notification that is sent to consumers contains the new value of the property, and, optionally, its old value. The WSRP specification says that the topic path of property change topics must be identical to the QName of resource property with which it is associated. Apache WSRF will automatically recognize any property change topics in your topic set and register listeners on the corresponding properties to ensure notifications are published whenever the properties are externally changed (i.e. via a SetResourceProperties request). If you wish to publish property changed notifications when a property is internally changed, you will need to publish the notification yourself by invoking the publish method on your producer resource.

As per the WS-ResourceProperties specification, a resource termination topic can be defined for a resource. Consumers can subscribe to this topic to be notified when the resource instance is destroyed. The notification that is sent to consumers contains the time that the resource was destroyed and, optionally, the reason it was destroyed. The WSRP specification says that the topic path of the resource termination topic must be "{http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceLifetime-1.2-draft-01.xsd}ResourceTermination". If you add the resource termination topic to your topic set, Apache WSRF will automatically register a listener on your resource to ensure a notification is published when the resource is destroyed. If you wish to support the resource termination topic for one or more of your services, you must make sure the topic namespace that defines the topic (i.e. the WS-ResourceLifetime topic namespace) has been added to the topic namespace registry. To do so, make sure the location "classpath:org/apache/ws/notification/topics/v2004_06/ResourceLifetime-TopicSpace.xml" is included in the TopicNamespaceRegistry bean definition in your wsrf-config.xml.