org.ws4d.java.communication
Interface CommunicationManager

public interface CommunicationManager

The * NEW * communication manager interface.

Field Summary

static java.lang.String

ID_NULL

Method Summary

boolean	addressMatches(URI xAddr, boolean source, ProtocolData protocolData)
ProtocolInfo	createProtocolInfo(int version) Creates an instance of ProtocolInfo according to the given version information.
void	getAutobindings(java.lang.String descriptor, DataStructure bindings) TODO
DataStructure	getAvailableDomains() Returns a data structure containing all domains within the corresponding technology that this communication manager instance provides.
java.lang.String	getCommunicationManagerId() Returns the unique identifier of this communication manager's technology (e.g.
CommunicationUtil	getCommunicationUtil() Returns an utility class for this communication manager.
QNameSet	getDeviceTypes()
DiscoveryBinding	getDiscoveryBindingForDomain(ProtocolDomain domain) Returns a discovery binding for a specified domain.
DiscoveryBinding	getDiscoveryBindingForProtocolData(ProtocolData data)
DataStructure	getDiscoveryBindings() To get a MulticastReceiver to all available Domains.
DataStructure	getDiscoveryDomainForBinding(DiscoveryBinding binding)
void	getProtocolDomains(Iterator bindings, DataStructure domains) TODO
ProtocolInfo	getProtocolInfo() Returns the an instance of ProtocolInfo for this communication manager.
long	getRandomApplicationDelay(int version)
ResourceLoader	getResourceAsStream(URI location) Returns an input stream which allows to read a resource from the given location.
HashSet	getSupportedVersions() Returns a set of supported versions by this communication manager.
void	init() This method will be invoked be the framework during the start up phase.
void	kill() Stops this communication manager immediately, closes all connections and frees any used resources without waiting for.
void	registerDevice(int[] messageTypes, CommunicationBinding binding, IncomingMessageListener listener, HTTPGroup user) Registers the messageListener for receiving incoming messages of the specified messageTypes at the given binding address.
void	registerDeviceReference(int[] messageTypes, DiscoveryBinding binding, IncomingMessageListener listener) Registers the messageListener for receiving incoming messages of the specified messageTypes at the given binding address.
void	registerDiscovery(int[] messageTypes, DiscoveryBinding binding, IncomingMessageListener listener) Registers the messageListener for receiving incoming messages of the specified messageTypes at the given binding address.
URI	registerResource(Resource resource, CommunicationBinding binding, java.lang.String resourcePath, HTTPGroup user) Deploys the given resource so that it can be accessed over the technology that this communication manager instance represents.
void	registerService(int[] messageTypes, CommunicationBinding binding, IncomingMessageListener listener, HTTPGroup user) Registers the messageListener for receiving incoming messages of the specified messageTypes at the given binding address.
void	send(Message message, XAddressInfo targetXAdrInfo, ProtocolDomain domain, ResponseCallback callback) Sends the message as a asynchronous request through the specified domain; any responses (if present) including faults and timeouts will be delivered to the given callback.
void	serializeMessageWithAttachments(Message message, java.lang.String attachmentSep, List attachments, java.io.OutputStream out, ProtocolData pd)
void	start() Starts this communication manager instance.
void	stop() Stops this communication manager as soon as possible, closes all connections and frees any used resources.
boolean	supportsAddressingNamespace(SOAPHeader header, java.lang.String namespace, ProtocolData pd)
void	unregisterDevice(int[] messageTypes, CommunicationBinding binding, IncomingMessageListener listener) Destroys a previously made registration for the given messageTypes, binding and listener.
void	unregisterDeviceReference(int[] messageTypes, DiscoveryBinding binding, IncomingMessageListener listener) Destroys a previously made registration for the given messageTypes, binding and listener.
void	unregisterDiscovery(int[] messageTypes, DiscoveryBinding binding, IncomingMessageListener listener) Destroys a previously made registration for the given messageTypes, binding and listener.
void	unregisterResource(URI deployAddress, CommunicationBinding binding) Removes the previously deployed resource at the given deployAddress from this communication manager.
void	unregisterService(int[] messageTypes, CommunicationBinding binding, IncomingMessageListener listener) Destroys a previously made registration for the given messageTypes, binding and listener.

Field Detail

ID_NULL

