org.ws4d.java.service
Class DefaultEventSource

java.lang.Object
  extended by org.ws4d.java.types.AttributableSupport
      extended by org.ws4d.java.service.OperationCommons
          extended by org.ws4d.java.service.DefaultEventSource
All Implemented Interfaces:
EventSource, OperationDescription, Attributable

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) method each time a notification is sent to subscribers.

The DPWS 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) 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.


Constructor Summary
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
 void fire(ParameterValue paramValue, int eventNumber)
          Fires this event source.
 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 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)
          Allows a client to subscribe to this event source.
 ClientSubscription subscribe(EventListener client, long duration, DataStructure bindings)
          Allows a listener to subscribe to this event source.
 
Methods inherited from class org.ws4d.java.service.OperationCommons
addCustomComplexType, addFault, addInputParameter, addOutputParameter, clearCustomComplexTypes, createFaultValue, createInputValue, createOutputValue, equals, getCustomComplexTypes, getFault, getFaultAttribute, getFaultAttributes, getFaultCount, getFaults, getInput, getInputAction, getInputAttribute, getInputAttributes, getInputName, getInputParameter, getName, getOutput, getOutputAction, getOutputAttribute, getOutputAttributes, getOutputName, getOutputParameter, getPortType, getService, hasFaultAttributes, hashCode, hasInputAttributes, hasOutputAttributes, isInputActionExtended, isInputActionSet, isInputNameSet, isOutputActionExtended, isOutputActionSet, isOutputNameSet, removeCustomComplexType, removeFault, setExtendedDefaultInputAction, setExtendedDefaultOutputAction, 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
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)
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)
                             throws EventingException,
                                    TimeoutException
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 DPWS 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
TimeoutException - if this event source belongs to a remote service and sending the subscription to it timed out

subscribe

public ClientSubscription subscribe(EventListener client,
                                    long duration,
                                    DataStructure bindings)
                             throws EventingException,
                                    TimeoutException
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 DPWS 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
TimeoutException - if this event source belongs to a remote service and sending the subscription to it timed out

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 DPWS framework each time a subscribed client responds to a fired event source (see fire(ParameterValue, int). 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) 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