org.ws4d.java.eventing
Interface EventSource

All Superinterfaces:

OperationDescription

All Known Implementing Classes:

DefaultEventSource

public interface EventSource
extends OperationDescription

Events sources are the source of server-side notifications, which interested clients may subscribe to.

The DPWS framework supports two types of WSDL 1.1 and WS-Eventing compliant events: notifications and solicit-response operations. While 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.

Clients willing to receive notifications from this event source may simply subscribe to it. A subscription can be defined 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 missing network reachability.

Method Summary

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.
ClientSubscription	subscribe(EventListener client, long duration) Allows a client to subscribe to this event source.
ClientSubscription	subscribe(EventListener eventListener, long duration, DataStructure bindings) Allows a listener to subscribe to this event source.

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

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

Method Detail

isNotification

boolean isNotification()

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

Returns:

checks whether this is a notification event source

isSolicitResponse

boolean isSolicitResponse()

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

Returns:

checks whether this is a solicit-response event source

subscribe

ClientSubscription subscribe(EventListener client,
                             long duration)
                             throws EventingException,
                                    TimeoutException

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

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:

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

EventingException - if an error occurs during subscription

subscribe

ClientSubscription subscribe(EventListener eventListener,
                             long duration,
                             DataStructure bindings)
                             throws EventingException,
                                    TimeoutException

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

Parameters:

eventListener - 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:

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

EventingException - if an error occurs during subscription