org.ws4d.java.service
Class DefaultService

java.lang.Object
  extended by org.ws4d.java.service.ServiceCommons
      extended by org.ws4d.java.service.DefaultService
All Implemented Interfaces:
Bindable, LocalService, Service

public class DefaultService
extends ServiceCommons
implements LocalService

Default implementation of a DPWS service.

This class should be used to create a DPWS service. A new service should extend the DefaultService class and add operations to the newly created service. It is also possible to use the default implementation.

 
 
 
 
 
 
 
 
 public class SampleService extends DefaultService {
 
        public SampleService() {
                // create operations here, add them to the service
        }
 }
 


Nested Class Summary
 
Nested classes/interfaces inherited from class org.ws4d.java.service.ServiceCommons
ServiceCommons.OperationSignature, ServiceCommons.PortType
 
Constructor Summary
DefaultService()
          Default DPWS service.
DefaultService(int configurationId)
          Default DPWS service with given configuration identifier.
 
Method Summary
 void addBinding(CommunicationBinding binding)
          Adds the given binding to this Bindable.
 void addEventSource(EventSource event)
          Add an event to this service.
 void addGroup(HTTPGroup group)
           
 void addOperation(Operation operation)
          Add an operation to this service.
 void addPortType(QName portTypeName)
          Add a port type (name) to this service.
 void addUser(HTTPUser user)
           
 void clearBindings()
          Removes all bindings from this Bindable instance.
 void define(URI wsdlUri)
          Enables dynamic service creation from an existing WSDL description.
 void define(WSDL wsdl)
          Enables dynamic service creation from an existing WSDL description.
 EventSource getAnyEventSource(QName portType, java.lang.String eventName)
          Returns the first (or last, or ANY other) event source with the specified portType and eventName.
 Operation getAnyOperation(QName portType, java.lang.String operationName)
          Returns the first (or last, or ANY other) operation with the specified portType and operationName.
 Iterator getBindings()
          Returns an iterator over all bindings assigned to this Bindable instance.
 int getConfigurationID()
          Gets configuration identifier.
 WSDL getDescription(java.lang.String targetNamespace)
          Returns a WSDL document describing this service by the given namespace.
 Iterator getDescriptionsForPortTypes()
          Returns an iterator containing all WSDL documents describing this service.
 Iterator getEprInfos()
          Returns an iterator of EprInfo.
 EventSource getEventSource(QName portType, java.lang.String eventName, java.lang.String inputName, java.lang.String outputName)
          Gets event source of specified portType with given eventName.
 EventSource getEventSource(java.lang.String outputAction)
          Gets event source with specified unique outputAction.
 Iterator getEventSources()
          Gets all events sources.
 Iterator getEventSources(QName portType)
          Gets all event sources of the specified service port type.
 Operation getOperation(QName portType, java.lang.String opName, java.lang.String inputName, java.lang.String outputName)
          Gets an operation of specified portType with given opName.
 Operation getOperation(java.lang.String inputAction)
          Gets operation with specified unique inputAction.
 Iterator getOperations()
          Gets all operations.
 Iterator getOperations(QName portType)
          Gets all operations of the specified service port type.
 DeviceReference getParentDeviceReference()
          Gets device reference of parent device.
 Iterator getPortTypes()
          Gets service port types.
 URI getServiceId()
          Gets service id
 ServiceReference getServiceReference()
          Gets the service reference.
 long getStatus(ClientSubscription subscription)
          Returns the duration in milliseconds until expiration of the specified client subscription.
 Iterator getTargetNamespaces()
          Returns the namespaces based on the port types for this service.
 boolean hasBindings()
          Returns true only if this Bindable instance has at least one binding assigned.
 boolean isRemote()
          Is the service remote (proxy) or local?
 boolean isRunning()
          Returns true, if this local service is currently in the running state.
 void pause()
          Pauses service.
 boolean removeBinding(CommunicationBinding binding)
          Removes the specified binding from this Bindable instance.
 long renew(ClientSubscription subscription, long duration)
          Renews an existing subscription with a new duration.
 void setParentDevice(LocalDevice device)
          Sets the parent device for this service.
 void setServiceId(URI serviceId)
          Sets the service identifier for this service.
 void start()
          Starts this service.
 void stop()
          Stops this service.
 ClientSubscription subscribe(EventSink sink, java.lang.String clientSubscriptionId, URISet eventActionURIs, long duration)
          Initializes event receiving from specified event sender.
 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.
 void unsubscribe(ClientSubscription subscription)
          Unsubscribe specified subscription.
 
