kFunctional Specification

Community Grids Lab, Indiana University

 

THIS DOCUMENT IS BASED ON REVISION 0.3 OF THE FUNCTION SPECIFICATION TEMPLATE!

 

 

1.         Introduction

This software provides an implementation of the WS-Eventing specification that was released in August 2004. This specification -- developed jointly by Microsoft, BEA, IBM and Sun -- can be found at http://www-128.ibm.com/developerworks/webservices/library/specification/ws-eventing/. This particular specification provides abstractions for publish/subscribe interactions within the Web Services domain and the ability to route notifications to the registered entities. Please note that what we briefly describe in this section is a background and overview to the WS-Eventing specification. If one is looking for comprehensive details the best place is the specification. Any attempt to describe the spec in detail, will end up making this document similar to the specification: which would be pointless.

 

1.1         A background on notifications

There are two main entities involved in a notification: the source which is the generator of notifications and the sink which is interested in these notifications. A sink first needs to register its interest in a situation, this operation is generally referred to as a subscribe operation. The source first wraps occurrences into notification messages. Next, the source checks to see if the message satisfies the constraints specified in the previously registered subscriptions. If so, the source routes the message to the sink. This routing of the message from the source to the sink is referred to as a notification.

It should be noted that there could be multiple sources and sinks within the system. Furthermore, each sink could register its interests with multiple sources, while a given source can manage multiple sinks. The complexity of the subscriptions registered by a sink could vary from simple strings such as “Weather/Warnings” to complex XPath or SQL queries.

Typically a source comprises two distinct roles: producer and publisher. A producer is responsible for packing occurrences into notification messages, while the publisher is responsible for publishing these notifications. Similarly, a sink comprises two distinct roles: subscriber and consumer. The subscriber is responsible for registering the consumer’s interests with a source, while the consumer is responsible for consuming notifications received from a source.

Depending on the nature of the underlying frameworks the coupling between the sources and sinks can vary. In loosely-coupled systems a source need not be aware of the sinks: the source generates events and an intermediary, typically a messaging middleware, is responsible for routing the message to appropriate sinks. In tightly-coupled systems there is no intermediary between the source and the sink.

 

1.2         Brief Overview of WS-Eventing

Figure 1 depicts the chief components in WS-Eventing. When the sink subscribes with the source, the source includes information regarding the subscription manager in its response. Subsequent operations –- such as getting the status of, renewing and unsubscribing –- pertaining to previously registered subscriptions are all directed to the subscription manager. The source sends both notifications and a message signifying the end of registered subscriptions to the sink.

 

 

Figure 1: WS-Eventing - Chief components

 

This software provides an implementation of the WS-Eventing specification and provides support for all the abstractions that are part of this specification. The schemas that are relevant to this specification are enumerated below.

 

 

2.         Product Description

This software provides an implementation of the WS-Eventing specification. This specification abstracts exchanges between entities (consumers and producers) in the area of publish/subscribe systems. There are similar specifications in the J2EE environment viz. Java Message Service (JMS) and in the Web Services environment -- WS-Notification. The table below provides a comparison of WS-Eventing and WS-Notification.

 

Table 1: Comparison of WS-Notification and WS-Eventing

 

WS-Notification

WS-Eventing

Related Specifications

SOAP, WS-Addressing, WS-BaseNotification, WS-Brokered Notification, WS-Topics, WS-Resource Properties and WS-ResourceLifetime

SOAP, WS-Addressing

Support for loosely coupled notifications. (Producers need not know consumers)

Yes. The intermediary called Notification Broker and the exchanges that need to be supported are defined in the WS-Brokered Notification specification.

No.

Delivery modes supported

Push

Push

Batched, Pull, & Trap (udp) defined in WS-Management

Delegated Management of subscriptions

Yes. Through the subscription manager interface.

Yes. Through the subscription manager interface.

Support for replay like features

One can get last message to a topic. A sink can also retrieve message issued between the pausing and resumption of a subscription.

No. However WS-Management introduces notion of resume/pause subscriptions.

Subscription operations

Subscribe, Pause and Resume. (There is NO exchange to unsubscribe).

Subscribe, Renew, Unsubscribe and Subscription End.

Subscription termination notification

NO

Yes. There is a SubscriptionEnd notification that is sent out by the source to the sink anytime the subscription ends (either an unsubscribe or termination)

Support for filters on to narrow notifications

YES

YES

Subscription lifetimes

Defined using the WS-Resource Lifetime specification.

Contained within the Subscribe and Renew exchanges.

Notification filters and topic expressions supported

Topic Expressions supported: QName, “/” separated Strings, and XPath path expressions.

Filter supported is XPath.

Hierarchical topics and Wildcards support

Yes. Supports * and // wildcards for selection of topic descendants in a topic tree.

No.

Topic space management

Defined using WS-Topics. The topic space will also support exchanges as defined by the WS-ResourceProperties specification.

No formal recommendation regarding topic management.

Advertisement of supported topics

Yes. The NotificationProducer interface allows inspection of available topics.

No.

On demand publishing

YES. This is supported through the WS-Brokered Notification specification. This allows a publisher to publish ONLY if there is a consumer interested in receipt of notifications.

NA. A source always keeps information regarding the sinks, so on-demand publishing is the default mode.

