Adding power and flexibility to the WebSphere Service Registry and Repository subscription and notification framework

You can subscribe to objects in WebSphere Service Registry and Repository (WSRR) and be notified when these objects change. WSRR releases have added power and flexibility to the subscription and notification framework, both in the scope of objects you can subscribe to, and the ways in which you can be notified. This article describes the subscription and notification framework and shows you how to use the new capabilities in WSRR V7.5 and V8.0.

Share:

Mandy de Belin (debelin@uk.ibm.com), Information Developer, WebSphere Service Registry and Repository, IBM

Photo of Mandy de BelinMandy de Belin is an Information Developer on the WebSphere Service Registry and Repository team at the IBM Software Lab in Hursley, United Kingdom. You can contact Mandy at debelin@uk.ibm.com.



Stephen Rea (stephen_rea@uk.ibm.com), Software Engineer, WebSphere Service Registry and Repository Development team, IBM

Photo of Stephen ReaStephen Rea is a Software Engineer on the WebSphere Service Registry and Repository team at the IBM Software Lab in Hursley, United Kingdom. His development expertise includes modeling, messaging, parsing, and consumability. Since joining the Lab as an experienced hire in 1999, Stephen has worked on numerous Websphere products, including WebSphere MQ, WebSphere Message Broker and WebSphere Service Registry and Repository. You can contact Stephen at stephen_rea@uk.ibm.com.



15 May 2013

Introduction

This article starts with an overview of the IBM® WebSphere® Service Registry and Repository (hereafter referred to as WSRR) subscription and notification framework. An historical account of the notifier plug-in and notification service in WSRR will help you better understand the enhancements available in WSRR V7.5 and V8.0.

WSRR plug-in framework

The plug-in framework was part of the first release of WSRR, V6. A plug-in is a Java class that supports one of several possible interfaces, depending on its type. Using the plug-in framework, WSRR automatically calls code in plug-in classes during standard processing. The plug-in framework was enhanced over subsequent WSRR releases to enable users to write their own Java plug-ins. These plug-ins are invoked automatically at key points in standard processing of WSRR objects, enabling user code to either alter WSRR behavior or act on results. In V6, available plug-in types were "Validator" and "Notifier." These names reflect their likely usage: validators are invoked at the start of operations and therefore can validate or alter input data, while notifiers get invoked at the end of operations and so cannot alter anything, but can initiate actions based on what happened. Initially WSRR offered four plug-in interfaces, representing the plug-in function available in WSRR V6:

  • ServiceRegistryValidator
  • ServiceRegistryGovernanceValidator
  • ServiceRegistryNotifier
  • ServiceRegistryGovernanceNotifier

The ServiceRegistryValidator and ServiceRegistryNotifier interfaces support the basic Create, Update, and Delete (CUD) operations. The ServiceRegistryGovernanceValidator and ServiceRegistryGovernanceNotifier interfaces support some of the governance operations (initially just Transition and Validate). Later releases added more function to the governance support by adding new interfaces that extended the base ones above. The new interfaces are:

  • ServiceRegistryGovenanceValidator2
  • ServiceRegistryGovernanceNotifier2
  • ServiceRegistryGovernanceNotifier3

A release subsequent to WSRR V6.0 introduced the Modifier -- another plug-in point (type). Modifier code runs after an operation is complete but before it is fully committed, which enables you to alter (or force a failure for) a function, such as the shredding of WSDL that happens after the initial validator but before the final notifier. The introduction of the modifier plug-in type added two new interfaces:

  • ServiceRegistryModifier
  • ServiceRegistryGovernanceModifier

For further information about WSRR-provided plug-ins, see Configuring the WSRR provided plug-ins in the WSRR V8 information center. For information about creating custom plug-ins, see Configuring custom plug-ins in the WSRR V8 information center.

Notification service