Methods inherited from class org.ws4d.java.service.ServiceCommons
getCertificate, getDescriptions, getPortTypeAttribute, getPortTypeAttributes, getPrivateKey, hasPortTypeAttributes, isSecure, setCertificate, setPortTypeAttribute, setPortTypeAttributes, setPrivateKey, setSecure, setSecureService, toString
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.ws4d.java.service.Service
getCertificate, getDescriptions, getPortTypeAttribute, getPortTypeAttributes, hasPortTypeAttributes, isSecure, setCertificate, setSecure
 

Constructor Detail

DefaultService

public DefaultService()
Default DPWS service.

No configuration identifier used. No configuration will be loaded for this service.


DefaultService

public DefaultService(int configurationId)
Default DPWS service with given configuration identifier.

Creates an default DPWS service and tries to load the configuration properties for the service.

Parameters:
configurationId - configuration identifier.
Method Detail

start

public void start()
           throws java.io.IOException
Description copied from interface: LocalService
Starts this service. Registers service within dispatcher.

Specified by:
start in interface LocalService
Throws:
java.io.IOException

stop

public void stop()
          throws java.io.IOException
Description copied from interface: LocalService
Stops this service. Unregisters service in device service registry.

Specified by:
stop in interface LocalService
Throws:
java.io.IOException

pause

public void pause()
Description copied from interface: LocalService
Pauses service. After calling this, subsequent incoming requests to this service will result in a "ServiceNotAvailable" fault.

Specified by:
pause in interface LocalService

isRunning

public boolean isRunning()
Description copied from interface: LocalService
Returns true, if this local service is currently in the running state. Returns false otherwise.

Specified by:
isRunning in interface LocalService
Returns:
whether this local service is currently running or not

getServiceReference

public ServiceReference getServiceReference()
Description copied from interface: Service
Gets the service reference.

Specified by:
getServiceReference in interface Service
Returns:
service reference

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

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

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

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

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

isRemote

public boolean isRemote()
Description copied from interface: Service
Is the service remote (proxy) or local?

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

getServiceId

public URI getServiceId()
Description copied from interface: Service
Gets service id

Specified by:
getServiceId in interface Service
Returns:
service id

getOperations

public Iterator getOperations()
Description copied from interface: Service
Gets all operations.

Specified by:
getOperations in interface Service
Overrides:
getOperations in class ServiceCommons
Returns:
all operations

getOperations

public Iterator getOperations(QName portType)
Description copied from interface: Service
Gets all operations of the specified service port type.

Specified by:
getOperations in interface Service
Overrides:
getOperations in class ServiceCommons
Parameters:
portType - specific port type
Returns:
the operations belonging to the specified port type

getOperation

public Operation getOperation(QName portType,
                              java.lang.String opName,
                              java.lang.String inputName,
                              java.lang.String outputName)
Description copied from interface: Service
Gets an operation of specified portType with given opName. The inputName and/or outputName may be null only if the requested operation doesn't have any input/output. Otherwise, this method won't get any results.

When an operation is added to a service, and it doesn't provide an explicit name for either its input or output elements (see OperationCommons.setInputName(String) and OperationCommons.setOutputName(String)), a default name is generated according to the WSDL 1.1 Specification. As long as there are other operations with the same input/output name which have already been added to this service, an incremental index is appended to the default generated name.

If you are certain that the operation of the specified portType and with the given opName is NOT overloaded (i.e. there is no other operation within the same port type with the same operation name), then you can use method Service.getAnyOperation(QName, String) instead of this one.