Notification messages

Provides support for both a Notify message as well as “raw” application specific message,

Does not define any special Notification message type.

Retrieve information about Topics from producer

Yes. Also indicates if the set of topics is going to be dynamic.

NO.

Retrieve info about topic expression dialects

Yes.

NO

Suggested Security

WS-Security and assorted specifications.

WS-Security & assorted specifications.

 

WS-Eventing provides a framework for notification between 2 Web Service endpoints. All exchanges between communicating entities are encapsulated within SOAP messages. The WS-Eventing specification provides a platform-independent and language-independent framework for notifications. We are also in the process of implementing WS-Notification, which is a competing specification. In summary, this software provides a complete implementation of the WS-Eventing specification. Finally, to effectively use this software you should be familiar with Java and have some working knowledge of Web Serviuces.

 

 

3.         Use Cases

Publish/subscribe systems have been deployed in a wide-variety of application domains. This software can be deployed in settings where distributed entities need to be able to communicate with each other through the exchange of messages. Furthermore, entities will be able to register an interest in specific events/messages (through previously registered subscriptions) and have the system route these events as and when they occur.

 

The WS-Eventing specification delegates security related issues to the WS-Security specification, which facilitates message-level security. Nothing in the WS-Eventing specification or this implementation of the specification precludes the use of WS-Security. We fully expect this implementation to work with existing WS-Security implementations. The WS-Security specification provides the ability to securely (leveraging encryption, message digest and signing) route SOAP messages between endpoints irrespective of the underlying transport mechanism.

 

We will be using this implementation within the SERVO (Solid Earth Research Virtual Observatory) Grid http://www.servogrid.org/ project. The software is quite robust since it deals with ALL the exception/fault conditions outlined within the WS-Eventing specification.

This software will report faults (as outlined in the WS-Eventing specification) if there are malformed requests. We enumerate some of these below

  1. If the subscription identifier specified for subscription renewals is an incorrect one.
  2. If the time specified for subscription renewal is in the past. For example if the correct time is New Year’s Eve 2005, and the renewal request is for Christmas 2005, the request will fail and a fault reporting this problem will be thrown by the subscription manager.
  3. If the subscription identifier specified in the unsubscribe request (or the renewal request) is an unknown one, a fault will be reported by the subscription manager.
  4. If the Filter dialect specified in the subscription request is an invalid one the source will respond with a fault message outlining this problem.
  5. If the expiration time specified in the subscription request is an invalid one the source will respond with a fault message outlining this problem.

 

The WS-Eventing specification, and this implementation, concerns itself only with the delivery of messages (notifications) from the source to the sinks that had previously registered their interests. As far as we know nothing in this software precludes its use by researchers, system administrators or project managers. What has been provided here is the underlying middleware, applications can be easily developed which hide the innards of this specification/implementation from the end-users.

 

 

4.         Evaluation Metrics

We now include performance measurements from our experiments. These experiments were performed on a 3.5 GHz Pentium IV machine with Sun’s 1.4.2 Java Virtual Machine. For each measurement we performed the experiment 100 times. An outlier removal program was used to remove outliers, if any, in the result set. For each run we also tracked the memory utilization. This was done by simply recording the memory utilization prior to the invocation of a specific operation and after the invocation. In some cases this calculation resulted in a negative utilization because of garbage collection (via the Java garbage collector thread) in the intervening period.

 

In our benchmarking we sought to measure the overheads involved in the creation of various exchanges that are part of the WS-Eventing specification. We have also reported measurements related to the creation of XMLBeans based SOAP Envelopes (Figure 2) and the creation of WS-Addressing Endpoint References both with and without wsa:ReferenceProperties. These costs have been depicted in Figure 3.

 

Figure 2: Costs involved in creation of XMLBeans based SOAP Envelope

 

 

Figure 3: Creation of WS-Addressing Endpoint References

 

 

Figure 4 and Figure 5 depict the costs involved in the creation of WSE Subscription Requests and WSE Subscription responses respectively.

Figure 4: Creation of a WSE Subscription Request

 

Figure 5: Creation of WSE Subscription Response

 

 

 

Figure 6 and Figure 7 depict the costs involved in the creation of an Unsubscribe Request and the corresponding response associated with it.

Figure 6: Creation of  a WSE Unsubscribe request

 

 

Figure 7: Creation of a WSE Unsubscribe Response

 

 

Figure 8 and Figure 9 depict the cost associated with the creation of a WSE Subscription Renewal request and the corresponding response associated with it.

Figure 8: Creation of a WSE Renew Request

 

 

Figure 9: Creation of WSE Renew Response

 

Figure 10 and Figure 11 depict the costs associated with the creation of a WSE GetStatus Request and Response respectively.

Figure 10: Creation of a WSE GetStatus Request

 

Figure 11: Creation of a GetStatus Response

 

 

Figure 12 depicts the cost associated with a SubscriptionEnd message.

 

Figure 12: Creation of a WSE Subscription End message

 

 

Operation

Mean

Standard

Deviation

Standard

Error

Outliers

Min

Max

Memory Utilization (Bytes)

Create EnvelopeDocument

127.505

29.833

3.093

7

110

283

2192

Create SOAPMessage

85.150

64.851

6.724

7

34

488

1824

Create Epr

84.260