static final java.lang.String ID_NULL

Method Detail

init

void init()

This method will be invoked be the framework during the start up phase.

getCommunicationManagerId

java.lang.String getCommunicationManagerId()

Returns the unique identifier of this communication manager's technology (e.g. DPWS, ZigBee, BT, etc.).

Returns:

the unique ID of this communication manager

start

void start()
           throws java.io.IOException

Starts this communication manager instance. This method executes any needed initialization steps so that further calls to other methods such as #register(int[], CommunicationBinding, IncomingMessageListener), #send(Message, ProtocolDomain, ResponseCallback), etc. can operate correctly.

If this communication manager has already been started, this method must not do anything else other than quickly return .

Throws:

java.io.IOException - in case initializing communication failed for some reason; the caller should assume that this communication manager instance is not usable

stop

void stop()

Stops this communication manager as soon as possible, closes all connections and frees any used resources. Any further interactions with this instance like registering listeners or sending messages will result in illegal state exceptions .

If it is necessary to stop the communication manager immediately the kill() method should be used.

WARNING! This method causes the communication manager to loose all of its current state! That is, reactivating the communication manager again after this method has been called will result in having no registrations for incoming messages.

If this communication manager has already been stopped, this method must not do anything else other than quickly return

kill

void kill()

Stops this communication manager immediately, closes all connections and frees any used resources without waiting for. Any further interactions with this instance like registering listeners or sending messages will result in illegal state exceptions .

WARNING! This method causes the communication manager to loose all of its current state! That is, reactivating the communication manager again after this method has been called will result in having no registrations for incoming messages.

If this communication manager has already been stopped, this method must not do anything else other than quickly return

getAvailableDomains

DataStructure getAvailableDomains()

Returns a data structure containing all domains within the corresponding technology that this communication manager instance provides. Domains are technology-specific endpoint designators, e.g. for IP over Ethernet a domain would consist of a network interface name (such as eth0) and an IP address.

Returns:

a data structure with all available domains that this communication manager provides within that technology

registerDevice

void registerDevice(int[] messageTypes,
                    CommunicationBinding binding,
                    IncomingMessageListener listener,
                    HTTPGroup user)
                    throws java.io.IOException,
                           WS4DIllegalStateException

Registers the messageListener for receiving incoming messages of the specified messageTypes at the given binding address. See DPWSMessageConstants for a list of supported DPWS message types.

Parameters:

messageTypes - determines which message types to register to

binding - the binding to register to

listener - the callback to deliver incoming desired messages to

Throws:

java.io.IOException - in case registration failed for some reason, e.g. an address being already in use, etc.

WS4DIllegalStateException - if this communication manager has already been stopped

registerService

void registerService(int[] messageTypes,
                     CommunicationBinding binding,
                     IncomingMessageListener listener,
                     HTTPGroup user)
                     throws java.io.IOException,
                            WS4DIllegalStateException

Registers the messageListener for receiving incoming messages of the specified messageTypes at the given binding address. See DPWSMessageConstants for a list of supported DPWS message types.

Parameters:

messageTypes - determines which message types to register to

binding - the binding to register to

listener - the callback to deliver incoming desired messages to

Throws:

java.io.IOException - in case registration failed for some reason, e.g. an address being already in use, etc.

WS4DIllegalStateException - if this communication manager has already been stopped

registerDiscovery

void registerDiscovery(int[] messageTypes,
                       DiscoveryBinding binding,
                       IncomingMessageListener listener)
                       throws java.io.IOException,
                              WS4DIllegalStateException

Registers the messageListener for receiving incoming messages of the specified messageTypes at the given binding address. See DPWSMessageConstants for a list of supported DPWS message types.

Parameters:

messageTypes - determines which message types to register to

binding - the binding to register to

listener - the callback to deliver incoming desired messages to

Throws:

java.io.IOException - in case registration failed for some reason, e.g. an address being already in use, etc.

WS4DIllegalStateException - if this communication manager has already been stopped

registerDeviceReference

void registerDeviceReference(int[] messageTypes,
                             DiscoveryBinding binding,
                             IncomingMessageListener listener)
                             throws java.io.IOException,
                                    WS4DIllegalStateException

Registers the messageListener for receiving incoming messages of the specified messageTypes at the given binding address. See DPWSMessageConstants for a list of supported DPWS message types.

