org.ws4d.java.service
Class DefaultDevice

java.lang.Object
  extended by org.ws4d.java.service.DeviceCommons
      extended by org.ws4d.java.service.DefaultDevice
All Implemented Interfaces:
Bindable, Lockable, Device, LocalDevice

public class DefaultDevice
extends DeviceCommons
implements LocalDevice

Implementation of a local DPWS device. A device in DPWS is a web service with specific functions. It can be discovered via probing by clients and it supports resolving of its endpoint. A device bears metadata information and services.

This class implements a local device within the framework. Its metadata can be configured and services can be added. The configuration can be done by use of a configuration file/stream via the Properties class. In this case, the constructor DefaultDevice(int configurationId) must be used with the configuration id of the matching device properties.

To receive messages, a communication binding CommunicationBinding must be added to the device. In DPWS, this binding must be a org.ws4d.java.communication.HTTPBinding, so that the device can receive get messages.

A DefaultDevice has to be started before becoming fully functional. Starting the device will establish the binding, i. e. a socket will be opened and the http server will listen to the address of the binding. In DPWS, a multicast listener will also be bound to the device. A hello message will then be sent to all connected networks. Residing services will also be started. Stopping the device will initiate the sending of a bye message, its services will be stopped and the binding will be removed.

Example code:
 DPWSFramework.start(args);
 ...
 DefaultDevice device = new DefaultDevice();
 HTTPBinding binding = new HTTPBinding( ip, port, "SimpleExampleDevice" );
 
 device.addBinding( binding );
 device.addService( service );
 device.addFriendlyName( "en-US", "JMEDS Simple Device" );
 
 device.start();
 