26.367

2.749

8

73

303

2072

Create EPR With

ReferenceProperties

131.065

36.396

3.815

9

112

358

2648

Create Epr Envelope

364.955

158.310

16.687

10

261

834

7184

Create Epr Envelope With Most Wsa Fields

491.263

204.220

21.408

9

347

1099

13880

Create Subscribe Request

1466.068

436.588

46.540

12

1059

2581

76360

Create Subscribe Response

352.545

48.714

5.193

12

315

533

21464

Create Unsubscribe Request

137.290

3.908

0.405

7

132

150

11728

Create Unsubscribe Response

137.804

4.185

0.436

8

133

158

11808

Create Renew Request

321.0

54.462

5.839

13

285

525

20536

Create Renew Response

294.066

63.293

6.671

10

249

472

18160

Create GetStatus Request

164.463

34.121

3.464

3

128

259

11728

Create GetStatus Response

279.088

60.820

6.411

10

241

489

18160

Create SubscriptionEnd

193.307

39.088

4.097

9

175

505

13008

 

 

 

5.         Functional Design Considerations

 

Assumptions that were made during functional design: The WS-Eventing specification leverages WS-Addressing and SOAP. These related technologies have a few schemas each corresponding to a different version of the aforementioned specifications. To be consistent with the javax.xml.soap.SOAPMessage format we used the SOAP schema specified at http://schemas.xmlsoap.org/soap/envelope/ . At the time the software was written (Dec  2004) we used the latest WS-Addressing schema that was available at that time -- http://schemas.xmlsoap.org/ws/2004/08/addressing. Here we note that a new version of the WS-Addressing schema released in March 2005 is now available.

 

Prerequisites for the correct working of the product: This software has been written in Java. For the correct working of this software one needs to use JDK 1.4 or higher.

 

Main decisions/reasons regarding functionality: This software is an implementation of the WS-Eventing specification. The decisions/reasons were driven by the considerations involved in the implementation of this specification. One of the major decisions was the choice of schema – we discussed this in the assumptions section. We also decided to support topic (“/” separated Strings) and regular-expressions based subscriptions in addition to the XPath format mandated by the WS-Eventing specification. The rationale for this was that there might be users used to JMS who would prefer the overall simplicity of topic based subscriptions.

 

 

Scale of deployment: The three major components have been deployed within the OMII Containers (both 1.2 and the recently released 2.0 specification). The source, sink, and subscription manager have all been tested in various distributed settings (all in the same machine, 2 in the same machine and 1 on another, and finally all components in different machines).

 

 

Resource requirements in terms of hardware, data volume, other software or equipment:  All you need is a machine that has a JVM for it. For the correct working of this software one needs to use JDK 1.4 or higher.

 

 

Portability: This software is written in Java. So, this will work on any machine/operating-system that has a Java Virtual Machine for it. As mentioned previously one needs to use JDK 1.4 or higher.

 

 

Reliability/Maintainability/Availability: The WS-Eventing specification does not deal with reliable messaging.  We have also implemented two specifications related to reliable messaging viz. WS-Reliability and WS-ReliableMessaging. This software will be released separately as part of the FIRMS release in the coming weeks.

 

 

Installation: We wanted the software to be easy to use and install. We have included ANT scripts which facilitate the deployment of the software in a variety of settings.

 

 

Security: As mentioned previously WS-Eventing delegates security issues to WS-Security. The WS-Security specification provides the ability to securely route SOAP messages between endpoints irrespective of the underlying transport mechanism. Nothing in the WS-Eventing (or this implementation of the spec) precludes the use of WS-Security. 

 

 

Configuration and customization: This software is an implementation of a specification. We have provided scripts for deployment of the software in various settings.

 

 

Error handling: This software will report faults if there are problems with any of the exchanges outlined in the WS-Eventing specification. We enumerated some of these faults in an earlier section (section 3.0) of this document. The API for this software also facilitates the creation of appropriate requests and responses. These methods also reports if there are problems in any of the parameters involved in the method invocation.

 

 

6.         List Of Functions

This section provides a description of the core classes, and their methods, within the FINS software.

 

Package: cgl.narada.wsinfra.wse

 

public class WseActions

This class provides a one-stop for all the URIs related to WS-Addressing Action URIs used within WS-Eventing. This eliminates the need to hard-code this in several places. Furthermore, if the spec changes the impact of this change will be felt at far fewer places.

 

public static WseActions getInstance()

Description

This will return instance of this class

Input arguments

Process

 

Output

Object of  WseActions

Exceptions

 

Comments

This will return single instance of the class.

 

public String getSubscribe()

Description

Retrieve the String action associated with the exchange

Input arguments

Process

 

Output

String value of wseSubscribe

Exceptions

 

Comments

 

 

public static String getSubscribeResponse()

Description

Retrieve the String action associated with the exchange

Input arguments

Process

 

Output

String value of  wseSubscribeResponse

Exceptions

 

Comments

 

 

public static String getRenewResponse()

Description

Retrieve the String action associated with the exchange

Input arguments

Process

 

Output

String value of  wseRenewReponse

Exceptions

 

Comments

 

 

public String getGetStatus()

Description

Retrieve the String action associated with the exchange

Input arguments

Process

 

Output

String value of  wseGetStatus