Specified by:
getOperation in interface Service
Overrides:
getOperation in class ServiceCommons
Parameters:
portType - specific port type of operation
opName - name of operation
inputName - the name of the input element which belongs to this operation according to its WSDL; must be null, if operation has no input
outputName - the name of the output element which belongs to this operation according to its WSDL; must be null, if operation has no output
Returns:
requested operation or null, if not found
See Also:
Service.getAnyOperation(QName, String)

getOperation

public Operation getOperation(java.lang.String inputAction)
Description copied from interface: Service
Gets operation with specified unique inputAction.

Specified by:
getOperation in interface Service
Overrides:
getOperation in class ServiceCommons
Parameters:
inputAction - the WS-Addressing action URI of the requested operation according to its WSDL
Returns:
requested operation or null, if not found

getAnyOperation

public Operation getAnyOperation(QName portType,
                                 java.lang.String operationName)
Description copied from interface: Service
Returns the first (or last, or ANY other) operation with the specified portType and operationName. Note that there might be more than one operation with the same name and port type in the case of overloading. In such situations, it is the user's responsibility to determine which of the overloaded versions was returned by this method. This method returns null, if there are no operations matching the portType and operationName arguments.

This method is useful in case it is known that there is only one operation with a given name within a port type.

Specified by:
getAnyOperation in interface Service
Overrides:
getAnyOperation in class ServiceCommons
Parameters:
portType - the port type to which the desired operation
operationName - the name of the operation
Returns:
any (maybe randomly determined) operation with the given port type and name
See Also:
Service.getOperation(QName, String, String, String)

getEventSources

public Iterator getEventSources()
Description copied from interface: Service
Gets all events sources.

Specified by:
getEventSources in interface Service
Overrides:
getEventSources in class ServiceCommons
Returns:
all event sources

getEventSources

public Iterator getEventSources(QName portType)
Description copied from interface: Service
Gets all event sources of the specified service port type.

Specified by:
getEventSources in interface Service
Overrides:
getEventSources in class ServiceCommons
Parameters:
portType - specific port type
Returns:
all event sources belonging to the specified service port type

getEventSource

public EventSource getEventSource(QName portType,
                                  java.lang.String eventName,
                                  java.lang.String inputName,
                                  java.lang.String outputName)
Description copied from interface: Service
Gets event source of specified portType with given eventName. The inputName and/or outputName may be null only if the requested event source doesn't have any input/output. Otherwise, this method won't find any results. *

When an event source is added to a service, and it doesn't provide an explicit name for either its input or output elements (see OperationCommons.setInputName(String) and OperationCommons.setOutputName(String)), a default name is therefore generated according to the WSDL 1.1 Specification. If there are other event sources with the same input/output name already added to this service, an incremental index is appended to the default generated name.

If you are certain that the event source of the specified portType and with the given eventName is NOT overloaded (i.e. there is no other event source within the same port type with the same event name), then you can use method Service.getAnyEventSource(QName, String) instead of this one.

Specified by:
getEventSource in interface Service
Overrides:
getEventSource in class ServiceCommons
Parameters:
portType - specific port type of operation
eventName - name of event source
inputName - the name of the input element that belongs to this event source according to its WSDL; must be null, if event source has no input
outputName - the name of the output element that belongs to this event source according to its WSDL; must be null, if event source has no output
Returns:
requested event source or null, if not found
See Also:
Service.getAnyEventSource(QName, String)

getEventSource

public EventSource getEventSource(java.lang.String outputAction)
Description copied from interface: Service
Gets event source with specified unique outputAction.

Specified by:
getEventSource in interface Service
Overrides:
getEventSource in class ServiceCommons
Parameters:
outputAction - the WS-Addressing action URI of the requested event source according to its WSDL
Returns:
requested event or null if not found

getAnyEventSource

public EventSource getAnyEventSource(QName portType,
                                     java.lang.String eventName)
Description copied from interface: Service
Returns the first (or last, or ANY other) event source with the specified portType and eventName. Note that there might be more than one event source with the same name and port type in the case of overloading. In such situations, it is the user's responsibility to determine which of the overloaded versions was returned by this method. This method returns null, if there are no event source matching the portType and eventName arguments.

