org.ws4d.java.service.reference

Interface DeviceReference

All Superinterfaces:

Reference

All Known Implementing Classes:

DefaultDeviceReference

public interface DeviceReference
extends Reference

Reference to a device. The referenced device within can change. Get present device by method getDevice(). Device references are created within the discovery process and returned by the DefaultClient. All device references are registered in the DeviceServiceRegistry. There should only be one reference to each device.

Receiving a device reference typically means the registration as device listener (DeviceListener) to the device, which informs about device changes by using callbacks. The DefaultClient is such a device listener. Device listening can be added manually by addListener(DeviceListener) and can be removed by removeListener(DeviceListener).

Field Summary

Fields

Modifier and Type	Field and Description
static int	STATE_BUILD_UP STATE: Device is running is the latest known information about the referenced device, and device (proxy/local) was created
static int	STATE_RUNNING STATE: Device is running is the latest known information about the referenced device
static int	STATE_STOPPED STATE: Device has stopped is the latest known information about the referenced device
static int	STATE_UNKNOWN STATE: Device reference created, but no information about device state

Fields inherited from interface org.ws4d.java.service.reference.Reference

LOCATION_LOCAL, LOCATION_REMOTE, LOCATION_UNKNOWN

Method Summary

Modifier and Type	Method and Description
void	addListener(DeviceListener listener) Register listener (callback) for device reference changes.
void	fetchCompleteDiscoveryDataAsync() Fetches all discovery data of device reference by sending a directed probe to the remote device.
void	fetchCompleteDiscoveryDataSync() Fetches all discovery data of device reference by sending a directed probe to the remote device.
Iterator	getChildren(boolean doDiscovery) Returns the embedded device references, if any exist.
Device	getDevice() Get device.
Iterator	getDevicePortTypes(boolean doDiscovery) Gets port types implemented by device.
QName[]	getDevicePortTypesAsArray(boolean doDiscovery) Gets port types implemented by device.
DiscoveryData	getDiscoveryData()
Iterator	getDiscoveryXAddressInfos(boolean doDiscovery)
EndpointReference	getEndpointReference() Gets endpoint reference of device.
long	getMetadataVersion(boolean doDiscovery) Returns the metadata version of the device.
XAddressInfo	getPreferredDiscoveryXAddressInfo()
XAddressInfo	getPreferredXAddressInfo()
Iterator	getScopes(boolean doDiscovery) Gets scopes the device resides in.
URI[]	getScopesAsArray(boolean doDiscovery) Gets scopes the device resides in.
SecurityKey	getSecurityKey()
int	getState() Gets state of device / device reference.
Iterator	getTransportAndDiscoveryXAddressInfos(boolean doDiscovery)
Iterator	getXAddressInfos(boolean doDiscovery) Get the transport addresses of the device.
boolean	isAutoUpdateDevice()
boolean	isCompleteDiscovered() Case remote: Did we receive the answer to a directed probe for the current version of the device? Case local: Always true.
boolean	isDeviceObjectExisting() Case remote: Did a proxy device object exist for the current version of the remote device? Case local: Always true.
boolean	isDiscovered() Case remote: Did we receive a resolve message for the current version of the device.
void	probeDeviceDirectly(ResponseCallback callback)
Device	rebuildDevice()
void	removeListener(DeviceListener listener) Unregisters listener for this device reference.
void	setAutoUpdateDevice(boolean autoUpdateDevice) When set to true, the device reference will attempt to rebuild the device proxy automatically each time a a change in the device's metadata version is detected.
void	setSecurityKey(SecurityKey newKey)
boolean	supportsSecurity()

Methods inherited from interface org.ws4d.java.service.reference.Reference

getComManId, getLocation, getPreferredXAddress

Field Detail

STATE_UNKNOWN

static final int STATE_UNKNOWN

STATE: Device reference created, but no information about device state

See Also:

Constant Field Values

STATE_STOPPED

static final int STATE_STOPPED