Exceptions

 

Comments

 

 

public String getGetStatusResponse()

Description

Retrieve the String action associated with the exchange

Input arguments

Process

 

Output

String value of  wseGetStatusResponse

Exceptions

 

Comments

 

 

public String getUnsubscribe()

Description

Retrieve the String action associated with the exchange

Input arguments

Process

 

Output

String value of  wseUnsubscribe

Exceptions

 

Comments

 

 

public String getUnsubscribeResponse()

Description

Retrieve the String action associated with the exchange

Input arguments

Process

 

Output

String value of  wseUnsubscribeResponse

Exceptions

 

Comments

 

 

public String getSubscriptionEnd()

Description

Retrieve the String action associated with the exchange

Input arguments

Process

 

 

Output

String value of  wseSubscriptionEnd

Exceptions

 

Comments

 

 

public boolean isValidEventingAction(String actionToCheck)

Description

Check to see if this is one of the registered WS-Eventing actions

Input arguments

Process

String actionToCheck

Output

Boolean value

Exceptions

 

Comments

 

 

public ActionDocument getSubscribeAction()

Description

Retrieve the ActionDocument associated with the exchange

Input arguments

Process

 

Output

ActionDocument value of  wse getSubscribeAction

Exceptions

 

Comments

 

 

public ActionDocument getSubscribeResponseAction()

Description

Retrieve the ActionDocument associated with the exchange

Input arguments

Process

 

Output

ActionDocument value of  wseSubscribeResponseAction

Exceptions

 

Comments

 

 

public ActionDocument getRenewAction()

Description

Retrieve the ActionDocument associated with the exchange

Input arguments

Process

 

Output

ActionDocument value of  getRenewAction

Exceptions

 

Comments

 

 

public ActionDocument getRenewResponseAction()

Description

Retrieve the ActionDocument associated with the exchange

Input arguments

Process

 

Output

ActionDocument value of  wseRenewResponseAction

Exceptions

 

Comments

 

 

public ActionDocument getGetStatusAction()

Description

Retrieve the ActionDocument associated with the exchange

Input arguments

Process

 

Output

ActionDocument value of  wseGetStatusAction

Exceptions

 

Comments

 

 

public ActionDocument getGetStatusResponseAction()

Description

Retrieve the ActionDocument associated with the exchange

Input arguments

Process

 

Output

ActionDocument value of  wseGetStatusResponseAction

Exceptions

 

Comments

 

 

public ActionDocument getUnsubscribeAction()

Description

Retrieve the ActionDocument associated with the exchange

Input arguments

Process

 

Output

ActionDocument value of  wseUnsubscribeAction

Exceptions

 

Comments

 

 

public ActionDocument getUnsubscribeResponseAction()

Description

Retrieve the ActionDocument associated with the exchange

Input arguments

Process

 

Output

ActionDocument value of  wseUnsubscribeResponseAction

Exceptions

 

Comments

 

 

public ActionDocument getSubscriptionEndAction()

Description

Retrieve the ActionDocument associated with the exchange

Input arguments

Process

 

Output

ActionDocument value of  wseSubscriptionEndAction

Exceptions

 

Comments

 

private ActionDocument prepareActionDocument(String wsaAction)

Description

Retrieve the ActionDocument associated with the exchange

Input arguments

Process

String  value of wsaAction

Output

ActionDocument value of  wseUnsubscribeResponseAction

Exceptions

 

Comments

 

 

 

public interface WseElementCreation

This is a utility class which is responsible for the creation of elements that are used within WS-Eventing.

 

 

public SubscribeDocument newSubscribeDocument(String deliveryMode, EndpointReferenceType endTo, String filterDialect, String filterConstraint, Calendar expiresAt, EndpointReferenceType notifyTo) throws ProcessingException

Description

This method creates a subscribe request document based on the specified arguments

Input arguments

 

 

 

Process

String deliveryMode, EndpointReferenceType endTo,String filterDialect, String filterConstraint, Calendar expiresAt, EndpointReferenceType notifyTo

 

 

It checks NotifyTo element otherwise throws exception and adds all other parameters to SubscribeDocument.

Output

SubscribeDocument

Exceptions

ProcessingException

Comments

 

 

 

public SubscribeDocument newSubscribeDocument(String filterDialect, String filterConstraint, Calendar expiresAt,  EndpointReferenceType notifyTo) throws ProcessingException

Description

This method creates a subscribe request document based on the specified arguments.

Input arguments

 

 

Process

String filterDialect, String filterConstraint, Calendar expiresAt,  EndpointReferenceType notifyTo

 

It adds deliveryMode and endTo elements and calls previous method.

Output

SubscribeDocument

Exceptions

ProcessingException

Comments

 

 

public RenewDocument newRenewDocument(Calendar expiresAt)  throws ProcessingException

Description

This method creates a renew request document based on the      newly created subscription entry

Input arguments

 

Process

Calendar expiresAt

 

It checks for expiresAt element for null value and throws exception.

Output

RenewDocument

Exceptions

ProcessingException

Comments

 

 

public GetStatusDocument newGetStatusDocument()

Description

This method creates a getStatus request document based on the

newly created subscription entry

Input arguments

Process

 

Output

GetStatusDocument

Exceptions

 

Comments

 

 

