DefaultClient

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.ws4d.java.client
Class DefaultClient

java.lang.Object
  org.ws4d.java.client.DefaultClient

All Implemented Interfaces:: HelloListener, SearchCallback, EventListener, DeviceListener, ServiceListener

public class DefaultClient
extends java.lang.Object
implements DeviceListener, ServiceListener, SearchCallback, EventListener, HelloListener
extends java.lang.Object
implements DeviceListener, ServiceListener, SearchCallback, EventListener, HelloListener

Default DPWS Client implementation. This class provides easy access to several points of interaction within the DPWS framework, such as searching for devices/services, tracking a device's or service's state changes and receiving events from subscribed services.

The basic idea behind this class is: it extends several callback interfaces and provides empty implementations for all of their methods, so that an implementing client can easily overwrite those in which it is really interested in.

A simple use case of this class could be a client searching for a particular device. This can be accomplished by a call to searchDevice(SearchParameter) providing the desired search criteria within the expected SearchParameter argument. The framework will then start looking asynchronously for devices matching those criteria and will invoke deviceFound(DeviceReference, SearchParameter) each time a corresponding device is discovered.
Searching for services can be done in a similar manner, this time using the method searchService(SearchParameter) to initiate the search and receiving results by means of serviceFound(ServiceReference, SearchParameter).

When a client starts a device search, it is automatically registered as DeviceListener to any device matching the search criteria. This is especially useful for getting notifications about state changes of the device, such as a device shut-down, an update of a device's metadata, etc.

Listening to service state changes differs from the aforementioned approach. In order to start receiving service update notifications, a client must register itself for that purpose. It will then be notified about any state change regarding every service the DPWS framework knows about. This also includes any services not explicitly searched for by this client.