STATE: Device has stopped is the latest known information about the referenced device

See Also:

Constant Field Values

STATE_RUNNING

static final int STATE_RUNNING

STATE: Device is running is the latest known information about the referenced device

See Also:

Constant Field Values

STATE_BUILD_UP

static final int STATE_BUILD_UP

STATE: Device is running is the latest known information about the referenced device, and device (proxy/local) was created

See Also:

Constant Field Values

Method Detail

getDevice

Device getDevice()
          throws CommunicationException

Get device. If a proxy device is not built, this will build it. Services may not be completely built.

A Proxy to a remote device is built up by sending resolve and get messages.

Returns:

device The device to this reference. The device can be a local device or a proxy to a remote device.

Throws:

CommunicationException - This exception is thrown, if the remote device doesn't answer to the messages, which tries to receive the necessary data. The possible messages to be sent are resolve, and get messages. The timeout value can be configured in the DispatchingProperties via the methods DispatchingProperties.setResponseWaitTime(int) and DispatchingProperties.setResponseWaitTime(int).

fetchCompleteDiscoveryDataSync

void fetchCompleteDiscoveryDataSync()
                             throws CommunicationException

Fetches all discovery data of device reference by sending a directed probe to the remote device. The current thread will block until a response is received from the device or an exception occurs during communication. This method will not do anything, if the associated device to this reference is local sited.

Throws:

CommunicationException

fetchCompleteDiscoveryDataAsync

void fetchCompleteDiscoveryDataAsync()
                              throws CommunicationException

Fetches all discovery data of device reference by sending a directed probe to the remote device. This method will not do anything, if the associated device to this reference is local sited.

Throws:

CommunicationException

getEndpointReference

EndpointReference getEndpointReference()

Gets endpoint reference of device.

Returns:

the device's endpoint reference

getDevicePortTypes

Iterator getDevicePortTypes(boolean doDiscovery)
                     throws CommunicationException

Gets port types implemented by device. If discovery should be done, no port types are known and device is remote located, a resolve message will be sent to remote device to discover them.

Parameters:

doDiscovery - if true and no port types are known and device is remote located, a resolve message will be sent to remote device to discover them.

Returns:

the port types of the device, object type is QName.

Throws:

CommunicationException

getDevicePortTypesAsArray

QName[] getDevicePortTypesAsArray(boolean doDiscovery)
                           throws CommunicationException

Gets port types implemented by device. If discovery should be done, no port types are known and device is remote located, a resolve message will be sent to remote device to discover them.

Parameters:

doDiscovery - if true and no port types are known and device is remote located, a resolve message will be sent to remote device to discover them.

Returns:

Shallow copy of the port types of the device, object type is QName.

Throws:

CommunicationException

getScopes

Iterator getScopes(boolean doDiscovery)
            throws CommunicationException

Gets scopes the device resides in. If discovery should be done, no port types are known and device is remote located, a resolve message will be sent to remote device to discover them.

Parameters:

doDiscovery - if true and no port types are known and device is remote located, a resolve message will be sent to remote device to discover them.

Returns:

the scopes of the device, object type is URI.

Throws:

CommunicationException

getScopesAsArray

URI[] getScopesAsArray(boolean doDiscovery)
                throws CommunicationException

Gets scopes the device resides in. If discovery should be done, no port types are known and device is remote located, a resolve message will be sent to remote device to discover them.

Parameters:

doDiscovery - if true and no port types are known and device is remote located, a resolve message will be sent to remote device to discover them.

Returns:

Shallow copy of the scopes of the device, object type is URI.

Throws:

CommunicationException

getMetadataVersion

long getMetadataVersion(boolean doDiscovery)
                 throws CommunicationException

Returns the metadata version of the device. If discovery should be done, no port types are known and device is remote located, a resolve message will be sent to remote device to discover them.

Parameters:

doDiscovery - if true and no port types are known and device is remote located, a resolve message will be sent to remote device to discover them.

Returns:

the metadata version of the device

Throws:

CommunicationException

getXAddressInfos

Iterator getXAddressInfos(boolean doDiscovery)
                   throws CommunicationException

Get the transport addresses of the device. If discovery should be done, no port types are known and device is remote located, a resolve message will be sent to remote device to discover them.

Parameters:

doDiscovery - if true and no port types are known and device is remote located, a resolve message will be sent to remote device to discover them.

Returns:

the transport addresses of the device, object type is URI .

Throws:

CommunicationException

getDiscoveryXAddressInfos

Iterator getDiscoveryXAddressInfos(boolean doDiscovery)
                            throws CommunicationException

Throws:

CommunicationException

getTransportAndDiscoveryXAddressInfos

Iterator getTransportAndDiscoveryXAddressInfos(boolean doDiscovery)
                                        throws CommunicationException

Throws:

CommunicationException

removeListener

void removeListener(DeviceListener listener)

Unregisters listener for this device reference. This method should be called, if holder of reference is no more interested in this reference.

Parameters:

listener - listener to remove.

addListener

void addListener(DeviceListener listener)

Register listener (callback) for device reference changes. Listeners get get information about device changes.

Parameters:

listener - listener (callback) to register.

isDeviceObjectExisting

boolean isDeviceObjectExisting()

Case remote: Did a proxy device object exist for the current version of the remote device?
Case local: Always true.

Returns:

Case remote: Did a proxy device object exist for the current version of the remote device?
Case local: Always true.

isCompleteDiscovered

boolean isCompleteDiscovered()

Case remote: Did we receive the answer to a directed probe for the current version of the device? Case local: Always true.

Returns:

Case remote: Did we receive the answer to a directed probe for the current version of the remote device?
Case local: Always true.

isDiscovered

boolean isDiscovered()

Case remote: Did we receive a resolve message for the current version of the device. Case local: Always true.

Returns:

Case remote: Did we receive a resolve message for the current version of the device?
Case local: Always true.

getState

int getState()

Gets state of device / device reference. The states specified for the device reference are STATE_UNKNOWN, STATE_RUNNING, STATE_BUILD_UP and STATE_STOPPED.

Returns:

the current state of the device

See Also:

STATE_UNKNOWN, STATE_RUNNING, STATE_BUILD_UP, STATE_STOPPED

isAutoUpdateDevice

boolean isAutoUpdateDevice()

setAutoUpdateDevice

void setAutoUpdateDevice(boolean autoUpdateDevice)

When set to true, the device reference will attempt to rebuild the device proxy automatically each time a a change in the device's metadata version is detected.

Parameters:

autoUpdateDevice -

getPreferredXAddressInfo

XAddressInfo getPreferredXAddressInfo()

getPreferredDiscoveryXAddressInfo

XAddressInfo getPreferredDiscoveryXAddressInfo()

getDiscoveryData

DiscoveryData getDiscoveryData()

getSecurityKey

SecurityKey getSecurityKey()

setSecurityKey

void setSecurityKey(SecurityKey newKey)

rebuildDevice

Device rebuildDevice()
              throws CommunicationException

Throws:

CommunicationException

getChildren

Iterator getChildren(boolean doDiscovery)
              throws CommunicationException

Returns the embedded device references, if any exist. Embedded devices are supported only by certain underlying technologies. Invoking this methods on a device reference of a technology like DPWS, where embedded devices do not exist, will always yield a return value of null. Getting information about the device hierarchy in some technologies involves additional communication over the network. Before this communication has taken place, the embed information returned by this method should be seen as preliminary.

Parameters:

doDiscovery - should be true if additional network communication is acceptable. This method will block until the information has been obtained.

Returns:

An iterator over a data structure containing the device references in the next lower level

Throws:

CommunicationException - Can only be thrown when doDiscovery is set to true

supportsSecurity

boolean supportsSecurity()

probeDeviceDirectly

void probeDeviceDirectly(ResponseCallback callback)