org.ws4d.java.service
Interface LocalDevice

All Superinterfaces:

Bindable, Device, Lockable

All Known Implementing Classes:

DefaultDevice

public interface LocalDevice
extends Device, Bindable, Lockable

Interface of local devices.

Method Summary

void	addFriendlyName(java.lang.String lang, java.lang.String friendlyName) Adds a friendly name to the device.
void	addService(LocalService service) Adds service to device.
void	addService(LocalService service, boolean startIfRunning) Adds a service to the device.
boolean	deviceMatches(QNameSet searchTypes, ProbeScopeSet searchScopes) Checks if the outer device matches the searched device port types and scopes.
DiscoveryData	getDiscoveryData() This will return the discovery data of the local device.
HTTPGroup	getGroup()
Iterator	getServices() Get iterator over all services.
boolean	isRunning() Returns if the device was started and is running now.
void	removeService(LocalService service) Removes service from device.
void	removeService(LocalService service, boolean stopIfRunning) Removes a service from the device.
void	sendBye() Send Bye Message.
void	sendHello() Send hello message.
void	setDeviceMetadata(ThisDeviceMData deviceMetadata) Sets the device metadata of the device.
void	setEndpointReference(EndpointReference endpoint) Set the EndpointReference of this device.
void	setFirmwareVersion(java.lang.String firmware) Sets the firmware version to the device.
void	setManufacturerUrl(java.lang.String manufacturerUrl) Set 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	start() Starts the device.
void	stop() Stops the device.
void	writeCustomizeMData(HashMap metaData) Add user metadata to a device

Methods inherited from interface org.ws4d.java.service.Device

addServiceReferences, getCertificate, getDefaultNamespace, getDeviceReference, getEndpointReference, getFirmwareVersion, getFriendlyName, getFriendlyNames, getManufacturer, getManufacturers, getManufacturerUrl, getMetadataVersion, getModelName, getModelNames, getModelNumber, getModelUrl, getPortTypes, getPresentationUrl, getPrivateKey, getScopes, getSerialNumber, getServiceReference, getServiceReference, getServiceReferences, getServiceReferences, getXAddressInfos, hasCustomizeMData, invalidate, isRemote, isSecure, isValid, readCustomizeMData, setCertificate, setPrivateKey, setSecureDevice

Methods inherited from interface org.ws4d.java.communication.Bindable

addBinding, clearBindings, getBindings, hasBindings, removeBinding, supportsBindingChanges

Methods inherited from interface org.ws4d.java.concurrency.Lockable

exclusiveLock, releaseExclusiveLock, releaseSharedLock, sharedLock, tryExclusiveLock, trySharedLock

Method Detail

getDiscoveryData

DiscoveryData getDiscoveryData()

This will return the discovery data of the local device. Changes to the discovery data must be avoided outside of the local device.

Returns:

this device's discovery data

isRunning

boolean isRunning()

Returns if the device was started and is running now.

Returns:

true, if this device is running

stop

void stop()
          throws java.io.IOException

Stops the device. Stopping the device will:

• stop its services,
• unbind each CommunicationBinding to the matching CommunicationManager,
• unregisters the device from the DeviceServiceRegistry.

Throws:

java.io.IOException - is thrown, if a binding couldn't be unbound or if stopping one service will throw the exception.

start

void start()
           throws java.io.IOException

Starts the device. Starting the device will:

• start its services,
• bind each CommunicationBinding to the matching CommunicationManager, i.e. start listening on incoming messages for the specified address,
• registers the device to the DeviceServiceRegistry.

Throws:

java.io.IOException - is thrown, if a binding couldn't be bind to the communication manager or if starting one service will throw the exception.

deviceMatches

boolean deviceMatches(QNameSet searchTypes,
                      ProbeScopeSet searchScopes)

Checks if the outer 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.

Parameters:

searchTypes - Searched device port types to match the outer device.

searchScopes - Searched scopes to match the outer device.

Returns:

true - if both the given device port types and scopes are part of the device.

sendHello

void sendHello()

Send hello message. Simple method to announce the device in the network.

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

sendBye

void sendBye()

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

setEndpointReference

void setEndpointReference(EndpointReference endpoint)

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

Parameters:

endpoint - The endpoint reference to set.

setPortTypes

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 bear. Clients 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.

Parameters:

qnsPortTypes - Device port types to set.

setScopes

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 ) to 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 Lockable.exclusiveLock(). After the last device data change the release of the exclusive lock by Lockable.releaseExclusiveLock() will send a single hello with an incremented metadata version.

Parameters:

scopes - List of scopes to set.

setManufacturerUrl

void setManufacturerUrl(java.lang.String manufacturerUrl)

Set the url of the manufacturer. It used as value in the "dpws:ManufacturerUrl" element of the model metadata.

