org.ws4d.java.service

Class DefaultEventSource

java.lang.Object

org.ws4d.java.types.AttributableSupport

org.ws4d.java.service.OperationCommons

org.ws4d.java.service.DefaultEventSource

All Implemented Interfaces:

EventSource, OperationDescription, Attributable

Direct Known Subclasses:

EventSourceStub

public class DefaultEventSource
extends OperationCommons
implements EventSource

Events are the source of server-side notifications to which interested clients may subscribe. Services exposing events create instances of this class and call its fire(ParameterValue, int, CredentialInfo) method each time a notification is sent to subscribers.

The JMEDS framework supports two types of WSDL 1.1 and WS-Eventing compliant events: notifications and solicit-response operations. Whilst the first ones represent one-way messages sent from the event source to its subscribers, the later additionally includes response messages sent back from the subscribers to the source. Those responses are delivered to the callback method solicitResponseReceived(ParameterValue, int, ServiceSubscription). Means to identify the particular subscriber responding as well as the original event to which the response belongs are also provided, see documentation for methods fire(ParameterValue, int, CredentialInfo) and solicitResponseReceived(ParameterValue, int, ServiceSubscription).

Clients willing to receive notifications from this event source can simply subscribe to it. A subscription can be set up to expire after a certain amount of time ( duration) or it may last "forever", i.e. until either the event source or the subscriber explicitly cancels it or it terminates due to shutdown or to lack of network reachability. Note: According to WSDL 1.1 Specification, an operation's name is not required to be unique within the scope of its containing port type in order to support overloading. However, when overloading operations, the combination of each one's name, input name and output name must be unique in order to avoid name clashes.

Field Summary

Fields inherited from class org.ws4d.java.service.OperationCommons

inputAttributable, outputAttributable, type

Fields inherited from class org.ws4d.java.types.AttributableSupport

attributes

Constructor Summary

Constructors

Constructor and Description
DefaultEventSource(java.lang.String name, QName portType) Creates a new event source instance with the given local name and portType .
DefaultEventSource(WSDLOperation operation)

Method Summary

Modifier and Type	Method and Description
void	fire(ParameterValue paramValue, int eventNumber, CredentialInfo credentialInfo) Fires this event source.
protected int	getSubscriptionCount()
int	getType() Returns the transmission type of this event source according to WSDL 1.1 specification.
boolean	isNotification() Returns true, if the transmission type of this event source is WSDLOperation.TYPE_NOTIFICATION.
boolean	isSolicitResponse() Returns true, if the transmission type of this event source is WSDLOperation.TYPE_SOLICIT_RESPONSE.
void	notificationCommunicationException(CommunicationException exception, int eventNumber, ServiceSubscription subscription)
void	solicitResponseException(java.lang.Exception exception, int eventNumber, ServiceSubscription subscription)
void	solicitResponseFaultReceived(FaultMessage fault, int eventNumber, ServiceSubscription subscription)
void	solicitResponseReceived(ParameterValue paramValue, int eventNumber, ServiceSubscription subscription) Callback method for receiving responses to sent events if they are from type solicit-response.
ClientSubscription	subscribe(EventListener client, long duration, CredentialInfo credentialInfo) Allows a client to subscribe to this event source.
ClientSubscription	subscribe(EventListener client, long duration, DataStructure bindings, CredentialInfo credentialInfo) Allows a listener to subscribe to this event source.

Methods inherited from class org.ws4d.java.service.OperationCommons

addCustomComplexType, addFault, addInputParameter, addOutputParameter, clearCustomComplexTypes, createFaultValue, createFaultValue, createInputValue, createInputValue, createOutputValue, createOutputValue, equals, getCustomComplexTypes, getFault, getFaultAttribute, getFaultAttributes, getFaultCount, getFaults, getInput, getInputAction, getInputAttribute, getInputAttributes, getInputName, getInputParameter, getName, getNameQuallified, getOutput, getOutputAction, getOutputAttribute, getOutputAttributes, getOutputName, getOutputParameter, getPortType, getService, hasFaultAttributes, hashCode, hasInputAttributes, hasOutputAttributes, isInputActionSet, isInputNameSet, isOutputActionSet, isOutputNameSet, removeCustomComplexType, removeFault, setFaultAttribute, setFaultAttributes, setInput, setInputAction, setInputAttribute, setInputAttributes, setInputName, setInputNameInternal, setOutput, setOutputAction, setOutputAttribute, setOutputAttributes, setOutputName, setOutputNameInternal, setService, toString

Methods inherited from class org.ws4d.java.types.AttributableSupport

getAttribute, getAttributes, hasAttributes, serializeAttributes, setAttribute, setAttribute, setAttributes

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.ws4d.java.service.OperationDescription

createFaultValue, createInputValue, createOutputValue, getFault, getFaultCount, getFaults, getInput, getInputAction, getInputName, getName, getOutput, getOutputAction, getOutputName, getPortType, getService

Constructor Detail

DefaultEventSource

public DefaultEventSource(java.lang.String name,
                          QName portType)

Creates a new event source instance with the given local name and portType .

Parameters:

name - the name of the event source; see here for a short description of uniqueness requirements regarding event source names

portType - the qualified port type of the event source

DefaultEventSource

public DefaultEventSource(WSDLOperation operation)

Parameters:

operation -

Method Detail

fire