public SubscribeResponseDocument newSubscribeResponseDocument(SubscriptionEntry subscriptionEntry) throws ProcessingException

Description

This method creates a subscribe response document based on the newly created subscription entry

Input arguments

 

Process

SubscriptionEntry subscriptionEntry

 

Checks for SubscriptionEntry for problems and returns new Subscription Response Document

Output

SubscribeResponseDocument

Exceptions

ProcessingException

Comments

 

 

public RenewResponseDocument newRenewResponseDocument(SubscriptionEntry  subscriptionEntry) throws ProcessingException

Description

This method creates a renew response document based on the newly created subscription entry

Input arguments

 

Process

SubscriptionEntry  subscriptionEntry

 

Check for Subscription entry for problems and creates new Renew Response Document.

Output

RenewResponseDocument

Exceptions

ProcessingException

Comments

 

 

public GetStatusResponseDocument newGetStatusResponseDocument(SubscriptionEntry  subscriptionEntry) throws ProcessingException

Description

This method creates a getStatus response document based on the newly created subscription entry

Input arguments

 

Process

SubscriptionEntry subscriptionEntry

 

Check for Subscription Entry for problems and creates new GetStatus Response Document

Output

GetStatusResponseDocument

Exceptions

ProcessingException

Comments

 

 

public SubscriptionEndDocument newSubscriptionEndDocument(SubscriptionEntry  subscriptionEntry, String status, String reason) throws ProcessingException

Description

This method create a SubscriptionEnd document based on the specified subscription entry

Input arguments

 

Process

SubscriptionEntry  subscriptionEntry,Sring status, String reason

 

Checks the Subscription Entry for problems, reason for not null. It will return new Subscription end document

Output

SubscriptionEndDocument

Exceptions

ProcessingException

Comments

 

 

 

public interface WseRequestCreator

This is a utility class which is used to create requests based on the specified parameters. The requests created by this utility class include

  • Subscribe
  • GetStatus
  • Renew
  • Unsubscribe

 

public EnvelopeDocument createSubscribe(EndpointReferenceType sourceEpr, EndpointReferenceType sinkEpr, SubscribeDocument subscribeDocument) throws ProcessingException

Description

Create the SOAP envelope with the specified subscribe request. This envelope's destination is the Sink which generated the original request message.

Input arguments

 

 

 

Process

EndpointReferenceType sourceEpr,                              EndpointReferenceType sinkEpr,                                  SubscribeDocument subscribeDocument

 

 

Check for sourceEpr Null values and creates subscribe EnvelopeDocument

Output

EnvelopeDocument

Exceptions

ProcessingException

Comments

This method is called from Sink Client

 

public EnvelopeDocument createRenew(EndpointReferenceType subscriptionManagerEpr, EndpointReferenceType sinkEpr, RenewDocument renewDocument) throws ProcessingException

Description

Create the SOAP envelope with the specified renew request. This envelope's destination is the sink which originated the message.

Input arguments

 

 

Process

EndpointReferenceType subscriptionManagerEpr,

EndpointReferenceType sinkEpr, RenewDocument renewDocument

 

Check for subscriptionManagerEpr for null values and creates renew Envelope document

Output

EnvelopeDocument

Exceptions

ProcessingException

Comments

This method is called from Sink Client

 

public EnvelopeDocument createGetStatus(EndpointReferenceType subscriptionManagerEpr, EndpointReferenceType sinkEpr, GetStatusDocument getStatusDocument) throws ProcessingException

Description

This method create a SubscriptionEnd document based on the specified subscription entry

Input arguments

 

 

 

Process

EndpointReferenceType subscriptionManagerEpr,

EndpointReferenceType sinkEpr, GetStatusDocument getStatusDocument

 

 

Check for subscriptionManagerEpr for null values and creates get Status Envelope Document

Output

EnvelopeDocument

Exceptions

ProcessingException

Comments

This method is called from Sink Client

 

public EnvelopeDocument createUnsubscribe(EndpointReferenceType subscriptionManagerEpr, EndpointReferenceType sinkEpr) throws ProcessingException

Description

Create the SOAP envelope with the specified getStatus request. This envelope's destination is the sink which originated the message.

Input arguments

 

 

Process

EndpointReferenceType subscriptionManagerEpr,

EndpointReferenceType sinkEpr

 

Check for subscriptionMnagerEpr for null values and creates Unsubscribe Envelope Document.

Output

EnvelopeDocument

Exceptions

ProcessingException

Comments

This method is called from Sink Client

 

public interface WseResponseCreator

This is a utility class which creates various responses based on the specified parameters. This is typically used by the source and the subscriptionManager.

 

public EnvelopeDocument createSubscribeResponse(EndpointReferenceType sinkEpr, EndpointReferenceType sourceEpr, RelatesToDocument relatesTo, SubscribeResponseDocument subscribeResponseDocument) throws ProcessingException

Description

Create the SOAP envelope with the specified subscribe response. This envelope's destination is the Sink which generated the original request message.

Input arguments

 

 

 

Process

EndpointReferenceType sinkEpr,  EndpointReferenceType sourceEpr,                  RelatesToDocument relatesTo, SubscribeResponseDocument

subscribeResponseDocument

 

Check for sinkEpr null values and creates subscribe response to Sink Envelope Document        

