org.ws4d.java.client
Class SearchManager

java.lang.Object
  org.ws4d.java.client.SearchManager

public final class SearchManager
extends java.lang.Object

This class provides tools for searching local and remote devices and services given a set of search criteria (see SearchParameter) and obtaining references to devices/services with known endpoint addresses.

A typical usage of the search functionality states that the caller provides an implementation of the SearchCallback interface which will receive asynchronous notifications about matching services/devices found during the search. Given this SearchCallback implementation and a SearchParameter instance describing what kind of devices/services to look for, the actual search can be started as depicted in the following sample code:

 SearchCallback callback = ...; // provide a receiver for search matches
 SearchParameter search = ...; // specify what to search for
 SearchManager.searchDevice(parameter, callback, null);
 

This example starts a search for a device, as the name of the called method #searchDevice(SearchParameter, SearchCallback, null) suggests. If a device fulfilling the given search parameter criteria is found, this will be indicated asynchronously by a call to SearchCallback.deviceFound(DeviceReference, SearchParameter). Similarly, if a search for services was issued (by means of searchService(SearchParameter, SearchCallback)), then matches would result in a call to SearchCallback.serviceFound(ServiceReference, SearchParameter).

The second purpose of this class is to enable the obtaining of a reference to a (local or remote) device/service when knowing its endpoint address (i.e. one of its endpoint references). This process differs somehow from the aforementioned search as it doesn't involve probing the network to assert the existence of the specified device or service (as its endpoint reference is already known). Thus, it is possible that calling DeviceReference.getDevice() or ServiceReference.getService() on the returned reference object results in a TimeoutException being thrown because the specified device/service is for some reason currently not reachable (e.g. it is not running at the moment or there is no network path connecting it with the local machine). In contrast, using the search abilities will provide notifications only about devices/services which are currently running and reachable.

Method Summary

static ServiceReference	createServiceReference(EndpointReference epr, QNameSet portTypes, java.lang.String comManId) Gets service reference of service with specified endpoint reference.
static DeviceReference	getDeviceReference(EndpointReference epr, DeviceListener listener, DiscoveryBinding binding) Gets device reference of device with specified endpoint reference.
static DeviceReference	getDeviceReference(EndpointReference epr, URI address, DeviceListener listener, DiscoveryBinding binding) Gets device reference of device specified by an endpoint reference and an address.
static DeviceReference	getDeviceReference(EndpointReference epr, URI address, DeviceListener listener, java.lang.String comManId) Gets device reference of device specified by an endpoint reference and an address.
static DeviceReference	getDeviceReference(HelloData helloData, DeviceListener listener) Gets device reference of device with specified endpoint reference.
static DataStructure	getLocalDevices() Returns a data structure containing all the local devices within the current DPWS framework.
static ServiceReference	getServiceReference(EndpointReference epr, java.lang.String comManId) Gets service reference of service with specified endpoint reference.
static void	searchDevice(SearchParameter search, SearchCallback callback, DeviceListener listener) Initiates a search for devices.
static void	searchService(SearchParameter search, SearchCallback callback) Searches for services.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getDeviceReference

public static DeviceReference getDeviceReference(EndpointReference epr,
                                                 URI address,
                                                 DeviceListener listener,
                                                 java.lang.String comManId)

Gets device reference of device specified by an endpoint reference and an address. If listener is not null, it will be used as callback for device changes of the corresponding device.

This method will NOT try to discover (resolve/probe) the device. If the address is unreachable or wrong this method will return null.

A DeviceReference that was created by this method has not DiscoveryBinding and will therefore not receive hello or bye messages form its referenced device.

Parameters:

epr - endpoint reference of device for which to get device reference

address - the address of the device

listener - optional; will be informed on changes of device' state

comManId - ID of the communication manager to use when interacting with supplied endpoint reference

Returns:

device reference for the specified device

getDeviceReference

public static DeviceReference getDeviceReference(EndpointReference epr,
                                                 URI address,
                                                 DeviceListener listener,
                                                 DiscoveryBinding binding)

Gets device reference of device specified by an endpoint reference and an address. If listener is not null, it will be used as callback for device changes of the corresponding device.

This method will NOT try to discover (resolve/probe) the device. If the address is unreachable or wrong this method will return null .

Parameters:

epr - endpoint reference of device for which to get device reference

address - the address of the device

listener - optional; will be informed on changes of device' state

binding - a DiscoveryBinding that specifies how to receive hello and bye messages for the DeviceReference

Returns:

device reference for the specified device

getDeviceReference

public static DeviceReference getDeviceReference(EndpointReference epr,
                                                 DeviceListener listener,
                                                 DiscoveryBinding binding)

Gets device reference of device with specified endpoint reference. If listener is not null, it will be used as callback for device changes of the corresponding device.

Parameters:

epr - endpoint reference of device for which to get device reference

listener - optional; will be informed on changes of device' state

binding - a DiscoveryBinding that specifies how to receive hello and bye messages for the DeviceReference

Returns:

device reference

getDeviceReference

public static DeviceReference getDeviceReference(HelloData helloData,
                                                 DeviceListener listener)

Gets device reference of device with specified endpoint reference. If listener is not null, it will be used as callback for device changes of the corresponding device.

Parameters:

helloData - hello data of device for which to get device reference

listener - optional; will be informed about changes of the device's state

Returns:

device reference

getServiceReference

public static ServiceReference getServiceReference(EndpointReference epr,
                                                   java.lang.String comManId)

Gets service reference of service with specified endpoint reference.

The returned @link ServiceReference instance can be used to obtain the actual service by calling ServiceReference.getService().

Parameters:

epr - endpoint reference of service to get service reference for

comManId - ID of the communication manager to use when interacting with supplied endpoint reference

Returns:

service reference

createServiceReference

public static ServiceReference createServiceReference(EndpointReference epr,
                                                      QNameSet portTypes,
                                                      java.lang.String comManId)
                                               throws DuplicateServiceReferenceException

Gets service reference of service with specified endpoint reference.

The returned @link ServiceReference instance can be used to obtain the actual service by calling ServiceReference.getService().

Parameters:

epr - endpoint reference of service to get service reference for

comManId - ID of the communication manager to use when interacting with supplied endpoint reference

Returns:

service reference

Throws:

DuplicateServiceReferenceException - in case a service reference with the same endpoint reference is already present

searchService

public static void searchService(SearchParameter search,
                                 SearchCallback callback)

Searches for services. Uses search parameter to specify the search criteria. When matching services are found, notifications are sent to the given callback by means of the method SearchCallback.serviceFound(ServiceReference, SearchParameter).

Parameters:

search - search parameter to specify the criteria that matching services must fulfill

callback - recipient of notifications about found matching services

searchDevice

public static void searchDevice(SearchParameter search,
                                SearchCallback callback,
                                DeviceListener listener)

Initiates a search for devices. A device is considered to match this search if its properties correspond to the values provided within argument search.

When a matching device is found, it is passed to the method SearchCallback.deviceFound(DeviceReference, SearchParameter) of the specified callback argument. Should listener not be null, it will be registered for tracking device changes on each matching device.

Parameters:

search - the search criteria for matching devices

callback - where search results are to be delivered to; must not be null

listener - if not null, the listener is used for asynchronous callbacks each time the state of a device matching the search criteria changes (i.e. when it goes online, etc.)

getLocalDevices

public static DataStructure getLocalDevices()

Returns a data structure containing all the local devices within the current DPWS framework.

Returns:

all local devices