Setting the manufacturer url includes getting the exclusive lock (( Lockable) to 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 Lockable.exclusiveLock(). After the last device data change the release of the exclusive lock by Lockable.releaseExclusiveLock() will send a single hello with an incremented metadata version.

Parameters:

manufacturerUrl - The url of the manufacturer to set.

setModelNumber

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) to 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 Lockable.exclusiveLock(). After the last device data change the release of the exclusive lock by Lockable.releaseExclusiveLock() will send a single hello with an incremented metadata version.

Parameters:

modelNumber - The model number of the device to set.

setModelUrl

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) to 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 Lockable.exclusiveLock(). After the last device data change the release of the exclusive lock by Lockable.releaseExclusiveLock() will send a single hello with an incremented metadata version.

Parameters:

modelUrl - The model url of the device to set.

setPresentationUrl

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) to 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 Lockable.exclusiveLock(). After the last device data change the release of the exclusive lock by Lockable.releaseExclusiveLock() will send a single hello with an incremented metadata version.

Parameters:

presentationUrl - The presentation url to set.

addFriendlyName

void addFriendlyName(java.lang.String lang,
                     java.lang.String friendlyName)

Adds a friendly name to the device. It is used as 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) to 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 Lockable.exclusiveLock(). After the last device data change the release of the exclusive lock by Lockable.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".

friendlyName - The friendly name of the device in the specified language to be set.

setFirmwareVersion

void setFirmwareVersion(java.lang.String firmware)

Sets the firmware version to the device. It is used as value of the "dpws:FirmwareVersion" element of the device metadata.

Setting the firmware version includes getting the exclusive lock (( Lockable) to 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 Lockable.exclusiveLock(). After the last device data change the release of the exclusive lock by Lockable.releaseExclusiveLock() will send a single hello with an incremented metadata version.

Parameters:

firmware - The firmware version of the device to set.

setSerialNumber

void setSerialNumber(java.lang.String serialNumber)

Sets the serial number of the device. It is used as value of the "wsdp:SerialNumber" element of the device metadata.

Set the serial number version includes getting the exclusive lock (( Lockable) to 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 Lockable.exclusiveLock(). After the last device data change the release of the exclusive lock by Lockable.releaseExclusiveLock() will send a single hello with an incremented metadata version.

Parameters:

serialNumber - The serial number of the device to set.

addService

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) to 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 Lockable.exclusiveLock(). After the last device data change the release of the exclusive lock by Lockable.releaseExclusiveLock() will send a single hello with an incremented metadata version.

Parameters:

service - service to add to this device.

See Also:

addService(org.ws4d.java.service.LocalService, boolean)

addService

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) to 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 Lockable.exclusiveLock(). After the last device data change the release of the exclusive lock by Lockable.releaseExclusiveLock() will send a single hello with an incremented metadata version.

Parameters:

service - service to add to this device.

startIfRunning - true the service is started if the device is already running, false the service is not started, we just add it.

Throws:

java.io.IOException

removeService

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) to 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 Lockable.exclusiveLock(). After the last device data change the release of the exclusive lock by Lockable.releaseExclusiveLock() will send a single hello with an incremented metadata version.

Parameters:

service - The service to remove from this device.

removeService

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) to 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 Lockable.exclusiveLock(). After the last device data change the release of the exclusive lock by Lockable.releaseExclusiveLock() will send a single hello with an incremented metadata version.

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

void setDeviceMetadata(ThisDeviceMData deviceMetadata)

Sets the device metadata of the device. It contains different device metadata and is transmitted in the "dpws:ThisDevice" metadata.

Setting the device metadata includes getting the exclusive lock (( Lockable) to 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 Lockable.exclusiveLock(). After the last device data change the release of the exclusive lock by Lockable.releaseExclusiveLock() will send a single hello with an incremented metadata version.

Parameters:

deviceMetadata -

setMetadataVersion

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 informations of the device.

Setting the metadata version includes getting the exclusive lock (( Lockable) to 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 Lockable.exclusiveLock(). After the last device data change the release of the exclusive lock by Lockable.releaseExclusiveLock() will send a single hello with the new metadata version.

Parameters:

metadataVersion - The metadata version to set is from type unsigned int.

setModelMetadata

void setModelMetadata(ThisModelMData modelMetadata)

Sets the model metadata of the device. It contains different model meta data and is transmitted in the "dpws:ThisModel" metadata.

Setting the model metadata version includes getting the exclusive lock (( Lockable) to 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 Lockable.exclusiveLock(). After the last device data change the release of the exclusive lock by Lockable.releaseExclusiveLock() will send a single hello with an incremented metadata version.

Parameters:

modelMetadata - The model metadata of the device to set.

getServices

Iterator getServices()

Get iterator over all services. A service is of type Service.

Returns:

Iterator over all services of type Service.

writeCustomizeMData

void writeCustomizeMData(HashMap metaData)

Add user metadata to a device

Parameters:

metaData - HashMap which contains the metadata which the user wants to add

getGroup

HTTPGroup getGroup()