public void fire(ParameterValue paramValue,
                 int eventNumber,
                 CredentialInfo credentialInfo)

Fires this event source. This will send notifications to each subscriber of this event source. The values of any parameters for the notification are taken from argument paramValue .

In case this event source represents a solicit-response operation (in the sense of WSDL 1.1 Specification), the value of argument eventNumber can be used by callers to correlate incoming responses with this particular event source. It will be passed as the second argument to solicitResponseReceived(ParameterValue, int, ServiceSubscription) . It is recommended to increment the supplied value whenever calling this method, but this is not checked for, so other means of providing reliable correlation based on this value can also be used.

Parameters:

paramValue - the parameters to be sent to all subscribers with this event notification

eventNumber - a number identifying this event notification and allowing correlation to possible responses from subscribers

getType

public final int getType()

Returns the transmission type of this event source according to WSDL 1.1 specification. The value returned is one of WSDLOperation.TYPE_NOTIFICATION or WSDLOperation.TYPE_SOLICIT_RESPONSE.

Specified by:

getType in interface OperationDescription

Specified by:

getType in class OperationCommons

Returns:

type the transmission type of this event source

isNotification

public final boolean isNotification()

Returns true, if the transmission type of this event source is WSDLOperation.TYPE_NOTIFICATION. Returns false in any other case.

Specified by:

isNotification in interface EventSource

Returns:

checks whether this is a notification event source

isSolicitResponse

public final boolean isSolicitResponse()

Returns true, if the transmission type of this event source is WSDLOperation.TYPE_SOLICIT_RESPONSE. Returns false in any other case.

Specified by:

isSolicitResponse in interface EventSource

Returns:

checks whether this is a solicit-response event source

subscribe

public ClientSubscription subscribe(EventListener client,
                                    long duration,
                                    CredentialInfo credentialInfo)
                             throws EventingException,
                                    java.io.IOException,
                                    CommunicationException

Description copied from interface: EventSource

Allows a client to subscribe to this event source. The subscription will last for duration milliseconds or it will not expire at all when the value of duration is 0.

This method will generate auto-bindings when subscribing to an event source which belongs to a remotely deployed service. This/These binding(s) will be used to open a local event sink and listen for incoming notifications.

This method returns a ClientSubscription instance, which can be used to explore and manage the state of the subscription (e.g. renew or unsubscribe, etc.).

Specified by:

subscribe in interface EventSource

Parameters:

client - the client to which notification messages from this event source are to be sent

duration - time until subscription expires in milliseconds; 0 means subscription never expires

Returns:

a client subscription allowing management of the subscription state

Throws:

EventingException - if an error occurs during subscription

CommunicationException - if this event source belongs to a remote service and sending the subscription to it timed out

java.io.IOException

subscribe

public ClientSubscription subscribe(EventListener client,
                                    long duration,
                                    DataStructure bindings,
                                    CredentialInfo credentialInfo)
                             throws EventingException,
                                    java.io.IOException,
                                    CommunicationException

Description copied from interface: EventSource

Allows a listener to subscribe to this event source. The subscription will last duration milliseconds or it will not expire at all, in case the value of duration is 0.

When subscribing to an event source, which belongs to a remotely deployed service, it is important to include at least one CommunicationBinding within the argument bindings. This/These binding(s) will be used to open a local event sink and listen for incoming notifications.

This method returns a ClientSubscription instance, which can be used to explore and manage the state of the subscription (e.g. renew or unsubscribe, etc.).

Specified by:

subscribe in interface EventSource

Parameters:

client - the listener to which notification messages from this event source are to be sent

duration - time until subscription expires in milliseconds; 0 means subscription never expires

bindings - a data structure consisting of one or more CommunicationBinding instances; those are used to bind a local event sink to and allow it to listen for event notifications from a remote service

Returns:

a client subscription allowing management of the subscription state

Throws:

EventingException - if an error occurs during subscription

CommunicationException - if this event source belongs to a remote service and sending the subscription to it timed out

java.io.IOException

solicitResponseReceived

public void solicitResponseReceived(ParameterValue paramValue,
                                    int eventNumber,
                                    ServiceSubscription subscription)

Callback method for receiving responses to sent events if they are from type solicit-response. A call to this method is made by the JMEDS framework each time a subscribed client responds to a fired event source (see fire(ParameterValue, int, CredentialInfo). The parameters sent by the client within its response are contained within argument paramValue . The value of eventNumber corresponds to the value passed to fire(ParameterValue, int, CredentialInfo) when creating the notification to which this response belongs. Finally, argument subscription contains information allowing identification of the subscriber sending the response, as well as further details about its subscription (such as expiration time, filter, etc.).

Parameters:

paramValue - parameter value from the response received

eventNumber - number allowing for correlation between sent notifications (solicit requests) and their corresponding responses

subscription - provides information about the subscriber who sent the response

solicitResponseFaultReceived

public void solicitResponseFaultReceived(FaultMessage fault,
                                         int eventNumber,
                                         ServiceSubscription subscription)

solicitResponseException

public void solicitResponseException(java.lang.Exception exception,
                                     int eventNumber,
                                     ServiceSubscription subscription)

notificationCommunicationException

public void notificationCommunicationException(CommunicationException exception,
                                               int eventNumber,
                                               ServiceSubscription subscription)

getSubscriptionCount

protected int getSubscriptionCount()