An e-mail notification service to inform users when changes are applied to an object inside WSRR, was introduced in WSRR V6.0.2. Change processing was triggered at a scheduled interval, configured when the service was enabled. At each interval, the e-mail notification service connected to a durable subscription (created when the scheduled task for the service was configured), and retrieved all available messages that had been created by WSRR success events. The e-mail notification service subscribed to the internal JMS topic jms/SuccessTopic.

To enable e-mail notifications, it was necessary to create and store one or more Subscription objects in the WSRR content model. Any subscribers that had registered with the repository system through the creation of subscription objects, and whose criteria matched with any message change events, were sent an e-mail message notifying them of the change the message represented. The e-mail destination address was one of many properties defined in a Subscription object by a subscriber to such events, and in this case could be a list of e-mail addresses, rather than single destination point.

Enhancements to subscription and notification framework

The notification service was re-engineered and upgraded in WSRR V7.5, and further enhanced in WSRR V8.0. The new service still supports the automatic sending of notification messages when user operations take place on WSRR objects, but the following functional and architectural changes were introduced:

  • A subscription notifier offers greater extensibility to the existing notifications framework, providing greater built-in filtering control than available to either notifier plug-ins or the e-mail notification service. You can use a subscription notifier plug-in to send a notification message automatically when a user operation takes place in relation to a given set of matching WSRR objects, such as loading a WSDL document, or transitioning a business service to a new life cycle state. You can also specify conditions to filter the objects for which notification messages are sent -- for example, all version 1.0 entities that are classified as being in the "Created" state.
  • New subscription notifier plug-ins:
    • The e-mail notification service was migrated to this new extensible framework and is now represented in the form of a built-in e-mail subscription notifier plug-in, offering identical backward-compatible behaviour. As before, you still must consider the implications of the e-mail subscription notification plug-in being built on the notification framework. When a governance event is applied to an entity, you might receive multiple e-mails.
    • A second built-in notifier type was provided: The HTTP POST notifier, which offers an alternative mechanism through which subscribers can receive notification messages.
  • New subscription notifier plug-in interface, which you can use to define your own notifier types through which to interact with WSRR. A WSRR subscription notification plug-in is written as a Java class that implements the interface com.ibm.serviceregistry.ServiceRegistryNotifier.
  • You can now use the Representational State Transfer (REST) API to create a Subscription object. You can access the content of WSRR by using the REST distributed application architecture. This feature enables lightweight clients that do not have support for EJBs and web services to perform these tasks using HTTP requests.
  • An extended collection of supported Subscription object attributes, offering greater filtering and notification control. For example, the notifications framework has been updated to support various security features for notifications:
    • You can define a security token to pass with events posted by the HTTP Post notifier.
    • You can define a authentication alias for events posted by the HTTP Post notifier.
    • You can specify a secure destination URL for events posted by the HTTP Post notifier.

Architecture of notification service

The architecture of the new notification service is shown in Figure 1:

Figure 1. Architecture of notification service
Architecture of notification service

