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, DeviceListener) 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 CommunicationException 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

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

Methods inherited from class java.lang.Object

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

Method Detail

getDeviceReference

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

Gets device reference of device specified by an endpoint reference, an address and an security key. 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 from its referenced device.

Parameters:

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

address - the address of the device

key - the security key for this 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,
                                                 SecurityKey key,
                                                 DeviceListener listener,
                                                 DiscoveryBinding binding)

Gets device reference of device specified by an endpoint reference, an address and an security key. 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

key - the security key for this 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,
                                                 SecurityKey key,
                                                 DeviceListener listener,
                                                 DiscoveryBinding binding,
                                                 java.lang.String comManId)

Gets device reference of device with specified endpoint reference and security key. 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

key - the security key for this 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

getDeviceReference

public static DeviceReference getDeviceReference(HelloData helloData,
                                                 SecurityKey key,
                                                 DeviceListener listener,
                                                 java.lang.String comManId)

Gets device reference of device with specified endpoint reference(from helloData) and security key. 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

key - the security key for this device

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

Returns:

device reference

getServiceReference

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

Gets service reference of service with specified endpoint reference and security key.

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

key - the security key for this device

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

Returns:

service reference

createServiceReference

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

Gets service reference of service with specified endpoint reference and security key.

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

key - the security key for this device

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,
                                 DeviceListener listener)

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).
Warning: In case of DPWS this method is very expensive in both traffic and local resources because it first discovers all device and subsequently searches every device for the specified service.

Parameters:

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

callback - recipient of notifications about found matching services

listener - maybe null.

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 JMEDS framework.

Returns:

all local devices