A simple client implementation interested in devices providing the ex:Printer port type (where ex is a XML namespace prefix referring to the http://www.example.org/printing namespace) could look like:

 // create a new client
 Client client = new DefaultClient() {
 
     // overwrite deviceFound method in order to receive callbacks
     public void deviceFound(DeviceReference devRef, SearchParameter search) {
         // start interacting with matching device
         ...
     }
 
 };
 // describe device port type to look for
 QName printerType = new QName("Printer", "http://www.example.org/printlng");
 QNameSet types = new QNameSet(printerType);
 
 // create a search parameter object and store desired type(s) into it
 SearchParameter criteria = new SearchParameter();
 criteria.setDeviceTypes(types);
 
 // start the asynchronous search
 client.searchDevice(criteria);

Constructor Summary
`DefaultClient()` Default constructor.

Method Summary
`void`	`deviceBuiltUp(DeviceReference deviceRef, Device device)` Callback method, if device within the `DeviceReference` was created.
`void`	`deviceBye(DeviceReference deviceRef)` Callback method, if device bye was received or the local device was stopped.
`void`	`deviceChanged(DeviceReference deviceRef)` Callback method, if device was changed and the device data is no longer accurate.
`void`	`deviceCommunicationErrorOrReset(DeviceReference deviceRef)` Callback method, if communication with the remote device of the `DeviceReference` has failed or the reference was reset.
`void`	`deviceCompletelyDiscovered(DeviceReference deviceRef)` Callback method, if discovery metadata was completely received from device (via directed probe).
`void`	`deviceFound(DeviceReference devRef, SearchParameter search)` This method is called each time a device matching the initial search criteria (as contained within argument `search`) has been found.
`void`	`deviceRunning(DeviceReference deviceRef)` Callback method, if device is usable.
`ParameterValue`	`eventReceived(ClientSubscription subscription, URI actionURI, ParameterValue parameterValue)` Callback method to receive events.
`EventSink`	`generateEventSink(int configurationId)` Generates an event sink which can be used when registering for event notifications from a service.
`DataStructure`	`getAllDiscoveryBindings()`
`DeviceReference`	`getDeviceReference(EndpointReference deviceEpr)`
`DeviceReference`	`getDeviceReference(EndpointReference deviceEpr, DiscoveryBinding binding)` Gets device reference of device with specified endpoint reference.
`DeviceReference`	`getDeviceReference(HelloData helloData)` Gets device reference of device which sent the specified hello data.
`EventSink`	`getEventSink(DataStructure bindings)` Gets an event sink, which can be used when registering for event notifications from a service.
`ServiceReference`	`getServiceReference(EndpointReference serviceEpr, java.lang.String comManId)` Gets service reference of service with specified endpoint reference.
`void`	`helloReceived(HelloData helloData)` This method is called, if matching hello was received.
`void`	`registerHelloListening()` Registers for incoming HelloMessages for all possible domains.
`void`	`registerHelloListening(DiscoveryBinding binding)` Registers for incoming Hello messages.
`void`	`registerHelloListening(SearchParameter search)` Registers for incoming HelloMessages for all possible domains, with specified types and scopes (`SearchParameter`).
`void`	`registerHelloListening(SearchParameter search, DiscoveryBinding binding)` Registers for incoming Hello messages, which matches to the specified types and scopes (`SearchParameter`).
`void`	`registerHelloListening(SearchParameter search, DiscoveryBinding binding, HelloListener helloListener)` Registers for incoming HelloMessages, which matches to the specified types and scopes (`SearchParameter`).
`void`	`registerServiceListening()` Registers client for service reference changes.
`void`	`searchDevice(SearchParameter search)` Shorthand method for searching devices.
`void`	`searchService(SearchParameter search)` Searches for services.
`void`	`serviceChanged(ServiceReference serviceRef, Service service)` Callback method, if service within the `ServiceReference` has been changed.
`void`	`serviceCreated(ServiceReference serviceRef, Service service)` Callback method, if the service within the `ServiceReference` was created.
`void`	`serviceDisposed(ServiceReference serviceRef)` Callback method, if the service within the `ServiceReference` was disposed of.
`void`	`serviceFound(ServiceReference servRef, SearchParameter search)` This method is called each time a service matching the initial search criteria (as contained within argument `search`) has been found.
`void`	`subscriptionEndReceived(ClientSubscription subscription, URI reason)` Callback method to receive unexpected subscription ends from event sources.
`void`	`subscriptionTimeoutReceived(ClientSubscription subscription)` Callback method to receive timeouts of subscriptions.
`void`	`unregisterHelloListening(DiscoveryBinding binding)` Unregisters the listeners for incoming hello messages according to the given `DiscoveryBinding`.
`void`	`unregisterHelloListening(SearchParameter search)` Unregisters the listeners for incoming hello messages according to the given `SearchParameter` and ALL `DiscoveryBinding` found.
`void`	`unregisterHelloListening(SearchParameter search, DiscoveryBinding binding)` Unregisters the listeners for incoming hello messages according to the given `SearchParameter` and `DiscoveryBinding`.
`void`	`unregisterServiceListening()` Unregisters service listening for this service client.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

DefaultClient

public DefaultClient()

Default constructor. Ensures the DPWS framework is running (see DPWSFramework.isRunning(). Throws a java.lang.RuntimeException if this is not the case.

Throws:: java.lang.RuntimeException - if the DPWS framework is not running; i.e. it was either not started by means of DPWSFramework.start(String[]) or has already been stopped via DPWSFramework.stop() before calling this constructor

Method Detail

getAllDiscoveryBindings

public DataStructure getAllDiscoveryBindings()

getEventSink

public EventSink getEventSink(DataStructure bindings)

Description copied from interface: EventListener

Gets an event sink, which can be used when registering for event notifications from a service. The supplied data structure bindings is supposed to contain at least one CommunicationBinding instance denoting a local transport address, at which incoming notifications shall be delivered to. The EventSink is associated with the EventListener.

Specified by:: getEventSink in interface EventListener

Parameters:: bindings - a data structure of CommunicationBinding instances to expose the created event sink over
Returns:: the event sink

generateEventSink

public EventSink generateEventSink(int configurationId)

Generates an event sink which can be used when registering for event notifications from a service. The supplied configuration id is supposed to refer to an EventSink property which contains at least one binding property to create a CommunicationBinding instance. This CommunicationBinding instance defines a local transport address, to which incoming notifications will be delivered.

Parameters:: configurationId - Configuration id of the properties of the event sink to generate
Returns:: a new event sink