org.ws4d.java.dispatch
Class DefaultDeviceReference

java.lang.Object
  org.ws4d.java.util.TimedEntry
      org.ws4d.java.dispatch.DefaultDeviceReference

All Implemented Interfaces:

DeviceReference, Reference

public class DefaultDeviceReference
extends TimedEntry
implements DeviceReference

Class holds listeners of device reference. Also manages creating and disposing of devices.

Field Summary

static AppSequence	APP_SEQUENCE_ZERO This sequence number should only be used to compare the first incoming message to proxy devices
static int	EVENT_DEVICE_BYE
static int	EVENT_DEVICE_CHANGED
static int	EVENT_DEVICE_COMPLETELY_DISCOVERED
static int	EVENT_DEVICE_FAULT_RESET
static int	EVENT_DEVICE_GET_RSP
static int	EVENT_DEVICE_SEEN

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

STATE_BUILD_UP, STATE_RUNNING, STATE_STOPPED, STATE_UNKNOWN

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	announceDeviceBye() Informs listeners on this device reference in separate thread about stop.
void	announceDeviceChangedAndBuildUp() Clones device listeners and informs everyone in separate thread about change.
void	announceDeviceRunningAndBuildUp() Clones device listeners and informs everyone in separate thread about change.
void	buildUpDevice() Instructs this device reference to asynchronously send a Get message to the device and create a new proxy, if required.
void	fetchCompleteDiscoveryDataAsync() Fetches all discovery data of device reference by sending a directed probe to the remote device.
void	fetchCompleteDiscoveryDataSync() Uses directed Probe to refresh discovery data.
java.lang.String	getCustomMData() Give the customize metadata
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.
int	getLocation() Returns the location of the device or service, which may be - LOCATION_UNKNOWN, - LOCATION_REMOTE, - LOCATION_LOCAL.
long	getMetadataVersion(boolean doDiscovery) Returns the metadata version of the device.
java.lang.String	getPreferredCommunicationManagerID() Returns the ID of the communication protocol to use when communicating with this reference's target over the current preferred transport address.
URI	getPreferredXAddress() Returns the preferred transport address for communication with this reference.
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()
Device	rebuildDevice() Rebuilds device.
void	removeListener(DeviceListener listener) Unregisters listener for this device reference.
void	reset() Resets all state information of the device reference except the endpoint reference.
void	reset(boolean recurse) Resets all state information of the device reference except the endpoint reference.
XAddressInfo	resolveRemoteDevice() Sends Resolve message to remote device.
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	setCustomMData(java.lang.String customMData) Set the customize metadata
void	setDiscoveryData(DiscoveryData newDiscoveryData)
Device	setLocalDevice(LocalDevice device) Sets device, replaces present device.
void	setSecureDevice(boolean sec)
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

APP_SEQUENCE_ZERO

public static final AppSequence APP_SEQUENCE_ZERO

This sequence number should only be used to compare the first incoming message to proxy devices

EVENT_DEVICE_SEEN

public static final int EVENT_DEVICE_SEEN

See Also:

Constant Field Values

EVENT_DEVICE_BYE

public static final int EVENT_DEVICE_BYE

See Also:

Constant Field Values

EVENT_DEVICE_GET_RSP

public static final int EVENT_DEVICE_GET_RSP

See Also:

Constant Field Values

EVENT_DEVICE_CHANGED

public static final int EVENT_DEVICE_CHANGED

See Also:

Constant Field Values

EVENT_DEVICE_COMPLETELY_DISCOVERED

public static final int EVENT_DEVICE_COMPLETELY_DISCOVERED

See Also:

Constant Field Values

EVENT_DEVICE_FAULT_RESET

public static final int EVENT_DEVICE_FAULT_RESET

See Also:

Constant Field Values

Method Detail

toString

public java.lang.String toString()

Overrides:

toString in class TimedEntry

getState

public int getState()

Description copied from interface: DeviceReference

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

Specified by:

getState in interface DeviceReference

Returns:

the current state of the device

See Also:

DeviceReference.STATE_UNKNOWN, DeviceReference.STATE_RUNNING, DeviceReference.STATE_BUILD_UP, DeviceReference.STATE_STOPPED

getDevice

public Device getDevice()
                 throws TimeoutException

Description copied from interface: DeviceReference

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.

Specified by:

getDevice in interface DeviceReference

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

rebuildDevice

public Device rebuildDevice()
                     throws TimeoutException

Rebuilds device. Removes all service references from registry. Should only be used for remote devices.

Returns:

Rebuild device.

Throws:

TimeoutException

buildUpDevice

public void buildUpDevice()

Instructs this device reference to asynchronously send a Get message to the device and create a new proxy, if required. The new proxy device is than announced asynchronously via DeviceListener#deviceBuildUp(DeviceReference, Device) method.

Note that in oder to reduce network traffic a Get message will actually be sent only if it is detected that the device within this device reference instance is not up to date anymore.

setLocalDevice

public Device setLocalDevice(LocalDevice device)

Sets device, replaces present device. Only to be used for local devices.

Parameters:

device - Replacement device (local).

Returns:

replaced device.

setDiscoveryData

public void setDiscoveryData(DiscoveryData newDiscoveryData)

reset

public void reset()

Resets all state information of the device reference except the endpoint reference. Removes the association between the device and services. This method has the same effect as calling reset(boolean) with an argument of false.

reset

public void reset(boolean recurse)

Resets all state information of the device reference except the endpoint reference. Removes the association between the device and services. If parameter recurse is set to true, than all service references currently associated with this device reference will be reset prior to removing them, too.

Parameters:

recurse - if service references associated with this device reference shell be reset, too