Important: Setting/Adding device data includes getting the exclusive lock ((Lockable) for the device.
If the device is running, each change will cause a hello message to be sent with an incremented metadata version. To combine multiple device data changes with sending only one hello message, the exclusive lock has to be first be obtained by exclusiveLock(). After the last device data change, releasing the exclusive lock through releaseExclusiveLock() will send a single hello with an incremented metadata version.

A DefaultDevice will respond to the following request message types:

with the appropriate response message types: Additionally the device initiates the sending of the following message types:

The DefaultDevice class implements the functionality of a Target Service described in the WSDD-Discovery specification. This version supports only the Ad hoc operational mode.


Nested Class Summary
 class DefaultDevice.AppSequenceManager
          Manages the application sequence of device.
 
Field Summary
 CustomizeMData custom
           
static boolean hasCustomizeMData
           
static int MAX_QNAME_SERIALIZATION
           
 
Constructor Summary
DefaultDevice()
          Constructor local DPWS device.
DefaultDevice(int configurationId)
          Constructor of local DPWS device.
 
Method Summary
 void addBinding(CommunicationBinding binding)
          Adds the given binding to this Bindable.
 void addBinding(DiscoveryBinding binding)
           
 void addFriendlyName(java.lang.String lang, java.lang.String friendlyName)
          Adds a friendly name to the device.
 void addGroup(HTTPGroup group)
           
 void addManufacturer(java.lang.String lang, java.lang.String manufacturer)
          Adds manufacturer name to the device which is used as value of the "dpws:Manufacturer" element in the model metadata.
 void addModelName(java.lang.String lang, java.lang.String modelName)
          Adds a model name to the device.
 void addOutputDiscoveryDomain(ProtocolDomain domain)
          Adds the specified protocol domain to this device.
 void addService(LocalService service)
          Adds service to device.
 void addService(LocalService service, boolean startIfRunning)
          Adds a service to the device.
 void addServiceReferences(DataStructure to, QNameSet servicePortTypes)
          Adds service references associated to this device to the data structure to, if they match the service port types given within serviceTypes.
 void addUser(HTTPUser user)
           
 void clearBindings()
          Removes all bindings from this Bindable instance.
 boolean deviceMatches(QNameSet searchTypes, ProbeScopeSet searchScopes)
          Checks if this device matches the searched device port types and scopes.
 void exclusiveLock()
          Acquires an exclusive lock.
 Iterator getBindings()
          Returns an iterator over all bindings assigned to this Bindable instance.
 int getConfigurationID()
          Gets the configuration id.
 java.lang.String getDefaultNamespace()
          return the default namespace.
 ThisDeviceMData getDeviceMetadata()
           
 DeviceProperties getDeviceProperties()
          Gets device configuration properties.
 DeviceReference getDeviceReference()
          Gets the DeviceReference of this device.
 Iterator getDiscoveryBindings()
           
 DiscoveryData getDiscoveryData()
          This will return the discovery data of the local device.
 EndpointReference getEndpointReference()
          Returns the endpoint reference of this device.
 java.lang.String getFirmwareVersion()
          Gets firmware version.
 java.lang.String getFriendlyName(java.lang.String lang)
          Gets friendly name of device.
 Iterator getFriendlyNames()
          Gets iterator over all friendly names of device.
 HTTPGroup getGroup()
           
 java.lang.String getManufacturer(java.lang.String lang)
          Gets manufacturer by language.
 Iterator getManufacturers()
          Gets all manufacturers as iterator over manufacterer names.
 java.lang.String getManufacturerUrl()
          Gets the url of the manufacturer.
 long getMetadataVersion()
          Returns metadata version for this device.
 ThisModelMData getModelMetadata()
           
 java.lang.String getModelName(java.lang.String lang)
          Gets model name by language.
 Iterator getModelNames()
          Gets all model names as iterator over model names.
 java.lang.String getModelNumber()
          Gets model number of device.
 java.lang.String getModelUrl()
          Gets model url of device.
 Iterator getPortTypes()
          Gets the iterator over device port types of the device.
 java.lang.String getPresentationUrl()
          Gets presentation url of device.
 Iterator getScopes()
          Gets iterator over all scopes of the device.
 java.lang.String getSerialNumber()
          Gets serial number.
 ServiceReference getServiceReference(EndpointReference serviceEpr)
          Get service reference by endpoint reference of referenced service.
 ServiceReference getServiceReference(URI serviceId)
          Gets service reference by service id of referenced service.
 Iterator getServiceReferences()
          Gets iterator over the service references of all services.
 Iterator getServiceReferences(QNameSet servicePortTypes)
          Gets iterator over the service reference of the services, which implements all port types specified.
 Iterator getServices()
          Gets iterator over all services.
 Iterator getXAddressInfos()
          Returns a iterator over the transport addresses of this device.
 boolean hasBindings()
          Returns true only if this Bindable instance has at least one binding assigned.
 boolean hasCustomizeMData()
          Tagged if a Device has metadata which are added by a user
 boolean hasDiscoveryBindings()
           
 void invalidate()
           
 boolean isDiscoveryProxy()
           
 boolean isRemote()
          Is device remote (proxy) or local?
 boolean isRunning()
          Returns if the device was started and is running now.
 boolean isUsingDefaultDiscoveryDomains()
          Does the device use the default discovery domains for send multicast discovery messages.
 boolean isValid()
           
 java.lang.String readCustomizeMData()
          The method return the metadata that a user has added as String
 boolean releaseExclusiveLock()
          Releases an exclusive lock of the current thread.
 void releaseSharedLock()
          Releases a shared lock of the current thread.
 boolean removeBinding(CommunicationBinding binding)
          Removes the specified binding from this Bindable instance.
 boolean removeBinding(DiscoveryBinding binding)
           
 void removeOutputDiscoveryDomain(ProtocolDomain domain)
          Removes a previously added output domain from this device.
 void removeService(LocalService service)
          Removes service from device.
 void removeService(LocalService service, boolean stopIfRunning)
          Removes a service from the device.
 void sendBye()
          Sends Bye Message.
 void sendHello()
          Sends hello message.
 void setDefaultNamespace(java.lang.String ns)
           
 void setDeviceMetadata(ThisDeviceMData deviceMetadata)
          Sets the device metadata of the device.
 void setDiscoveryProxy(boolean isDiscoveryProxy)
           
 void setEndpointReference(EndpointReference endpoint)
          Sets the EndpointReference of this device.
 void setFirmwareVersion(java.lang.String firmware)
          Sets the firmware version to the device.
 void setManufacturerUrl(java.lang.String manufacturerUrl)
          Sets the url of the manufacturer.
 void setMetadataVersion(long metadataVersion)
          Sets the metadata version of the device.
 void setModelMetadata(ThisModelMData modelMetadata)
          Sets the model metadata of the device.
 void setModelNumber(java.lang.String modelNumber)
          Sets the model number of the device.
 void setModelUrl(java.lang.String modelUrl)
          Sets the model url of the device.
 void setPortTypes(QNameSet qnsPortTypes)
          Sets the port types of the device.
 void setPresentationUrl(java.lang.String presentationUrl)
          Sets the presentation url of the device.
 void setScopes(ScopeSet scopes)
          Sets a list of scopes.
 void setSerialNumber(java.lang.String serialNumber)
          Sets the serial number of the device.
 void sharedLock()
          Acquires a shared lock.
 void start()
          Starts the device.
 void stop()
          Stops the device.
 void stop(boolean stopServices)
          Stops the device.
 boolean supportsBindingChanges()
          Returns true, if it is safe to call one of the mutator methods ((Bindable.addBinding(CommunicationBinding), Bindable.removeBinding(CommunicationBinding), (Bindable.clearBindings(), etc.) at this time without getting an IllegalStateException.
 boolean tryExclusiveLock()
          Try to get an exclusive lock immediately.
 boolean trySharedLock()
          Tries to get a shared lock immediately.
 void writeCustomizeMData(HashMap metaData)
          Add user metadata to a device
 
Methods inherited from class org.ws4d.java.service.DeviceCommons
equals, getCertificate, getPrivateKey, hashCode, isSecure, setCertificate, setPrivateKey, setSecureDevice, setSecureDevice, toString
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.ws4d.java.service.Device
getCertificate, getPrivateKey, isSecure, setCertificate, setPrivateKey, setSecureDevice
 

Field Detail

MAX_QNAME_SERIALIZATION

public static final int MAX_QNAME_SERIALIZATION
See Also:
Constant Field Values

hasCustomizeMData

public static boolean hasCustomizeMData

custom

public CustomizeMData custom
Constructor Detail

DefaultDevice

public DefaultDevice()
Constructor local DPWS device. No device properties of the properties file/stream Properties are used to build up the device.

Important: It is necessary to add a binding to a device before it can be started.


DefaultDevice

public DefaultDevice(int configurationId)
Constructor of local DPWS device. The given configuration id should map to the device property entries in the configuration file/stream Properties. The property entries of this device will be gathered in a DeviceProperties object and used to build up the device and its metadata.

Important: It is necessary to add a binding to a device before it can be started. The binding may be specified within the configuration file/stream.

Parameters:
configurationId - The configuration id that map to the device properties within the configuration file/stream.
Method Detail

isRemote

public boolean isRemote()
Description copied from interface: Device
Is device remote (proxy) or local?

Specified by:
isRemote in interface Device
Returns:
whether this is a remote device (proxy) or not

isRunning

public boolean isRunning()
Description copied from interface: LocalDevice
Returns if the device was started and is running now.

Specified by:
isRunning in interface LocalDevice
Returns:
true, if this device is running

hasBindings

public boolean hasBindings()
Description copied from interface: Bindable
Returns true only if this Bindable instance has at least one binding assigned. Returns false, if it doesn't have any bindings.

Specified by:
hasBindings in interface Bindable
Returns:
whether there are any bindings assigned to that Bindable instance or not

hasDiscoveryBindings

public boolean hasDiscoveryBindings()

getBindings

public Iterator getBindings()
Description copied from interface: Bindable
Returns an iterator over all bindings assigned to this Bindable instance. This iterator will have no next elements (rather than being ), if the Bindable doesn't have any bindings.

Specified by:
getBindings in interface Bindable
Returns:
an iterator over all available bindings

getDiscoveryBindings

public Iterator getDiscoveryBindings()

supportsBindingChanges

public boolean supportsBindingChanges()
Description copied from interface: Bindable
Returns true, if it is safe to call one of the mutator methods ((Bindable.addBinding(CommunicationBinding), Bindable.removeBinding(CommunicationBinding), (Bindable.clearBindings(), etc.) at this time without getting an IllegalStateException. Returns false otherwise.

Some implementations of this interface may not allow for bindings to be added or removed all the time, but rather only when the actual implementation is in a certain set of states (note that this set could be empty or contain solely a single set). By calling this method and observing its return value it is possible for a client to determine whether this Bindable supports changes within its current state.

Specified by:
supportsBindingChanges in interface Bindable
Returns:
true if this Bindable instance may be modified at the moment without throwing IllegalStateExceptions, false otherwise
See Also:
Bindable.addBinding(CommunicationBinding), Bindable.removeBinding(CommunicationBinding), Bindable.clearBindings()

addBinding

public void addBinding(CommunicationBinding binding)
                throws WS4DIllegalStateException
Description copied from interface: Bindable
Adds the given binding to this Bindable. Does nothing if the Bindable already contains the binding.

Specified by:
addBinding in interface Bindable
Parameters:
binding - the binding to add
Throws:
WS4DIllegalStateException - in case this Bindable doesn't currently support modifications (see Bindable.supportsBindingChanges())

addBinding

public void addBinding(DiscoveryBinding binding)
                throws WS4DIllegalStateException
Throws:
WS4DIllegalStateException

removeBinding

public boolean removeBinding(CommunicationBinding binding)
                      throws WS4DIllegalStateException
Description copied from interface: Bindable
Removes the specified binding from this Bindable instance. Does nothing, if the Bindable doesn't contain the given binding. Returns true if the binding was removed and false if it didn't exist.

Specified by:
removeBinding in interface Bindable
Parameters:
binding - the binding to remove
Returns:
true if this Bindable instance had the given binding assigned and it was removed successfully, false otherwise
Throws:
WS4DIllegalStateException - in case this Bindable doesn't currently support modifications (see Bindable.supportsBindingChanges())

removeBinding

public boolean removeBinding(DiscoveryBinding binding)
                      throws WS4DIllegalStateException
Throws:
WS4DIllegalStateException

clearBindings

public void clearBindings()
                   throws WS4DIllegalStateException
Description copied from interface: Bindable
Removes all bindings from this Bindable instance. Does nothing if there are no bindings assigned.

Specified by:
clearBindings in interface Bindable
Throws:
WS4DIllegalStateException - in case this Bindable doesn't support modifications at the current time (see Bindable.supportsBindingChanges())

getDeviceReference

public DeviceReference getDeviceReference()
Description copied from interface: Device
Gets the DeviceReference of this device.

Specified by:
getDeviceReference in interface Device
Returns:
The DeviceReference of this device.

start

public final void start()
                 throws java.io.IOException
Starts the device. Starting the device will:

Specified by:
start in interface LocalDevice
Throws:
java.io.IOException - is thrown, if a binding couldn't be bound to the communication manager or if starting a service will throw the exception.

stop

public final void stop()
                throws java.io.IOException
Stops the device. Stopping the device will:

Specified by:
stop in interface LocalDevice
Throws:
java.io.IOException - is thrown if a binding couldn't be unbound or if stopping a service will throw the exception.

stop

public final void stop(boolean stopServices)
                throws java.io.IOException
Stops the device. Stopping the device will:

Parameters:
stopServices - If true, stops services too.
Throws:
java.io.IOException - is thrown if a binding couldn't be unbound or if stopping a service will throw the exception.

sendHello

public void sendHello()
Sends hello message. Simple method to announce the device is in the network.

Important: This method won't start the device. But starting this device will automatically send a hello message.

Specified by:
sendHello in interface LocalDevice

sendBye

public void sendBye()
Sends Bye Message. Simple method to send a bye message to the network.

Important: This method won't stop the device. But stopping this device will automatically send a bye message.

Specified by:
sendBye in interface LocalDevice

sharedLock

public void sharedLock()
Description copied from interface: Lockable
Acquires a shared lock. If the lock cannot be allocated immediately, the thread is blocked until allocation is possible.

Specified by:
sharedLock in interface Lockable

exclusiveLock

public void exclusiveLock()
Description copied from interface: Lockable
Acquires an exclusive lock. If the lock cannot be allocated immediately, the thread is blocked until allocation is possible.

Specified by:
exclusiveLock in interface Lockable

releaseSharedLock

public void releaseSharedLock()
Description copied from interface: Lockable
Releases a shared lock of the current thread.

Specified by:
releaseSharedLock in interface Lockable

releaseExclusiveLock

public boolean releaseExclusiveLock()
Description copied from interface: Lockable
Releases an exclusive lock of the current thread.

Specified by:
releaseExclusiveLock in interface Lockable
Returns:
true = if last exclusive lock of this thread is released.

tryExclusiveLock

public boolean tryExclusiveLock()
Description copied from interface: Lockable
Try to get an exclusive lock immediately.

Specified by:
tryExclusiveLock in interface Lockable
Returns:
true if the lock has been allocated, false otherwise

trySharedLock

public boolean trySharedLock()
Description copied from interface: Lockable
Tries to get a shared lock immediately.

Specified by:
trySharedLock in interface Lockable
Returns:
true if the lock has been allocated, false otherwise

getEndpointReference

public EndpointReference getEndpointReference()
Description copied from interface: Device
Returns the endpoint reference of this device. This endpoint reference is a unique identifier for the device.

Specified by:
getEndpointReference in interface Device
Returns:
endpoint reference as unique identifier.

getPortTypes

public Iterator getPortTypes()
Description copied from interface: Device
Gets the iterator over device port types of the device. The port types are of type QName.

Specified by:
getPortTypes in interface Device
Returns:
Iterator over device port types of type QName.

getScopes

public Iterator getScopes()
Description copied from interface: Device
Gets iterator over all scopes of the device. A scope is of type URI.

Specified by:
getScopes in interface Device
Returns:
Iterator over all scopes of type URI.

getManufacturer

public java.lang.String getManufacturer(java.lang.String lang)
Description copied from interface: Device
Gets manufacturer by language. Language consts are specified in LocalizedString.

Specified by:
getManufacturer in interface Device
Overrides:
getManufacturer in class DeviceCommons
Parameters:
lang - The language of the manufacturer's name to be obtained. The language consts are specified in LocalizedString.
Returns:
Manufacturer's name in specified language of type LocalizedString.

getManufacturers

public Iterator getManufacturers()
Description copied from interface: Device
Gets all manufacturers as iterator over manufacterer names. A single manufacturer name is of type LocalizedString.

Specified by:
getManufacturers in interface Device
Overrides:
getManufacturers in class DeviceCommons
Returns:
Iterator over manufacturer of type LocalizedString.

getManufacturerUrl

public java.lang.String getManufacturerUrl()
Description copied from interface: Device
Gets the url of the manufacturer.

Specified by:
getManufacturerUrl in interface Device
Overrides:
getManufacturerUrl in class DeviceCommons
Returns:
Url of manufacturer

getModelName

public java.lang.String getModelName(java.lang.String lang)
Description copied from interface: Device
Gets model name by language. Language consts are specified in LocalizedString.

Specified by:
getModelName in interface Device
Overrides:
getModelName in class DeviceCommons
Parameters:
lang - Language of the model name to get. The language consts are specified in LocalizedString.
Returns:
Model name in specified language of type LocalizedString.

getModelNames

public Iterator getModelNames()
Description copied from interface: Device
Gets all model names as iterator over model names. A single model name is of type LocalizedString.

Specified by:
getModelNames in interface Device
Overrides:
getModelNames in class DeviceCommons
Returns:
Iterator over model names of type LocalizedString.

getModelNumber

public java.lang.String getModelNumber()
Description copied from interface: Device
Gets model number of device.

Specified by:
getModelNumber in interface Device
Overrides:
getModelNumber in class DeviceCommons
Returns:
Model number.

getModelUrl

public java.lang.String getModelUrl()
Description copied from interface: Device
Gets model url of device.

Specified by:
getModelUrl in interface Device
Overrides:
getModelUrl in class DeviceCommons
Returns:
Model url.

getPresentationUrl

public java.lang.String getPresentationUrl()
Description copied from interface: Device
Gets presentation url of device.

Specified by:
getPresentationUrl in interface Device
Overrides:
getPresentationUrl in class DeviceCommons
Returns:
Presentation url.

getFriendlyName

public java.lang.String getFriendlyName(java.lang.String lang)
Description copied from interface: Device
Gets friendly name of device.

Specified by:
getFriendlyName in interface Device
Overrides:
getFriendlyName in class DeviceCommons
Parameters:
lang - language of friendly name
Returns:
Friendly name of type LocalizedString in specified language

getFriendlyNames

public Iterator getFriendlyNames()
Description copied from interface: Device
Gets iterator over all friendly names of device. A single name is of type LocalizedString.

Specified by:
getFriendlyNames in interface Device
Overrides:
getFriendlyNames in class DeviceCommons
Returns:
Iterator over friendly names of type LocalizedString.

getFirmwareVersion

public java.lang.String getFirmwareVersion()
Description copied from interface: Device
Gets firmware version.

Specified by:
getFirmwareVersion in interface Device
Overrides:
getFirmwareVersion in class DeviceCommons
Returns:
firmware version

getSerialNumber

public java.lang.String getSerialNumber()
Description copied from interface: Device
Gets serial number.

Specified by:
getSerialNumber in interface Device
Overrides:
getSerialNumber in class DeviceCommons
Returns:
serial number

setEndpointReference

public void setEndpointReference(EndpointReference endpoint)
Sets the EndpointReference of this device. The endpoint reference bears a stable globally-unique identifier of the device. This address part is typically not a physical address.
If not set, the framework generates it automatically. The address part of the endpoint reference can be configured via the Properties.

Specified by:
setEndpointReference in interface LocalDevice
Parameters:
endpoint - The endpoint reference to set.

setPortTypes

public void setPortTypes(QNameSet qnsPortTypes)
Sets the port types of the device. This port types should show clients in the network which services the device may hold. Clients (see DefaultClient) can search for the specific device port types.

The port types are communicated via the hello, probe matches, resolve matches, get response and the get metadata response messages (the "wsdd:Types" elements and the be "dpws:Types" elements of host metadata).

The "dpws:Device" port type is added by default.

Specified by:
setPortTypes in interface LocalDevice
Parameters:
qnsPortTypes - Device port types to set.

setScopes

public void setScopes(ScopeSet scopes)
Sets a list of scopes. Scopes are used within the discovery of devices. A client may search for devices with specific scopes.
Scopes are part of the hello, probe matches, resolve matches messages.

Setting the scopes includes getting the exclusive lock ((Lockable ) of the device.
If the device is running, each change will initiate the sending of a hello message with an incremented metadata version. To combine multiple device data changes with sending only one hello, the exclusive lock has to be obtained through exclusiveLock(). After the last device data change, releasing the exclusive lock with releaseExclusiveLock() will send a single hello with an incremented metadata version.

Specified by:
setScopes in interface LocalDevice
Parameters:
scopes - List of scopes to set.

addManufacturer

public void addManufacturer(java.lang.String lang,
                            java.lang.String manufacturer)
Adds manufacturer name to the device which is used as value of the "dpws:Manufacturer" element in the model metadata. The manufacturer name is language specific.

Adding the manufacturer name includes getting the exclusive lock (( Lockable) for the device.
If the device is running, each change will initiate the sending of a hello message with an incremented metadata version. To combine multiple device data changes with sending only one hello, the exclusive lock has to be obtained through exclusiveLock(). After the last device data change, releasing the exclusive lock with releaseExclusiveLock() will send a single hello with an incremented metadata version.

Parameters:
lang - Language attribute, i. e. "en-US or "de-DE":
  • The syntax of the language tags is described in RFC 5646.
  • All language subtags are registered to the IANA Language Subtag Registry.
  • All region subtags are specified in "ISO 3166: Codes for Country Names".
manufacturer - The manufacturer name to set in the specified language.

setManufacturerUrl

public void setManufacturerUrl(java.lang.String manufacturerUrl)
Sets the url of the manufacturer. It used as the value of the "dpws:ManufacturerUrl" element of the model metadata.

Setting the manufacturer url includes getting the exclusive lock (( Lockable) for the device.
If the device is running, each change will initiate the sending of a hello message with an incremented metadata version. To combine multiple device data changes with sending only one hello, the exclusive lock has to be obtained through exclusiveLock(). After the last device data change, releasing the exclusive lock with releaseExclusiveLock() will send a single hello with an incremented metadata version.

Specified by:
setManufacturerUrl in interface LocalDevice
Parameters:
manufacturerUrl - The url of the manufacturer to set.

addModelName

public void addModelName(java.lang.String lang,
                         java.lang.String modelName)
Adds a model name to the device. The model name is used as value of the "dpws:ModelName" element in the model metadata. The model name is language specific.

Adding a model name includes getting the exclusive lock (( Lockable) for the device.
If the device is running, each change will initiate the sending of a hello message with an incremented metadata version. To combine multiple device data changes with sending only one hello, the exclusive lock has to be obtained through exclusiveLock(). After the last device data change releasing the exclusive lock with releaseExclusiveLock() will send a single hello with an incremented metadata version.

Parameters:
lang - Language attribute, i. e. "en-US or "de-DE":
  • The syntax of the language tags is described in RFC 5646.
  • All language subtags are registered to the IANA Language Subtag Registry.
  • All region subtags are specified in "ISO 3166: Codes for Country Names".
modelName - The model name to set in the specified language.

setModelNumber

public void setModelNumber(java.lang.String modelNumber)
Sets the model number of the device. The model number is used as value of the "dpws:ModelNumber" element in the model metadata.

Setting the model number includes getting the exclusive lock (( Lockable) for the device.
If the device is running, each change will initiate the sending of a hello message with an incremented metadata version. To combine multiple device data changes with sending only one hello, the exclusive lock has to be obtained throughexclusiveLock(). After the last device data change the release of the exclusive lock by releaseExclusiveLock() will send a single hello with an incremented metadata version.

Specified by:
setModelNumber in interface LocalDevice
Parameters:
modelNumber - The model number of the device to set.

setModelUrl

public void setModelUrl(java.lang.String modelUrl)
Sets the model url of the device. The model url is used as value of the "dpws:ModelUrl" element of the model metadata.

Setting the model url includes getting the exclusive lock (( Lockable) for the device.
If the device is running, each change will initiate the sending of a hello message with an incremented metadata version. To combine multiple device data changes with sending only one hello, the exclusive lock has to be taken by exclusiveLock(). After the last device data change the release of the exclusive lock by releaseExclusiveLock() will send a single hello with an incremented metadata version.

Specified by:
setModelUrl in interface LocalDevice
Parameters:
modelUrl - The model url of the device to set.

setPresentationUrl

public void setPresentationUrl(java.lang.String presentationUrl)
Sets the presentation url of the device. It is used as value of the "dpws:PresentationUrl" element of the model metadata.

Setting the presentation url includes getting the exclusive lock (( Lockable) for the device.
If the device is running, each change will initiate the sending of a hello message with an incremented metadata version. To combine multiple device data changes with sending only one hello, the exclusive lock has to be obtained through exclusiveLock(). After the last device data change releasing the exclusive lock with releaseExclusiveLock() will send a single hello with an incremented metadata version.

Specified by:
setPresentationUrl in interface LocalDevice
Parameters:
presentationUrl - The presentation url to set.

addFriendlyName

public void addFriendlyName(java.lang.String lang,
                            java.lang.String friendlyName)
Adds a friendly name to the device. It is used as the value of the "dpws:FriendlyName" element of the device metadata. The friendly name is language specific.

Adding a friendly name includes getting the exclusive lock (( Lockable) for the device.
If the device is running, each change will initiate the sending of a hello message with an incremented metadata version. To combine multiple device data changes with sending only one hello, the exclusive lock has to be obtained through exclusiveLock(). After the last device data change releasing the exclusive lock with releaseExclusiveLock() will send a single hello with an incremented metadata version.

Specified by:
addFriendlyName in interface LocalDevice
Parameters:
lang - Language attribute, i. e. "en-US or "de-DE":
  • The syntax of the language tags is described in RFC 5646.
  • All language subtags are registered to the IANA Language Subtag Registry.
  • All region subtags are specified in "ISO 3166: Codes for Country Names".
friendlyName - The friendly name of the device in the specified language to be set.

setFirmwareVersion

public void setFirmwareVersion(java.lang.String firmware)
Sets the firmware version to the device. It is used as the value of the "dpws:FirmwareVersion" element of the device metadata.

Setting the firmware version includes getting the exclusive lock (( Lockable) for the device.
If the device is running, each change will initiate the sending of a hello message with an incremented metadata version. To combine multiple device data changes with sending only one hello, the exclusive lock has to be obtained through exclusiveLock(). After the last device data change releasing the exclusive lock with releaseExclusiveLock() will send a single hello with an incremented metadata version.

Specified by:
setFirmwareVersion in interface LocalDevice
Parameters:
firmware - The firmware version of the device to set.

setSerialNumber

public void setSerialNumber(java.lang.String serialNumber)
Sets the serial number of the device. It is used as the value of the "wsdp:SerialNumber" element of the device metadata.

Setting the serial number version includes getting the exclusive lock (( Lockable) for the device.
If the device is running, each change will initiate the sending of a hello message with an incremented metadata version. To combine multiple device data changes with sending only one hello, the exclusive lock has to be obtained through exclusiveLock(). After the last device data change releasing the exclusive lock with releaseExclusiveLock() will send a single hello with an incremented metadata version.

Specified by:
setSerialNumber in interface LocalDevice
Parameters:
serialNumber - The serial number of the device to set.

addService

public void addService(LocalService service)
Adds service to device.

NOTICE: If the device is already running, you must start the service with the start() method, or use the addService(LocalService, boolean) method.

Adding a service to the device includes getting the exclusive lock (( Lockable) for the device.
If the device is running, each change will initiate the sending of a hello message with an incremented metadata version. To combine multiple device data changes with sending only one hello, the exclusive lock has to be obtained through exclusiveLock(). After the last device data change releasing the exclusive lock with releaseExclusiveLock() will send a single hello with an incremented metadata version.

Specified by:
addService in interface LocalDevice
Parameters:
service - service to add to this device.
See Also:
LocalDevice.addService(org.ws4d.java.service.LocalService, boolean)

addService

public void addService(LocalService service,
                       boolean startIfRunning)
                throws java.io.IOException
Adds a service to the device.

Adding a service to the device includes getting the exclusive lock (( Lockable) for the device.
If the device is running, each change will initiate the sending of a hello message with an incremented metadata version. To combine multiple device data changes with sending only one hello, the exclusive lock has to be obtained through exclusiveLock(). After the last device data change, releasing the exclusive lock with releaseExclusiveLock() will send a single hello with an incremented metadata version.

Specified by:
addService in interface LocalDevice
Parameters:
service - service to add to this device.
startIfRunning - true the service is started if the device is already running, false the service has not been not started, we just add it.
Throws:
java.io.IOException

removeService

public void removeService(LocalService service)
Removes service from device. The service will be removed from the device, but won't be stopped.

Removing a service from the device includes getting the exclusive lock (( Lockable) for the device.
If the device is running, each change will initiate the sending of a hello message with an incremented metadata version. To combine multiple device data changes with sending only one hello, the exclusive lock has to be obtained through exclusiveLock(). After the last device data change releasing the exclusive lock with releaseExclusiveLock() will send a single hello with an incremented metadata version.

Specified by:
removeService in interface LocalDevice
Parameters:
service - The service to remove from this device.

removeService

public void removeService(LocalService service,
                          boolean stopIfRunning)
                   throws java.io.IOException
Removes a service from the device. If stopIfRunning is true the service to remove is stopped if running, else not.

Removing a service from the device includes getting the exclusive lock (( Lockable) for the device.
If the device is running, each change will initiate the sending of a hello message with an incremented metadata version. To combine multiple device data changes with sending only one hello, the exclusive lock has to be obtained throughexclusiveLock(). After the last device data change releasing the exclusive lock with releaseExclusiveLock() will send a single hello with an incremented metadata version.

Specified by:
removeService in interface LocalDevice
Parameters:
service - The service to remove from the device.
stopIfRunning - true the service is stopped if the service is running, false just remove.
Throws:
java.io.IOException

setDeviceMetadata

public void setDeviceMetadata(ThisDeviceMData deviceMetadata)
Sets the device metadata of the device. It contains different device metadata and is transmitted to the "dpws:ThisDevice" metadata.

Setting the device metadata includes getting the exclusive lock (( Lockable) for the device.
If the device is running, each change will initiate the sending of a hello message with an incremented metadata version. To combine multiple device data changes with sending only one hello, the exclusive lock has to obtained through exclusiveLock(). After the last device data change, releasing the exclusive lock with releaseExclusiveLock() will send a single hello with an incremented metadata version.

Specified by:
setDeviceMetadata in interface LocalDevice
Parameters:
deviceMetadata -

setMetadataVersion

public void setMetadataVersion(long metadataVersion)
Sets the metadata version of the device. The metadata version is part of some discovery messages of the device. If it is incremented, clients receiving this new metadata version have to update the device's information.

Setting the metadata version includes getting the exclusive lock (( Lockable) for the device.
If the device is running, each change will initiate the sending of a hello message with an incremented metadata version. To combine multiple device data changes with sending only one hello, the exclusive lock has to be obtained through exclusiveLock(). After the last device data change, releasing the exclusive lock with releaseExclusiveLock() will send a single hello with the new metadata version.

Specified by:
setMetadataVersion in interface LocalDevice
Parameters:
metadataVersion - The metadata version to set is of type unsigned int.

setModelMetadata

public void setModelMetadata(ThisModelMData modelMetadata)
Sets the model metadata of the device. It contains different model meta data and is transmitted via the "dpws:ThisModel" metadata.

Setting the model metadata version includes getting the exclusive lock (( Lockable) for the device.
If the device is running, each change will initiate the sending of a hello message with an incremented metadata version. To combine multiple device data changes with sending only one hello, the exclusive lock has to be obtained through exclusiveLock(). After the last device data change releasing the exclusive lock with releaseExclusiveLock() will send a single hello with an incremented metadata version.

Specified by:
setModelMetadata in interface LocalDevice
Parameters:
modelMetadata - The model metadata of the device to set.

getDeviceMetadata

public ThisDeviceMData getDeviceMetadata()

getMetadataVersion

public long getMetadataVersion()
Description copied from interface: Device
Returns metadata version for this device. The metadata version is transmitted via discovery messages.

Specified by:
getMetadataVersion in interface Device
Returns:
metadata version as unsigned integer.

getModelMetadata

public ThisModelMData getModelMetadata()

getServices

public Iterator getServices()
Gets iterator over all services. A service is of type Service.

Specified by:
getServices in interface LocalDevice
Returns:
Iterator over all services of type Service.

getServiceReferences

public Iterator getServiceReferences()
Description copied from interface: Device
Gets iterator over the service references of all services. A service reference is of type ServiceReference.

Specified by:
getServiceReferences in interface Device
Returns:
Iterator over the (@link ServiceReference) of each service of the device.

getServiceReferences

public Iterator getServiceReferences(QNameSet servicePortTypes)
Description copied from interface: Device
Gets iterator over the service reference of the services, which implements all port types specified. A service reference is of type ServiceReference.

Specified by:
getServiceReferences in interface Device
Parameters:
servicePortTypes - The service port types the services must implement, to be returned by its reference.
Returns:
Iterator over the (@link ServiceReferences) to the services of the device, which implements the specified service port types.

addServiceReferences

public void addServiceReferences(DataStructure to,
                                 QNameSet servicePortTypes)
Description copied from interface: Device
Adds service references associated to this device to the data structure to, if they match the service port types given within serviceTypes.

Specified by:
addServiceReferences in interface Device
Parameters:
to - collection to add matching service references to
servicePortTypes - service port types to look for

getServiceReference

public ServiceReference getServiceReference(URI serviceId)
Description copied from interface: Device
Gets service reference by service id of referenced service. Service id is compared as case-sensitive string.

Specified by:
getServiceReference in interface Device
Returns:
service reference, or null if no service matches the service id.

getServiceReference

public ServiceReference getServiceReference(EndpointReference serviceEpr)
Description copied from interface: Device
Get service reference by endpoint reference of referenced service.

Specified by:
getServiceReference in interface Device
Returns:
service reference, or null, if no service matches the service id.

getXAddressInfos

public Iterator getXAddressInfos()
Description copied from interface: Device
Returns a iterator over the transport addresses of this device. The type of the addresses is URI.

Specified by:
getXAddressInfos in interface Device
Returns:
Iterator over transport addresses of type URI.

getDiscoveryData

public DiscoveryData getDiscoveryData()
Description copied from interface: LocalDevice
This will return the discovery data of the local device. Changes to the discovery data must be avoided outside of the local device.

Specified by:
getDiscoveryData in interface LocalDevice
Returns:
this device's discovery data

isUsingDefaultDiscoveryDomains

public boolean isUsingDefaultDiscoveryDomains()
Does the device use the default discovery domains for send multicast discovery messages. If true => hello and bye messages will be sent via the static output domains in Discovery. If false => hello and bye will be sent to this device's explicitly configured domains.

Returns:
If true => hello and bye messages will be sent via the static output domains in Discovery. If false => hello and bye will be sent to this device's configured output domains.

addOutputDiscoveryDomain

public void addOutputDiscoveryDomain(ProtocolDomain domain)
Adds the specified protocol domain to this device. The domain will be used for sending discovery messages (hellos and byes), in case isUsingDefaultDiscoveryDomains() returns false.

Parameters:
domain - the new protocol domain to add to this device
See Also:
isUsingDefaultDiscoveryDomains(), #setUsingDefaultDiscoveryDomains(boolean)

removeOutputDiscoveryDomain

public void removeOutputDiscoveryDomain(ProtocolDomain domain)
Removes a previously added output domain from this device.

Parameters:
domain - the output domain to remove
See Also:
isUsingDefaultDiscoveryDomains(), #setUsingDefaultDiscoveryDomains(boolean)

getDeviceProperties

public DeviceProperties getDeviceProperties()
Gets device configuration properties. The device properties are built up while reading a configuration file/stream by the Properties class.

While constructing this device, the device properties were used to set the device data. Changes of the device data afterwards will not be transmitted to the properties.

Returns:
properties The properties of device created whilst reading the configuration file/stream.

getConfigurationID

public int getConfigurationID()
Gets the configuration id. The configuration id maps to the device properties within the configuration file/stream. The device can be constructed by DefaultDevice(int) which specifies the configuration id. The default id is -1, which doesn't map to any configuration.

Returns:
The configuration id of the device. If it is -1, no configuration id was specified.

deviceMatches

public boolean deviceMatches(QNameSet searchTypes,
                             ProbeScopeSet searchScopes)
Checks if this device matches the searched device port types and scopes. To match the device both the port types and the scopes must be part of the device.

Specified by:
deviceMatches in interface LocalDevice
Parameters:
searchTypes - Searched device port types to match the device.
searchScopes - Searched scopes to match the device.
Returns:
true - if both the given device port types and scopes are part of the device.

setDiscoveryProxy

public void setDiscoveryProxy(boolean isDiscoveryProxy)

isDiscoveryProxy

public boolean isDiscoveryProxy()

setDefaultNamespace

public void setDefaultNamespace(java.lang.String ns)

getDefaultNamespace

public java.lang.String getDefaultNamespace()
Description copied from interface: Device
return the default namespace.

Specified by:
getDefaultNamespace in interface Device
Returns:
default namespace

isValid

public boolean isValid()
Specified by:
isValid in interface Device

invalidate

public void invalidate()
Specified by:
invalidate in interface Device

getGroup

public HTTPGroup getGroup()
Specified by:
getGroup in interface LocalDevice

addUser

public void addUser(HTTPUser user)

addGroup

public void addGroup(HTTPGroup group)

readCustomizeMData

public java.lang.String readCustomizeMData()
Description copied from interface: Device
The method return the metadata that a user has added as String

Specified by:
readCustomizeMData in interface Device
Returns:
String which contains the users metadata
See Also:
Device.readCustomizeMData()

writeCustomizeMData

public void writeCustomizeMData(HashMap metaData)
Description copied from interface: LocalDevice
Add user metadata to a device

Specified by:
writeCustomizeMData in interface LocalDevice
Parameters:
metaData - HashMap which contains the metadata which the user wants to add
See Also:
LocalDevice.writeCustomizeMData(HashMap)

hasCustomizeMData

public boolean hasCustomizeMData()
Description copied from interface: Device
Tagged if a Device has metadata which are added by a user

Specified by:
hasCustomizeMData in interface Device
Returns:
boolean
See Also:
Device.hasCustomizeMData()