Output

EnvelopeDocument

Exceptions

ProcessingException

Comments

This method is called from Source

 

public EnvelopeDocument createSubscribeResponseToSM(EndpointReferenceType subscriptionManagerEpr, EndpointReferenceType sourceEpr, SubscribeDocument subscribeDocument, SubscribeResponseDocument subResponseDocument) throws ProcessingException

Description

Create the SOAP envelope with the specified subscribe response AND subscribe original request. This envelope's destination is the SubscriptionManager for the source in question.

Input arguments

 

 

 

Process

EndpointReferenceType subscriptionManagerEpr,                    EndpointReferenceType sourceEpr,              SubscribeDocument subscribeDocument,  SubscribeResponseDocument subResponseDocument

 

Check for SubscriptionManagerEpr for null values and creates  subscribe response to Subscription Manager Envelope Document

Output

EnvelopeDocument

Exceptions

ProcessingException

Comments

This method is called from Source

 

public EnvelopeDocument createRenewResponse(EndpointReferenceType sinkEpr, EndpointReferenceType subscriptionManagerEpr, RelatesToDocument relatesTo, RenewResponseDocument renewResponseDocument) throws ProcessingException

Description

Create the SOAP envelope with the specified renew response. This envelope's destination is the sink which originated the message.

Input arguments

 

 

 

Process

EndpointReferenceType sinkEpr,                                      EndpointReferenceType subscriptionManagerEpr,                     RelatesToDocument relatesTo,                           RenewResponseDocument renewResponseDocument

 

Check for sinkEpr for null values and creates renew response to Sink Envelope Document.

Output

EnvelopeDocument

Exceptions

ProcessingException

Comments

This method is called from Subscription Manager

 

public EnvelopeDocument createRenewResponseToSource(EndpointReferenceType sourceEpr, EndpointReferenceType subscriptionManagerEpr, String subscriptionIdentifier, RenewResponseDocument renewResponseDocument) throws ProcessingException

Description

Create the SOAP envelope with the specified renew response. This envelope's destination is the source which notifies the relevant sink.

Input arguments

 

 

 

 

Process

EndpointReferenceType sourceEpr,                                                  EndpointReferenceType subscriptionManagerEpr,                     String subscriptionIdentifier,                           RenewResponseDocument renewResponseDocument

 

Check for SourceEpr for null values and creates renew response document to Source Envelope Document

Output

EnvelopeDocument

Exceptions

ProcessingException

Comments

This method is called from Subscription Manager.

 

public EnvelopeDocument createGetStatusResponse(EndpointReferenceType sinkEpr, EndpointReferenceType subscriptionManagerEpr, RelatesToDocument relatesTo, GetStatusResponseDocument getStatusResponseDocument) throws ProcessingException

Description

Create the SOAP envelope with the specified getStatus response. This envelope's destination is the sink which originated the message.

Input arguments

 

 

 

Process

EndpointReferenceType sinkEpr, EndpointReferenceType subscriptionManagerEpr,                RelatesToDocument relatesTo,                     GetStatusResponseDocument getStatusResponseDocument

 

Check for sinkEpr for null values and creates getStatus response to Sink Envelope Document.

Output

EnvelopeDocument

Exceptions

ProcessingException

Comments

This method is called from Subscription Manager.

 

public EnvelopeDocument createUnsubscribeResponse(EndpointReferenceType sinkEpr, EndpointReferenceType subscriptionManagerEpr, RelatesToDocument relatesTo) throws ProcessingException

Description

Create the SOAP envelope with the specified getUnsubscribe response. This envelope's destination is the sink which originated the message.

Input arguments

 

 

Process

EndpointReferenceType sinkEpr,   EndpointReferenceType subscriptionManagerEpr,                  RelatesToDocument relatesTo

 

Check for sinkEpr for null values and creates unsubscribe response Envelope Document to Sink

Output

EnvelopeDocument

Exceptions

ProcessingException

Comments

This method is called from Subscription Manager

 

public EnvelopeDocument createUnsubscribeResponseToSource(EndpointReferenceType sourceEpr, EndpointReferenceType subscriptionMgrEpr, String subscriptionIdentifier) throws ProcessingException

Description

Create the SOAP envelope with the specified getStatus response. This envelope's destination is the source for the sink in question.

Input arguments

 

 

Process

EndpointReferenceType sourceEpr,              EndpointReferenceType subscriptionMgrEpr,    String subscriptionIdentifier

 

Check for sourceEpr for null values and creates unsubscribe response Document to Source

Output

EnvelopeDocument

Exceptions

ProcessingException

Comments

This method is called from Subscription Manager

 

 

 

public EnvelopeDocument createSubscriptionEnd(EndpointReferenceType destinationEpr, EndpointReferenceType sourceEpr, SubscriptionEndDocument subscriptionEndDocument) throws ProcessingException

Description

Creates a SOAP envelope with the subscription end document

Input arguments

 

 

Process

EndpointReferenceType destinationEpr, EndpointReferenceType sourceEpr, SubscriptionEndDocument subscriptionEndDocument

 

Checks for destinationEpr for null values and creates subscription end Envelope Document

Output

EnvelopeDocument

Exceptions

ProcessingException

Comments

This method is called from Subscription Manager.

 