Parameters:

messageTypes - determines which message types to register to

binding - the binding to register to

listener - the callback to deliver incoming desired messages to

Throws:

java.io.IOException - in case registration failed for some reason, e.g. an address being already in use, etc.

WS4DIllegalStateException - if this communication manager has already been stopped

unregisterDevice

void unregisterDevice(int[] messageTypes,
                      CommunicationBinding binding,
                      IncomingMessageListener listener)
                      throws java.io.IOException,
                             WS4DIllegalStateException

Destroys a previously made registration for the given messageTypes, binding and listener.

Parameters:

messageTypes - determines which message types to remove registration from

binding - the binding to remove

listener - the callback which was previously registered

Throws:

java.io.IOException - in case removing the registration failed for some reason, e.g. this binding was not already registered, etc.

WS4DIllegalStateException - if this communication manager has already been stopped

unregisterService

void unregisterService(int[] messageTypes,
                       CommunicationBinding binding,
                       IncomingMessageListener listener)
                       throws java.io.IOException,
                              WS4DIllegalStateException

Destroys a previously made registration for the given messageTypes, binding and listener.

Parameters:

messageTypes - determines which message types to remove registration from

binding - the binding to remove

listener - the callback which was previously registered

Throws:

java.io.IOException - in case removing the registration failed for some reason, e.g. this binding was not already registered, etc.

WS4DIllegalStateException - if this communication manager has already been stopped

unregisterDiscovery

void unregisterDiscovery(int[] messageTypes,
                         DiscoveryBinding binding,
                         IncomingMessageListener listener)
                         throws java.io.IOException,
                                WS4DIllegalStateException

Destroys a previously made registration for the given messageTypes, binding and listener.

Parameters:

messageTypes - determines which message types to remove registration from

binding - the binding to remove

listener - the callback which was previously registered

Throws:

java.io.IOException - in case removing the registration failed for some reason, e.g. this binding was not already registered, etc.

WS4DIllegalStateException - if this communication manager has already been stopped

unregisterDeviceReference

void unregisterDeviceReference(int[] messageTypes,
                               DiscoveryBinding binding,
                               IncomingMessageListener listener)
                               throws java.io.IOException,
                                      WS4DIllegalStateException

Destroys a previously made registration for the given messageTypes, binding and listener.

Parameters:

messageTypes - determines which message types to remove registration from

binding - the binding to remove

listener - the callback which was previously registered

Throws:

java.io.IOException - in case removing the registration failed for some reason, e.g. this binding was not already registered, etc.

WS4DIllegalStateException - if this communication manager has already been stopped

send

void send(Message message,
          XAddressInfo targetXAdrInfo,
          ProtocolDomain domain,
          ResponseCallback callback)
          throws WS4DIllegalStateException

Sends the message as a asynchronous request through the specified domain; any responses (if present) including faults and timeouts will be delivered to the given callback.

The argument domain has a certain meaning only when sending multicast/broadcast messages; this currently applies to HelloMessages, ByeMessages, ProbeMessages and ResolveMessages. In this case, it specifies the concrete transport technology and optionally, some technology- or protocol-specific interfaces (aka. "domains") over which to send the multicast message. In the case of DPWS, where multicast messages are sent by means of SOAP-over-UDP, the value of this argument could depict a certain network interface (e.g. eth0, pcn0, etc.) or a specific local IP address. This should then be used to send the multicast message. For further information regarding the outgoing interface of multicast messages when using IP multicast, see RFC 1112.

In the concrete case when message is one of HelloMessage, ByeMessage or SubscriptionEndMessage, the value of callback is ignored. In any other case it is expected to have a non-null value.

Parameters:

message - the request message to send

domain - protocol domain over which to send the message

callback - where to deliver responses to the message

Throws:

WS4DIllegalStateException - if this communication manager has already been stopped

registerResource

URI registerResource(Resource resource,
                     CommunicationBinding binding,
                     java.lang.String resourcePath,
                     HTTPGroup user)
                     throws java.io.IOException,
                            WS4DIllegalStateException

Deploys the given resource so that it can be accessed over the technology that this communication manager instance represents. The resource is made available over the addressing information provided by the specified binding and additional resource-specific addressing information found in resourcePath. Returns an URI depicting the actual address the resource is bound to.