fetchCompleteDiscoveryDataSync

public void fetchCompleteDiscoveryDataSync()
                                    throws TimeoutException

Uses directed Probe to refresh discovery data. A previously built up device will be disposed of.

Specified by:

fetchCompleteDiscoveryDataSync in interface DeviceReference

Throws:

TimeoutException

fetchCompleteDiscoveryDataAsync

public void fetchCompleteDiscoveryDataAsync()

Description copied from interface: DeviceReference

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.

Specified by:

fetchCompleteDiscoveryDataAsync in interface DeviceReference

resolveRemoteDevice

public XAddressInfo resolveRemoteDevice()
                                 throws TimeoutException

Sends Resolve message to remote device. ResolveMatches message will be handled by callback handler, which updates discovery data. Only one Resolve message will be sent each time.

Returns:

preferred transport address of device and corresponding protocol

Throws:

TimeoutException

getLocation

public int getLocation()

Description copied from interface: Reference

Returns the location of the device or service, which may be - LOCATION_UNKNOWN, - LOCATION_REMOTE, - LOCATION_LOCAL.

Specified by:

getLocation in interface Reference

Returns:

the location of the device or service

getDevicePortTypes

public Iterator getDevicePortTypes(boolean doDiscovery)
                            throws TimeoutException

Description copied from interface: DeviceReference

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.

Specified by:

getDevicePortTypes in interface DeviceReference

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

public QName[] getDevicePortTypesAsArray(boolean doDiscovery)
                                  throws TimeoutException

Description copied from interface: DeviceReference

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.

Specified by:

getDevicePortTypesAsArray in interface DeviceReference

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

public Iterator getScopes(boolean doDiscovery)
                   throws TimeoutException

Description copied from interface: DeviceReference

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.

Specified by:

getScopes in interface DeviceReference

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

public URI[] getScopesAsArray(boolean doDiscovery)
                       throws TimeoutException

Description copied from interface: DeviceReference

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.

Specified by:

getScopesAsArray in interface DeviceReference

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

public long getMetadataVersion(boolean doDiscovery)
                        throws TimeoutException

Description copied from interface: DeviceReference

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.

Specified by:

getMetadataVersion in interface DeviceReference

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

public Iterator getXAddressInfos(boolean doDiscovery)
                          throws TimeoutException

Description copied from interface: DeviceReference

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.

Specified by:

getXAddressInfos in interface DeviceReference

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

getPreferredXAddress

public URI getPreferredXAddress()

Description copied from interface: Reference

Returns the preferred transport address for communication with this reference.

Specified by:

getPreferredXAddress in interface Reference

Returns:

the preferred transport address for this reference

getPreferredCommunicationManagerID

public java.lang.String getPreferredCommunicationManagerID()

Description copied from interface: Reference

Returns the ID of the communication protocol to use when communicating with this reference's target over the current preferred transport address. Will return the framework-wide default communication ID, if no preferred transport address has been explicitly set.

Specified by:

getPreferredCommunicationManagerID in interface Reference

Returns:

the ID of the protocol to communicate over with the target of this reference

getEndpointReference

public EndpointReference getEndpointReference()

Description copied from interface: DeviceReference

Gets endpoint reference of device.

Specified by:

getEndpointReference in interface DeviceReference

Returns:

the device's endpoint reference

getCustomMData

public java.lang.String getCustomMData()

Give the customize metadata

Specified by:

getCustomMData in interface DeviceReference

Returns:

String which contains the user added metadata.

setCustomMData

public void setCustomMData(java.lang.String customMData)

Set the customize metadata

Parameters:

customMData - String which contains the new customize metadata.

addListener

public void addListener(DeviceListener listener)

Description copied from interface: DeviceReference

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

Specified by:

addListener in interface DeviceReference

Parameters:

listener - listener (callback) to register.

removeListener

public void removeListener(DeviceListener listener)

Description copied from interface: DeviceReference

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

Specified by:

removeListener in interface DeviceReference

Parameters:

listener - listener to remove.

isDeviceObjectExisting

public boolean isDeviceObjectExisting()

Description copied from interface: DeviceReference

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

Specified by:

isDeviceObjectExisting in interface DeviceReference

Returns:

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

isDiscovered

public boolean isDiscovered()

Description copied from interface: DeviceReference

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

Specified by:

isDiscovered in interface DeviceReference

Returns:

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

isCompleteDiscovered

public boolean isCompleteDiscovered()

Description copied from interface: DeviceReference

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

Specified by:

isCompleteDiscovered in interface DeviceReference

Returns:

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

setAutoUpdateDevice

public void setAutoUpdateDevice(boolean autoUpdateDevice)

Description copied from interface: DeviceReference

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.

Specified by:

setAutoUpdateDevice in interface DeviceReference

isAutoUpdateDevice

public boolean isAutoUpdateDevice()

Specified by:

isAutoUpdateDevice in interface DeviceReference

announceDeviceBye

public void announceDeviceBye()

Informs listeners on this device reference in separate thread about stop.

announceDeviceChangedAndBuildUp

public void announceDeviceChangedAndBuildUp()

Clones device listeners and informs everyone in separate thread about change.

announceDeviceRunningAndBuildUp

public void announceDeviceRunningAndBuildUp()

Clones device listeners and informs everyone in separate thread about change.

isSecureDevice

public boolean isSecureDevice()

Specified by:

isSecureDevice in interface DeviceReference

setSecureDevice

public void setSecureDevice(boolean sec)

Specified by:

setSecureDevice in interface DeviceReference

getPreferredXAddressInfo

public XAddressInfo getPreferredXAddressInfo()

Specified by:

getPreferredXAddressInfo in interface DeviceReference