public EndpointReferenceType getSendResponseTo(AddressingHeaders requestHeaders, EndpointReferenceType alternateEPR, String requestType) throws ProcessingException

Description

Try and the initialize the EPR to send a response message to. This is typically used to initialize the [wsa:To] element. The addressing headers that are passed here are the headers that were constructed based on the original request that came in previously. So this method will       look for the [wsa:ReplyTo] or [wsa:From] elements to construct the responses.

Input arguments

 

 

 

Process

AddressingHeaders requestHeaders,                             EndpointReferenceType alternateEPR,

String requestType

 

Check ‘[was:To]’ and ‘alternateEpr’ for null values and sends eighther ‘to’ if not null or alternateEpr based on request AddressingHeaders.

Output

EndpointReferenceType

Exceptions

ProcessingException

Comments

This method is called form Source and Subscription Manager

 

 

public RelatesToDocument getResponseRelatesTo(AddressingHeaders requestHeaders)

Description

Initializes the relates to element appropriately, based on whether there is a messageID in the requestHeaders. This will return a NULL if there is no MessageID within the AddressingHeaders

Input arguments

 

Process

AddressingHeaders requestHeaders

 

It checks for messageId in AddressingHeaders and returns ‘relatesTo’ is messageId is present.

Output

RelatesToDocument

Exceptions

 

Comments

This method is called from Source and Subscription Manger Processors.

 

Package: cgl.narada.wsinfra.wse.impl

 

public class SourceSubscribeRequestProcessing

 

Class which implements functionality related to processing subscription requests received at a source.

 

Following methods are in the SourceSubscribeRequestProcessing class

 

public static SourceSubscribeRequestProcessing getInstance()

Description

It will returns the instance of this class

Input arguments

 

Process

 

 

This method will return the single instance of the class.

Output

SourceSubscribeRequestProcessing

Exceptions

 

Comments

Constructor of this class is declares as private.

 

public SubscriptionEntry processSubscribeRequest(SubscribeDocument subscribeDocument, SubscriptionManagement subscriptionManagement, EndpointReferenceType sourceEpr, EndpointReferenceType subscriptionManagerEpr) throws WsFaultException

Description

The method to process a SubscriptionRequest issued by a Sink. If this request is successfully processed a SubscriptionEntry object is returned. If the request is NOT successful a WsFaultException is thrown.

Input arguments

 

 

 

Process

SubscribeDocument, SubscriptionManagement,      EndpointReferenceType sourceEpr,                                              EndpointReferenceType subscriptionManagerEpr

Output

SourceSubscribeRequestProcessing

Exceptions

WsFaultException

Comments

 

 

private SubscribeResponseDocument createSubscribeResponseDocument(SubscriptionEntry subscribeEntry)

Description

This method create a subscribe response document based on the newly create subscription entry

Input arguments

Process

SubscriptionEntry

Output

SubscribeResponseDocument

Exceptions

 

Comments

 

 

 

public EnvelopeDocument createEnvelopedResponse(AddressingHeaders requestHeaders, SubscribeResponseDocument subscribeResponseDocument)

 

Description

This method creates the appropriate SOAP envelope for the subscription response. It takes care to ensure that the appropriate Action headers, RelatesTo, MessageId, To and From Headers are appropriately filled

Input arguments

 

 

Process

AddressingHeaders,  SubscribeResponseDocument

Output

EnvelopeDocument

Exceptions

 

Comments

 

 

public EnvelopeDocument createEnvelopeForSubManager(EndpointReferenceType sourceEpr, EndpointReferenceType subscriptionManagerEpr, SubscribeDocument subscribeDocument, SubscribeResponseDocument subResponseDocument)

Description

This method creates the appropriate SOAP envelope for the subscription response. It takes care to ensure that the appropriate Action headers, RelatesTo, MessageId, To and From Headers are appropriately filled.

Input arguments

 

 

 

Process

EndpointReferenceType sourceEpr,                                                  EndpointReferenceType subscriptionManagerEpr,                     SubscribeDocument subscribeDocument,                       SubscribeResponseDocument subResponseDocument

Output

EnvelopeDocument

Exceptions

 

Comments

 

 

private EndpointReferenceType initializeTo(AddressingHeaders requestHeaders)

Description

Computes the destination to send a Message To based on the specified Addressing Headers

Input arguments

Process

AddressingHeaders

Output

EndpointReferenceType

Exceptions

 

Comments

 

 

 

public class WseNodeUtilsImpl extends WseNodeUtils

A utility class which retrieves the subscription identifier associated with an exchange. The method has to throw exceptions, if either the identifier is null or is not present. Furthermore, the identifier should also be a valid subscription maintained within subscription tables.

 

public static WseNodeUtils getInstance()

Description

This will return instance of WseNodeUtils class

Input arguments

Process

 

Output

WseNodeUtils

Exceptions

 

Comments

 

 

public SubscribeDocument getSubscribeDocument(EnvelopeDocument envelopeDocument) throws WsFaultException

Description

This method retrieves the SubscribeDocument element from the BODY of the SOAP envelope. The method has to throw exceptions, if either the element is null or is not present

Input arguments

Process

EnvelopeDocument

It checks for subscribeDocument for null values

Output

SubscribeDocument

Exceptions

WsFaultException