This method is useful in case it is known that there is only one event source with a given name within a port type.

Specified by:
getAnyEventSource in interface Service
Overrides:
getAnyEventSource in class ServiceCommons
Parameters:
portType - the port type the desired event source belongs to
eventName - the name of the event source
Returns:
any (maybe randomly determined) event source with the given port type and name
See Also:
Service.getEventSource(QName, String, String, String)

setServiceId

public void setServiceId(URI serviceId)
Sets the service identifier for this service.

The service identifier identifies the service uniquely for the parent device.

Parameters:
serviceId - the service identifier to set.

getPortTypes

public Iterator getPortTypes()
Description copied from interface: Service
Gets service port types.

Specified by:
getPortTypes in interface Service
Returns:
service port types, data structure is read only.

addPortType

public void addPortType(QName portTypeName)
Description copied from interface: LocalService
Add a port type (name) to this service. The port type will initially be empty, i.e. it will contain neither event sources, nor any operations.

Specified by:
addPortType in interface LocalService
Parameters:
portTypeName - the name of the port type to add.

getEprInfos

public Iterator getEprInfos()
Description copied from interface: Service
Returns an iterator of EprInfo.

Specified by:
getEprInfos in interface Service
Returns:
an iterator of EprInfo.

addOperation

public void addOperation(Operation operation)
Description copied from interface: LocalService
Add an operation to this service.

Specified by:
addOperation in interface LocalService
Parameters:
operation - operation to add.

addEventSource

public void addEventSource(EventSource event)
Description copied from interface: LocalService
Add an event to this service.

Specified by:
addEventSource in interface LocalService
Parameters:
event - event to add.

getConfigurationID

public int getConfigurationID()
Gets configuration identifier.

The configuration identifier is necessary to resolve properties based configuration.

Returns:
the configuration identifier.

setParentDevice

public void setParentDevice(LocalDevice device)
Sets the parent device for this service.

Every service is assigned to one device.

Specified by:
setParentDevice in interface LocalService
Parameters:
devicet - the device which the service should be assigned to.

getParentDeviceReference

public DeviceReference getParentDeviceReference()
Description copied from interface: Service
Gets device reference of parent device. This method may return null in case this service doesn't reside on a device or its underlying device is not known at this time.

Specified by:
getParentDeviceReference in interface Service
Returns:
device reference of parent device, may be null

getTargetNamespaces

public Iterator getTargetNamespaces()
Returns the namespaces based on the port types for this service.

Returns:
the namespaces based on the port types for this service.

getDescriptionsForPortTypes

public Iterator getDescriptionsForPortTypes()
Description copied from interface: LocalService
Returns an iterator containing all WSDL documents describing this service.

Specified by:
getDescriptionsForPortTypes in interface LocalService
Returns:
an iterator containing all WSDL documents describing this service, i.e. those containing port types of the service.

getDescription

public WSDL getDescription(java.lang.String targetNamespace)
Returns a WSDL document describing this service by the given namespace.

Specified by:
getDescription in interface Service
Parameters:
targetNamespace - the namespace.
Returns:
the WSDL document describing this service by the given namespace.

define

public void define(URI wsdlUri)
            throws java.io.IOException
Enables dynamic service creation from an existing WSDL description.

This method analyzes the WSDL loaded from wsdlUri and adds all supported port types found to this service. For each supported operation (i.e. either one-way or request-response transmission types), an instance of class OperationStub is created and added, whereas for each event source (aka. notification or solicit-response transmission types) an instance of class DefaultEventSource is added.

The actual business logic of imported one-way or request-response operations can be specified on the corresponding OperationStub instance after having obtained it from this service via one of the getOperation(...) methods like this:

 DefaultService myService = ...;
 myService.define("http://www.example.org/myService/description.wsdl");
 
 InvokeDelegate myDelegate = ...;
 
 Operation myOp = (OperationStub) myService.getOperation("http://www.example.org/MyServicePortType/MyOperation");
 myOp.setDelegate(myDelegate);
 