Parameters:

resource - the resource to deploy

binding - a binding over which to make the resource available

resourcePath - additional addressing-related information for use when binding the resource

Returns:

actual address the resource is bound to

Throws:

java.io.IOException - in case binding the resource failed for some reason, e.g. an address being already in use, etc.

WS4DIllegalStateException - if this communication manager has already been stopped

unregisterResource

void unregisterResource(URI deployAddress,
                        CommunicationBinding binding)
                        throws java.io.IOException,
                               WS4DIllegalStateException

Removes the previously deployed resource at the given deployAddress from this communication manager.

Parameters:

deployAddress - the addressing at which the resource previously was #registerResource(Resource, CommunicationBinding, String)

Throws:

java.io.IOException - in case removing the resource failed for some reason, e.g. the resource was not previously deployed, etc.

WS4DIllegalStateException - if this communication manager has already been stopped

getResourceAsStream

ResourceLoader getResourceAsStream(URI location)
                                   throws java.io.IOException

Returns an input stream which allows to read a resource from the given location.

Parameters:

location - the location of the resource (e.g. http://example.org/test.wsdl).

Returns:

an input stream for the given resource.

Throws:

java.io.IOException

addressMatches

boolean addressMatches(URI xAddr,
                       boolean source,
                       ProtocolData protocolData)

Parameters:

xAddr - a protocol dependent transport address

source - if true, the given URI xAddr is compared against the source address of the specified protocolData, otherwise against the destination address

protocolData - protocol data instance associated with a certain incoming message

Returns:

true only if the given protocolData has a source or destination address matching the specified xAddr URI

getAutobindings

void getAutobindings(java.lang.String descriptor,
                     DataStructure bindings)
                     throws java.io.IOException

TODO

Parameters:

descriptor -

bindings -

Throws:

java.io.IOException

getProtocolDomains

void getProtocolDomains(Iterator bindings,
                        DataStructure domains)
                        throws java.io.IOException

TODO

Parameters:

bindings -

domains -

Throws:

java.io.IOException

getDiscoveryBindings

DataStructure getDiscoveryBindings()
                                   throws java.io.IOException

To get a MulticastReceiver to all available Domains.

Throws:

java.io.IOException

getDiscoveryBindingForDomain

DiscoveryBinding getDiscoveryBindingForDomain(ProtocolDomain domain)
                                              throws java.io.IOException

Returns a discovery binding for a specified domain.

Parameters:

domain - specified domain.

Returns:

Binding.

Throws:

java.io.IOException - If the Domain does not fit.

getDiscoveryDomainForBinding

DataStructure getDiscoveryDomainForBinding(DiscoveryBinding binding)
                                           throws java.io.IOException

Throws:

java.io.IOException

getDiscoveryBindingForProtocolData

DiscoveryBinding getDiscoveryBindingForProtocolData(ProtocolData data)

serializeMessageWithAttachments

void serializeMessageWithAttachments(Message message,
                                     java.lang.String attachmentSep,
                                     List attachments,
                                     java.io.OutputStream out,
                                     ProtocolData pd)
                                     throws java.io.IOException

Throws:

java.io.IOException

getProtocolInfo

ProtocolInfo getProtocolInfo()

Returns the an instance of ProtocolInfo for this communication manager.

Returns:

the protocol info.

createProtocolInfo

ProtocolInfo createProtocolInfo(int version)

Creates an instance of ProtocolInfo according to the given version information.

Parameters:

version - the version the protocol info should be created for.

Returns:

the protocol info for the given version.

getSupportedVersions

HashSet getSupportedVersions()

Returns a set of supported versions by this communication manager.

This should be a set containing Integer objects with the version number.

Returns:

a set of supported versions.

getCommunicationUtil

CommunicationUtil getCommunicationUtil()

Returns an utility class for this communication manager.

Returns:

the utility class for this communication manager.

getRandomApplicationDelay

long getRandomApplicationDelay(int version)

supportsAddressingNamespace

boolean supportsAddressingNamespace(SOAPHeader header,
                                    java.lang.String namespace,
                                    ProtocolData pd)
                                    throws VersionMismatchException

Throws:

VersionMismatchException

getDeviceTypes

QNameSet getDeviceTypes()