The default configuration profiles supplied with WSRR V7.5 contain a subscription notifier plug-in scheduler entry called SubscriptionNotifierPluginScheduler. This scheduler entry defines a subscription notifier plug-in scheduled task that is turned off by default. To use the subscription notifier plug-in framework, you must enable this scheduled task. When enabled, the task runs periodically to:

  • Check for changes to subscription objects in the WSRR content model, and confirm their validity (Step 1 in Figure 1). Subscribe to the internal change event topic jms/SubscriptionTopic.
  • Process all published SubscriptionTopic events and for each subscription that matches an event, such as create a new event (Step 2 in Figure 1.
  • Process each of the new events and attempt to notify the subscription endpoint tied to it, which could be an e-mail subscription notifier, an HTTP POST subscription notifier, or a custom user-defined notifier (Step 3 in Figure 1).

By default, the scheduled task runs every five minutes. The frequency is controlled by the scheduler entry property values:

  • intervalGranularity -- Units of time (default is minutes)
  • interval -- Number of units (default is 5)

Description of notification service

The subscription notifier plug-in scheduled task is of type Message, and is supported by the scheduler framework introduced in WSRR V6.1. For more information, see Scheduler framework in the WSRR V8 information center.

The scheduler framework is an EJB component that enables you to configure different types of scheduled tasks. The tasks are controlled by scheduler configuration XML files. For subscription notifications, this file is SubscriptionNotifierPluginScheduler. The processing of all messages can be performed in a single EJB transaction, or in the case of the subscription notifier plug-in, each message is processed in its own transaction. Tasks are defined in a Java class that is loaded into WSRR as a plug-in.

The subscription notifier plug-in Java class com.ibm.sr.subscriptionnotifier.plugin.SubscriptionNotifierPluginMessageTask is specified in the class element of the configuration file, and it implements the ServiceRegistryMessageTask interface, which is supplied in the ServiceRegistryClient.jar file. Message tasks are executed at the specified time interval by calling the implemented ServiceRegistryMessageTask interface methods preExecute(), execute(), and postExecute(), available on the Java class. These methods support the Steps 1, 2, and 3 respectively, in Figure 1.

When the subscription notifier plug-in scheduled task is run, it enters an initial set-up stage where activity is encapsulated within a call to the public method PreExecute() (Step 1 in Figure 1). During the PreExecute stage, the framework first refreshes an active subscription object cache, where the complete set of subscription objects present in the WSRR content model are validated. Subscription objects are deemed invalid or non-active if they have either expired, or if no plug-in notifier class exists (registered with the framework) for the notifier type specified in the subscription object's definition. The default notifier type is e-mail. This validation process can result in a reduced or empty subscription set. In the case of an empty set, all system change events are ignored by the framework.

The scheduled task next enters a change event processing stage. Activity is encapsulated within repeat calls to the public method execute() (Step 2 in Figure 1). During the execute stage, the framework reads and stores WSRR success (change) event messages from a new internal JMS topic jms/SubscriptionTopic. These messages are then processed in the final stage of the scheduled task via public method postExecute().

Before WSRR V7.5, the e-mail notification service subscribed to the internal JMS topic jms/SuccessTopic to gain access to WSRR success (change) events triggered by user (system) interaction. This topic is still supported for backward compatibility, but when the e-mail notification service was migrated to the new extensible framework in V7.5, it was converted into a subscription notifier plug-in. These notifiers rely on enhanced change events published to the new internal JMS topic jms/SubscriptionTopic.

To optimize matching performance, new success events containing additional information are published. For example, if the event represents a change to a logical object, then the event also needs to contain the bsrUri of its owning document, which was not previously available. Consider a document stored in the WSRR content model that is the target of a subscription. If it has an associated logical model, then the content of the document is parsed when loaded, and the appropriate logical model objects are created.

Take a WSDL document containing a portType: an instance of WSDLPortType will be created and associated with the new instance of WSDLDocument. That is, a WSDLPortType logical object will be created along with an association (backward reference) to the document representing the WSDL file that defined the portType. But the physical document will not have an association (forward reference) to this or any other logical object generated when it was loaded.

Therefore, with the WSDL document as the target for a subscription that has its object graph depth set to one (the depth logical objects can be considered to reside at in this case and for which you want notifications to be sent for), a graph query to this depth would not bring back this logical object due to the lack of a forward references to it. When targeting such a WSDL document via a subscription at depth one, the intention is to match not just on changes to the physical file, but also on changes to its unknown logical objects. Therefore, providing the bsrUri of the owning document up front in an event (used to identify owners of logical objects that might be the target object of a subscription) saves on the overhead of additional queries to run during postExecution() in the Scheduler.

The final processing stage of the scheduled task is encapsulated within a call to the public method postExecute() (Step 3 in Figure 1). Here, for each subscription object within the active subscription cache that matches an event published to the jms/SubscriptionTopic, a new internal event message is first created, tying an event to its matched subscription.

Several of these new events for each subscription match might also be created. A subscription specifies a notifier type to publish events through, but there may be multiple implementations of a given plug-in notifier type. The next stage in the postExecution() method involves processing each newly created internal event message where an attempt is made to notify the subscription endpoint associated with it. For example, a new internal event message might specify that notification should be provided through the built in HTTP POST notifier plug-in, using details that uniquely target a specific endpoint. The endpoint is described in the cached subscription object matched, and embedded in the new message event in question.

Messages are either processed separately or as a group, in which case their content is batched into a single notification message before delivery. Again, the subscription details embedded in the event messages dictate whether or not to send notifications to their target endpoint (destination) in batch mode. If set, multiple notifications are sent in a single message to optimize notification message flow.

Failure handling

The failure of a specific notifier plug-in to deliver its cargo to a specific destination causes a rollback of activity. Any previously read messages are preserved, to reattempt delivery the next time the scheduled task runs. This provides a quality of service whereby change event messages are either delivered or preserved for later delivery, but never consumed and lost. Event messages are permanently forgotten only following a commit after their successful delivery.

On failure, processing of further events continues, but all additional messages tied to the same failing destination are excluded. The exclusion criteria includes:

  • Notifier plugin Identifier
  • Endpoint reference (destination address)
  • Batch mode
  • Security token
  • SecurityAuthAlias (security authentication alias)

These subscription properties uniquely identify a specific notification mechanism and destination which, when combined together, are failing. For the given schedule interval concerned, excluded messages are preserved, but ignored for the remainder of the scheduled task's postExecute processing. Once the processing in postExecute is complete for the given schedule interval (all event messages that can be sent to their subscribers have been sent) the method and then the scheduled task are exited.

Support for named queries

The notification service added in WSRR V7.5 was extended further in WSRR V8.0 to include support for named queries. They were introduced in WSRR V7.0, but were not supported as legitimate targets of a notification subscription object. Unlike saved search query objects, which were supported in WSRR V6.3 onwards, named query objects are managed by administrators. They form part of the configuration profile, rather than content, and so cannot be the subject of a change in the content model. Such user-defined named queries are XML-defined configuration items, loaded into the configuration store, and manipulated by a user (administrator) through the WSRR Web UI. For more information, see Subscription object properties below, or see Subscription notifier in the WSRR V8.0 information center.

Subscription objects offer standard properties that are used to define a set of target objects (entities) in the content model. Notifications are sent following changes to these target objects. Typically, a subscription supplies either target object bsrURI, or object name, namespace, and version . Named queries do not form part of the content model and therefore do not have an associated bsrURI, and neither do they appear in any result set following a search of the content model.

Functional and architectural changes in WSRR V8.0

  • Support for notification subscription objects that target named queries: In a subscription definition, a named query can now be specified through the targetName property. Subscription definitions that target named queries are defined and operate in an identical manner to those that target saved searches, except that saved searches can be specified using the targetName or targetBsrURI property, and named queries can be specified using only the targetName. Either query type can be defined and can operate as a Graph or Property query.
  • Support for notification subscription objects that target named queries or saved searches that in turn expect parameters: Both of these querying mechanisms can be created to accept parameter values by adding positional parameters into their query expressions, and these act as insert locations in the expression for values provided by the caller. Parameter values are required to be passed to such queries, enabling their XPath expression to be fully resolved prior to their invocation. Subscription object definitions can now support such parameter passing.

The architecture changes introduced in WSRR V8.0 and made to the new notification service offered in V7.5 are shown below:

Figure 2. Architecture of notification service including named query enhancements
Architecture of notification service including named query enhancements

Description of named query support

The default profile for WSRR V8.0 continues to contain a subscription notifier plug-in scheduler entry called SubscriptionNotifierPluginScheduler. This scheduler entry defines a subscription notifier plug-in scheduled task that you must enable in order to use the subscription notifier plug-in framework. As previously described, when enabled, the task runs at a specified time interval, calling the implemented ServiceRegistryMessageTask interface methods preExecute(), execute(), and postExecute(), which support Steps 1, 2 and 3 respectively in Figure 2.

WSRR success/change (CUD) events, tied to named query configuration items that are managed in the configuration profile by an administrator, are now captured alongside standard change events driven from system interaction with the content model. The architecture changes in WSRR V8.0 that offer named query configuration items as targets for subscription objects required implementation changes only to the interface method postExecute().

The additional steps listed below were added to the standard processing already described for postExecute(). The additional steps come before those already supported in the postExecute() method, which is marked as Step 3 in Figure 2.

  • Persist all named query configuration item changes as notification events. The method first compares the latest in-memory cache of named query configuration items against an older cache, recorded the last time the scheduler ran. The comparison of these caches, representing the previous and current state of the configuration store in relation to named query definitions, produces an in-memory collection of CUD event types and their associated named query objects. Information maintained on each named query object referenced in the compared caches includes:
    • Type of query (Property or Graph)
    • Depth of query
    • User-defined properties tied to query object

    Any of this information might have been changed for an existing named query definition stored in the configuration profile. Such state changes are detected through a comparison of past and current cached state. Equally, a named query object might have been deleted or a new one created. For all such activity, new WSRR success (change) events are produced and collected in order to support subscribers or interested parties to such change events. To support the management of the previous (older) named query cache during WSRR restarts, the latest in-memory cache is persisted -- a copy is placed in the configuration store under the name NamedQueryList. The previous state of the named query cache is then hydrated from the configuration store as the first processing step in postExecute() to pick up changes since the scheduler last ran.

  • Loop over the in-memory collection of CUD event types, calculated in the processing step above. For each recorded named query configuration item change, create a WSRR success (change) event.

Following these new processing steps, standard processing (as described for postExecute earlier) resumes. As previously described, to fulfill Step 3 the postExecute() method produces, for each subscription object within the active subscription cache that matches a captured WSRR success (change) event, a new internal event message that ties an event to its matched subscription object. To match an active subscription to a captured WSRR success (change) event, postExecute calculates the current set (watch list) of target entities in the content model (and now named queries in the configuration profile) tied to the subscription.

For example, if a saved search or named query is targeted by a subscription via the targetName property, specified changes to such query objects are of interest to the subscription. Additionally, if the subscription object property _notifySavedSearchResultChanges is set to "true" (see Subscription object property extensions in V7.5 below), then the final set of target entities is the union of the existing set of target entities produced by the targetName property value (which could just be the query object itself), combined with the entire result set produced by running the query object found in the existing set of target entities.

To support the targeting of saved search and named query objects that expect parameters to fulfil their query expressions, the part of the Step 3 process to calculate the watch list for a subscription was upgraded in WSRR V8.0. The following processing logic was added to gather parameters tied to a query when property _notifySavedSearchResultChanges is set to "true":

  • Strip out and capture any parameters provided in the subscription's targetName or targetBsrURI property values.
  • For any target objects of the subscription that represent a saved search query object in the content model, store the captured parameters with each.
  • If the subscription's targetName property has a value, then check if the target name matches a named query. If so, the subscription has a named query as part of its list of target objects to watch, so retrieve the query object tied to the named query in the named query configuration cache, and add it to the subscription's target watch list (again along with its captured parameters if provided).

Subscription objects

Systems that store complex objects and associated metadata in repositories commonly enable clients to subscribe to events. These events are related to changes or operations applied to these objects following system interaction with the repository. Specifically, the content of an object or its metadata might have been created, deleted, transitioned, or updated in some way. In WSRR, the effect on its content model following such system interaction can be monitored by clients through registering (creating) one or more subscription objects, a subclass of OriginalObject in the Registry content model. A Subscription object itself forms part of, and is stored in, the WSRR content model, so it too can be subscribed to for changes of interest.

To enable event notifications through the WSRR subscription notification service, you must create and store at least one subscription object in the WSRR content model. Here are the purposes of a subscription object:

  • To describe, through a collection of filtering attributes, criteria that will be used to match the subscription to target entities within the content model. Based on the filtering information provided, the target set could be a collection of top-level target objects, or their descendants if a match depth greater than zero is specified for the subscription. Not all target objects present in the content model have relationships to further content in the model, and such objects therefore add themselves to the target set regardless of the depth value specified.
  • For all target entities in the match set, the subscription further filters by expressing a set of change events for which the subscriber wishes to be notified. Any change events not subscribed to for these target entities are ignored, and no notification is performed by the subscription notification service. Change events filtered on can include specific lifecycle transitions.
  • When a change event match occurs, the subscription object describes how the subscription notification service should contact the subscriber. It describes both the mechanism to use to send event notification messages, and the destination to which messages are sent. It specifies a notifier type (such as e-mail), and the destination (such as e-mail address) by using the provided endpoint reference subscription attribute.

A top-level target object can be any of the following types supported in the WSRR content model:

Base object

  • Logical model objects. For example:
    • WSDLPortType (LogicalObject type, built by shredding a loaded WSDL document).
    • Service model objects. WSRR manages these services by representing them in its content model as a WSDLService type and associating metadata with them that describes the role of the service in the SOA environment, together with its relationship to other artifacts on which it depends.
  • OriginalObject (Any object a user creates, such as a Document, QueryObject, or GenericObject). For example:
    • Documents (Physical artifacts such as WSDL files are represented by instances of subtypes of Document, specifically WSDLDocument.).
    • Generic objects (The GenericObject interface is used to represent any concepts that do not have a physical artifact.).
    • SCAModule.
    • Subscription.
    • QueryObject (the root interface of the various types of query that Registry supports. For example, ProperyQuery and GraphQuery.

User-defined metadata (properties, relationships, and classifications)

  • UserDefinedProperty
  • UserDefinedRelationship

Subscription object properties

Subscription objects were introduced into the Registry content model in WSRR V6.0.2, at the same time as, and in support of, the e-mail notification service. For a list and explanation of all of the original properties associated to this object at the time, see Subscriptions in the WSRR V7.0 information center:

To filter the events they require, users subscribe to certain events on certain types of artifacts by using subscription objects and the subscription notification service. Their subscription objects provide properties that are used to filter or target specific content model objects or target entities in WSRR, thus producing a set of objects of interest. They also provide properties that are used to target a range of change events published by WSRR, following activity caused by system interaction with WSRR. A notification occurs if a match is made for a subscription, where a matching event is associated with an entity in the content model, and that entity is also part of the subscription's calculated set of objects of interest (target entities).

The following standard properties are used to produce the set of target entities:

  • targetName: Object name for which notifications are required. Notifications are generated only for objects with this name.
  • targetNamespace: Object namespace for which notifications are required. Notifications are generated only for objects with this namespace value. A namespace is a container within the scope of which uniquely defined (named) items exist. A namespace cannot contain two items with the same name. For example, in programming languages, package names are used to address unique identifier requirements. In an XML document, namespaces are used to address identically named elements or attributes.
  • targetVersion: Object version for which notifications are required. Notifications are generated only for objects with this version value.
  • targetBsrURI: bsrURI of the root object of the governed collection for which notifications are required.
  • targetClassifications: A list containing possible object classification URIs.

If a property value is provided in the subscription for the targetBsrUri field, then the targetName, targetNamespace and targetVersion fields are not used to produce the set of target entities. They therefore are not used when attempting to match the subscription against a notified event. If a value for the targetBsrUri field is not provided, then the targetName, targetNamespace, and targetVersion fields are combined using logical ANDs to form the matching criteria on which to query the WSRR content model to produce the set of target entities.

If one or more URIs are provided for the targetClassifications property, then the set of target entities produced by the previous properties is potentially reduced. The property is used to ensure that each object in the set is also classified with either a classification URI specified explicitly in the list, or a classification URI derived from a parent classification specified in the list. That is, each object in the set of target entities that does not meet this final match criteria will be removed from the set.

The following standard properties are used to target a range of change events published by the notification framework:

  • subscribedOperations: A list containing the object operation names for which notifications are required. If no operations are specified, the subscription is assumed to apply to all operations. A subscriber can subscribe to any or all of the following operations: create, update, delete, transition, validate, make_governable, and remove_governance.
  • subscribedTransitions: A list containing the classification URIs for the life cycle transitions for which notifications are required. If no transitions are specified, and the transition operation is subscribed to via the previous subscribedOperations property, then the subscription is assumed to apply to all transitions.

Therefore a notification for a given subscription is made only if an event occurs that matches one of its subscribed operations, and for the transition operation, one of its subscribed transitions. The event must also be associated with an object that is within the calculated set of target entities.

Subscription object property extensions in WSRR V7.5

Subscription objects were enhanced in WSRR V7.5, extending the set of available properties in support of the subscription notification service, which was also introduced in this release. For a complete list and explanation of all the properties now associated to this object, see Body of a subscription creation message in the REST API in the WSRR V7.5 information center.

The following additional properties are now available to complement the standard properties described above:

  • _targetQuery: An XPath query expression run against the repository content model in the form of a GraphQuery to a specified depth (see _referencedObjectMatchDepth). If supplied in addition to the previously described standard properties, then the final set is the intersection of the result set of objects produced by this graph query with the existing set of target entities produced by the standard property values. This could potentially reduce the original set. If none of the standard properties were used, and so no set of target entities exists, then the final set of target entities is the entire result set returned from the query.
  • _referencedObjectMatchDepth: The object graph depth that you want to include in your resulting set of target entities. For example, If you supply a non-zero value for this property, the set of objects returned is not only the top level objects identified by the specified expression, but also any other objects referenced from these target objects, to the specified graph depth. If you supply a negative value for this property, the set contains the entire referenced graph. The default value is zero, that is, only return the top level objects matching the expression.
  • _notifySavedSearchResultChanges: If you set the value of this property to "true", and if it is supplied in addition to previously described properties (standard or extensions), then the final set is the union of the existing set of target entities produced by the standard/extension property values, combined with the entire result sets produced by running any query objects found in the existing set of target entities. This could potentially increase the original set. Duplicate objects are removed from the final set based on the union. The query objects are objects of type QueryObject and represent Saved Searches, pre-defined in the content model.

The following additional properties, which are not supported for the e-mail notifier type, are now available to complement the standard properties, and are used to target a range of change events published by the notification framework:

  • _notifyPolicyUpdates: If the value of this property is set to "true", a notification for a given subscription is made only if:
    1. An event occurs that matches one of its subscribed operations/transitions and
    2. The event is associated with an object that is within the calculated set of target entities or
    3. The event is associated with a policy that is attached to an object within the calculated set of target entities.
  • _notifyMonitoringPolicyUpdates: If the value of this property is set to "true", a notification for a given subscription is made only if:
    1. An event occurs that matches one of its subscribed operations/transitions and
    2. The event is associated with an object that is within the calculated set of target entities or
    3. The event is associated with a policy that is attached to a service level agreement (SLA), applied to a WSDL document that is within the calculated set of target entities.

Additional miscellaneous properties

  • _notifierType: The mechanism to be used to send event notification messages, for events matching this subscription. The property value for this field can have any of the following values:
    • email: Messages are sent to a specified e-mail address or addresses (default value).
    • httpost: Messages are sent to a specified URL.
    • Any other string of your choice: You write your own Java class to process the events.
  • _endPointReference: Target endpoint (destination) to which you want to send notifications of events matching this subscription. The property value for this field can have any of the following values:
    • If _notifierType is "email", set the _endPointReference property to the destination e-mail address.
    • If _notifierType is "httppost", set the _endPointReference property to the destination URL. You can specify a secure destination URL, which will cause the HTTP Post notifier to create a Secure Sockets Layer (SSL) connection through which to post the event.
    • If _notifierType is "custom", set the _endPointReference property to your custom target endpoint.
  • _endPointSecurityToken: A security token that is passed in events posted by the HTTP Post notifier. It is not used by the e-mail notifier. You can define a string value to associate with the subscription object that you are creating. It is used by consumers of a posted event to confirm that the posted message is authentic and sent by WSRR. A consumer can use the bsrURI of the subscription object, which is posted with the event, to look up the expected security token for that subscription and confirm that it matches the posted token.
  • _endPointSecurityAuthAlias: Specifies an existing WebSphere Application Server authentication alias configured on the WSRR server. The presence of an alias causes the HTTP Post notifier to post messages with an HTTP Basic Authorization header. The HTTP notifier accesses the user ID and password that the alias represents, and then base64 encodes a string representing the authentication details in the form userID:password. The encoded authentication string is included in the Basic Authorization header. This property is not used by the e-mail notifier.
  • _correlationID: Can be any unique string of your choice, which is sent in the event notification messages resulting from a match on this subscription. This value is used to correlate the messages generated from this subscription.
  • _enableBatchNotification: If the value of this property field is set to "true", the notifier for this subscription object is instructed to send notifications to the target endpoint in batch mode. This means that multiple notifications are sent in a single message to optimize notification message flow.
  • _duration: Specifies an expiry interval, in days, for the subscription. After the interval, the subscription object is deleted automatically. The interval is measured from the time the subscription object is created, or from when it was last modified. Therefore, any modification to a subscription object causes the start time of the expiry interval to be reset. If the numeric interval value ends with a lower-case "s", then the interval represents seconds rather than days.

Subscription object property extensions in WSRR V8.0

Subscription objects were enhanced in WSRR V8.0, extending the set of values that can be given to the standard properties targetName and targetBsrURI. Additionally, the existing subscription notification object property _notifySavedSearchResultChanges now also applies to any named query objects found in a subscription's set of target objects.

In subscriptions, a named query can be specified only in the targetName property. A saved search query can be specified in either the targetName or targetBsrURI property. In addition to being identified via the query's name and, in the case of a saved search, its bsrURI, both fields can also accept parameter values to be passed into the query, thus completing such queries by providing their expected insert values.

For the targetName property, the new syntax is:

name ?p1=param_1&p2=param_2...

Where name is the name of a saved search or named query, and param_1, param_2, and so on are the values to be inserted into the query's expression. The parameter number matches its corresponding insert position, that is, %1, %2, and so on. For example, the value (param_2) associated to parameter two (p2) is substituted for all occurrences of insert two (%2) in the expression. You can specify multiple parameters, delimited by the ampersand character (&). Parameters and their values can be provided in any order.

For the targetBsrURI property, the new syntax is similar:

bsrURI ?p1=param_1&p2=param_2...

Where bsrURI is the registry-provided uniform resource identifier of a saved search query object in the repository content model. For example, in the targetBsrURI property value:

2f11722f-8bf3-4348.a2d6.42b65242d6bb?p1=basic.wsdl&p2=test

the bsrURI identifies a saved search query. The saved search object could have the following query expression:

/WSRR/WSDLDocument[@name='%1' and @description='%2']

The query returns only those WSDL document objects whose names match basic.wsdl and whose descriptions match test. For a complete list and explanation of all the properties now associated with this object, see Body of a subscription creation message in the REST API in the WSRR V8.0 information center.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=929285
ArticleTitle=Adding power and flexibility to the WebSphere Service Registry and Repository subscription and notification framework
publish-date=05152013