Comments

 

 

public SubscribeResponseDocument getSubscribeResponseDocument(EnvelopeDocument envelopeDocument) throws WsFaultException

Description

This method retrieves the SubscribeResponseDocument element from the BODY of the SOAP envelope. The method has to throw exceptions, if either the element is null or is not present

Input arguments

Process

EnvelopeDocument

It checks for null values.

Output

SubscribeResponseDocument

Exceptions

WsFaultException

Comments

 

 

public RenewDocument getRenewDocument(EnvelopeDocument envelopeDocument) throws WsFaultException

Description

This method retrieves the RenewDocument element from the BODY of the SOAP envelope. The method has to throw exceptions, if either the element is null or is not present.

Input arguments

Process

EnvelopeDocument

Output

RenewDocument

Exceptions

WsFaultException

Comments

 

 

public RenewResponseDocument getRenewResponseDocument(EnvelopeDocument envelopeDocument) throws WsFaultException

Description

This method retrieves the RenewResponseDocument element from the BODY of the SOAP envelope. The method has to throw exceptions, if either the element is null or is not present

Input arguments

Process

EnvelopeDocument

Output

RenewResponseDocument

Exceptions

WsFaultException

Comments

 

 

public GetStatusDocument getGetStatusDocument(EnvelopeDocument envelopeDocument) throws WsFaultException

Description

This method retrieves the GetStatusDocument element from the BODY of the SOAP envelope. The method has to throw exceptions, if either the element is null or is not present

Input arguments

Process

Envelope Document

Output

GetStatusDocument

Exceptions

WsFaultException

Comments

 

 

public GetStatusResponseDocument getGetStatusResponseDocument(EnvelopeDocument envelopeDocument) throws WsFaultException

Description

This method retrieves the GetStatusResponseDocument element from the BODY of the SOAP envelope. The method has to throw exceptions, if either the element is null or is not present

Input arguments

Process

Envelope Document

Output

GetStatusResponseDocument

Exceptions

WsFaultException

Comments

 

 

public UnsubscribeDocument getUnsubscribeDocument(EnvelopeDocument envelopeDocument) throws WsFaultException

Description

This method retrieves the UnsubscribeDocument element from the BODY of the SOAP envelope. The method has to throw exceptions, if either the element is null or is not present.

Input arguments

Process

Envelope Document

Output

UnsubscribeDocument

Exceptions

WsFaultException

Comments

 

 

public SubscriptionEndDocument getSubscriptionEndDocument(EnvelopeDocument envelopeDocument) throws WsFaultException

Description

This method retrieves the SubscriptionEndDocument element from the BODY of the SOAP envelope. The method has to throw exceptions, if either the element is null or is not present

Input arguments

Process

Envelope Document

Output

SubscriptionEndDocument

Exceptions

WsFaultException

Comments

 

 

public IdentifierDocument getIdentifierDocument(EnvelopeDocument envelopeDocument) throws WsFaultException

Description

This method retrieves the identifier element from the HEADER of the SOAP envelope. The method has to throw exceptions, if either the element is null or is not present

Input arguments

Process

Envelope Document

Output

IdentifierDocument

Exceptions

WsFaultException

Comments

 

 

public IdentifierDocument getIdentifierDocumentFromBody(EnvelopeDocument envelopeDocument) throws WsFaultException

Description

This method retrieves the identifier element from the BODY of the SOAP envelope. The method has to throw exceptions, if either the element is null or is not present.

Input arguments

Process

Envelope Document

Output

IdentifierDocument

Exceptions

WsFaultException

Comments

 

 

public EndpointReferenceType getNotifyTo(SubscribeDocument subscribeDocument) throws WsFaultException

Description

This method tries to retrieve the notifyTo element. The method also issues exception in case it is unable to do so or if the retrived element is actually null

Input arguments

Process

SubscribeDocument

Output

EndpointReferenceType

Exceptions

WsFaultException

Comments

 

 

public class WseSinkProcessor extends WsProcessor  implements SubscriptionExpiryListener

 

This class which implements the interface that encapsulates the behavior of a WS-Eventing sink node.

 

public boolean processExchange(EnvelopeDocument envelopeDocument, int direction)

Description

Process the exchange. The argument also indicates the direction in which the exchange has actually traversed

Input arguments

 

Process

Envelope Document

 

It gets the Addressing headers from Envelope Document. It gets the Action Document from addressing headers. It stores the request info based on action type and process response.

Output

Boolean true or false

Exceptions

UnknownExchangeException, IncorrectExchangeException,MessageFlowException, ProcessingException

Comments

 

 

public EnvelopeDocument createSubscribeRequest(EndpointReferenceType sourceEpr, String deliveryMode, EndpointReferenceType endTo, String filterDialect, String filterConstraint, Calendar expiresAt)

Description

Creates a subscribe request based on the specified parameters

Input arguments

 

 

 

Process

EndpointReferenceType sourceEpr, String deliveryMode, EndpointReferenceType endTo, String filterDialect, String filterConstraint, Calendar expiresAt

 

It creates Subscribe Document first and then it creates Envelope based on subscribe document.

Output

Envelope document

Exceptions

ProcessingException

Comments

 

 

public EnvelopeDocument  createGetStatus(String subscriptionIdentifier) throws ProcessingException