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

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

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.
java.lang.String	getCustomMData()
Device	getDevice() Get device.
Iterator	getDevicePortTypes(boolean doDiscovery) Gets port types implemented by device.
QName[]	getDevicePortTypesAsArray(boolean doDiscovery) Gets port types implemented by device.
EndpointReference	getEndpointReference() Gets endpoint reference of device.
long	getMetadataVersion(boolean doDiscovery) Returns the metadata version of the device.
XAddressInfo	getPreferredXAddressInfo()
Iterator	getScopes(boolean doDiscovery) Gets scopes the device resides in.
URI[]	getScopesAsArray(boolean doDiscovery) Gets scopes the device resides in.
int	getState() Gets state of device / device reference.
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?
boolean	isDeviceObjectExisting() Case remote: Did a proxy device object exist for the current version of the remote device?
boolean	isDiscovered() Case remote: Did we receive a resolve message for the current version of the device.
boolean	isSecureDevice()
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	setSecureDevice(boolean sec)

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

getLocation, getPreferredCommunicationManagerID, 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 TimeoutException

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:

TimeoutException - 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.setMatchWaitTime(long) and DispatchingProperties.setResponseWaitTime(int).

fetchCompleteDiscoveryDataSync

void fetchCompleteDiscoveryDataSync()
                                    throws TimeoutException

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:

TimeoutException

fetchCompleteDiscoveryDataAsync

void fetchCompleteDiscoveryDataAsync()
                                     throws TimeoutException

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:

TimeoutException

getEndpointReference

EndpointReference getEndpointReference()

Gets endpoint reference of device.

Returns:

the device's endpoint reference

getDevicePortTypes

Iterator getDevicePortTypes(boolean doDiscovery)
                            throws TimeoutException

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:

TimeoutException

getDevicePortTypesAsArray

QName[] getDevicePortTypesAsArray(boolean doDiscovery)
                                  throws TimeoutException

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:

TimeoutException

getScopes

Iterator getScopes(boolean doDiscovery)
                   throws TimeoutException

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:

TimeoutException

getScopesAsArray

URI[] getScopesAsArray(boolean doDiscovery)
                       throws TimeoutException

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:

TimeoutException

getMetadataVersion

long getMetadataVersion(boolean doDiscovery)
                        throws TimeoutException

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:

TimeoutException

getXAddressInfos

Iterator getXAddressInfos(boolean doDiscovery)
                          throws TimeoutException

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:

TimeoutException

getCustomMData

java.lang.String getCustomMData()

Returns:

the customize metadata as string

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

isSecureDevice

boolean isSecureDevice()

setSecureDevice

void setSecureDevice(boolean sec)

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