The InvokeDelegate instance above defines the actual code to be executed when the myOperation gets called. Its InvokeDelegate.invoke(Operation, ParameterValue) method receives the parameters sent to the operation, as well as the operation instance itself. The latter is useful for implementors who want to share a single InvokeDelegate instance between different operations.

Note that the cast to OperationStub above is only safe if the operation being obtained was actually created via a call to this define(URI) method - in any other case, e.g. when it was added manually by means of addOperation(Operation), this cast will most likely result in a java.lang.ClassCastException.

Parameters:
wsdlUri - URI pointing to the location of the WSDL document to define this service from; the URI may have an arbitrary schema (e.g. file, http, https, etc.) as long as there is runtime support available for accessing it within the DPWS framework, see DPWSFramework.getResourceAsStream(URI)
Throws:
java.io.IOException - if a failure occurs while attempting to obtain the WSDL from the given URI

define

public void define(WSDL wsdl)
            throws java.io.IOException
Enables dynamic service creation from an existing WSDL description.

This method analyzes the WSDL loaded from wsdlUri and adds all supported port types found to this service. For each supported operation (i.e. either one-way or request-response transmission types), an instance of class OperationStub is created and added, whereas for each event source (aka. notification or solicit-response transmission types) an instance of class DefaultEventSource is added.

The actual business logic of imported one-way or request-response operations can be specified on the corresponding OperationStub instance after having obtained it from this service via one of the getOperation(...) methods like this:

 DefaultService myService = ...;
 myService.define("http://www.example.org/myService/description.wsdl");
 
 InvokeDelegate myDelegate = ...;
 
 Operation myOp = (OperationStub) myService.getOperation("http://www.example.org/MyServicePortType/MyOperation");
 myOp.setDelegate(myDelegate);
 
The InvokeDelegate instance above defines the actual code to be executed when the myOperation gets called. Its InvokeDelegate.invoke(Operation, ParameterValue) method receives the parameters sent to the operation, as well as the operation instance itself. The latter is useful for implementors who want to share a single InvokeDelegate instance between different operations.

Note that the cast to OperationStub above is only safe if the operation being obtained was actually created via a call to this define(URI) method - in any other case, e.g. when it was added manually by means of addOperation(Operation), this cast will most likely result in a java.lang.ClassCastException.

Parameters:
wsdl - the WSDL object which should be used to define the serivce.
Throws:
java.io.IOException - if a failure occurs while attempting to obtain the WSDL from the given URI

subscribe

public ClientSubscription subscribe(EventSink sink,
                                    java.lang.String clientSubscriptionId,
                                    URISet eventActionURIs,
                                    long duration)
                             throws EventingException,
                                    TimeoutException
Description copied from interface: Service
Initializes event receiving from specified event sender.

Specified by:
subscribe in interface Service
Parameters:
sink - event sink which will receive the notifications.
eventActionURIs - a set of action URIs to subscribe to
duration - duration in millis of subscription. If 0, subscription does not expire.
Returns:
subscription id (wse:identifier)
Throws:
EventingException
TimeoutException

unsubscribe

public void unsubscribe(ClientSubscription subscription)
                 throws EventingException,
                        TimeoutException
Description copied from interface: Service
Unsubscribe specified subscription.

Specified by:
unsubscribe in interface Service
Parameters:
subscription - subscription to terminate.
Throws:
EventingException
TimeoutException

renew

public long renew(ClientSubscription subscription,
                  long duration)
           throws EventingException,
                  TimeoutException
Description copied from interface: Service
Renews an existing subscription with a new duration. If duration is "0", subscription never terminates.

Specified by:
renew in interface Service
Throws:
EventingException
TimeoutException

getStatus

public long getStatus(ClientSubscription subscription)
               throws EventingException,
                      TimeoutException
Description copied from interface: Service
Returns the duration in milliseconds until expiration of the specified client subscription.

Specified by:
getStatus in interface Service
Returns:
Throws:
EventingException
TimeoutException

addUser

public void addUser(HTTPUser user)

addGroup

public void addGroup(HTTPGroup group)