org.ws4d.java.service
Class Operation

java.lang.Object
  org.ws4d.java.types.AttributableSupport
      org.ws4d.java.service.OperationCommons
          org.ws4d.java.service.Operation

All Implemented Interfaces:

OperationDescription, Attributable

Direct Known Subclasses:

OperationStub

public abstract class Operation
extends OperationCommons

An operation is an abstraction of executable code. Operations are (together with events) the main parts of a DPWS service implementation.

The actual business logic behind an operation is contained within the invoke(ParameterValue) method. Operation subclasses are required to overwrite it providing the code to be executed when this operation is called.

Before adding an operation to a service, the types of its input and output parameters must be defined in terms of XML Schema constructs like elements, simple types and complex typess. A simple operation with no input and a single string message as its only output parameter could look like:

 Operation myOperation = new Operation() {
 
     public ParameterValue invoke(ParameterValue params)
         throws InvocationException, TimeotException {
         // business logic goes here
         ...
     }
 
 };
 Element message = new Element("message",
     "http://www.example.org/messageService", SchemaUtil.TYPE_STRING);
 myOperation.setOutput(message);
 

Additionally, if an operation's invocation can cause expected (checked) exceptional conditions (errors), they must be declared as faults.

Note: According to WSDL 1.1 Specification, an operation's name is not required to be unique within the scope of its containing port type in order to support overloading. However, when overloading operations, the combination of each one's name, input name and output name must be unique in order to avoid name clashes.

Constructor Summary

Operation()
Creates a new operation instance without specified name.

Operation(java.lang.String name)
Creates a new operation instance with the given name.

Operation(java.lang.String name, QName portType)
Creates a new operation instance with the given local name and portType.

Operation(java.lang.String name, java.lang.String serviceName)
Creates a new operation instance with the given name and the name of the specified service.

Method Summary

int	getType() Returns the transmission type of this operation according to WSDL 1.1 specification.
abstract ParameterValue	invoke(ParameterValue parameterValue) Invokes the operation.
boolean	isOneWay() Returns true if the transmission type of this operation is WSDLOperation.TYPE_ONE_WAY.
boolean	isRequestResponse() Returns true if the transmission type of this operation is WSDLOperation.TYPE_REQUEST_RESPONSE.

Methods inherited from class org.ws4d.java.service.OperationCommons

addCustomComplexType, addFault, addInputParameter, addOutputParameter, clearCustomComplexTypes, createFaultValue, createInputValue, createOutputValue, equals, getCustomComplexTypes, getFault, getFaultAttribute, getFaultAttributes, getFaultCount, getFaults, getInput, getInputAction, getInputAttribute, getInputAttributes, getInputName, getInputParameter, getName, getOutput, getOutputAction, getOutputAttribute, getOutputAttributes, getOutputName, getOutputParameter, getPortType, getService, hasFaultAttributes, hashCode, hasInputAttributes, hasOutputAttributes, isInputActionExtended, isInputActionSet, isInputNameSet, isOutputActionExtended, isOutputActionSet, isOutputNameSet, removeCustomComplexType, removeFault, setExtendedDefaultInputAction, setExtendedDefaultOutputAction, setFaultAttribute, setFaultAttributes, setInput, setInputAction, setInputAttribute, setInputAttributes, setInputName, setInputNameInternal, setOutput, setOutputAction, setOutputAttribute, setOutputAttributes, setOutputName, setOutputNameInternal, setService, toString

Methods inherited from class org.ws4d.java.types.AttributableSupport

getAttribute, getAttributes, hasAttributes, serializeAttributes, setAttribute, setAttribute, setAttributes

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Operation

public Operation(java.lang.String name,
                 QName portType)

Creates a new operation instance with the given local name and portType.

Parameters:

name - the name of the operation; see here for a short description of uniqueness requirements regarding operation names

portType - the qualified port type of the operation

Operation

public Operation()

Creates a new operation instance without specified name.

Operation

public Operation(java.lang.String name)

Creates a new operation instance with the given name.

Parameters:

name -

Operation

public Operation(java.lang.String name,
                 java.lang.String serviceName)

Creates a new operation instance with the given name and the name of the specified service. Namespace default is "http://www.ws4d.or" can be set once in the DefaultDevice (setDefaultNamespace). There is also the possibility to set the namespace for every operation.

Parameters:

name -

Method Detail

getType

public final int getType()

Returns the transmission type of this operation according to WSDL 1.1 specification. The value returned is one of WSDLOperation.TYPE_ONE_WAY or WSDLOperation.TYPE_REQUEST_RESPONSE.

Specified by:

getType in interface OperationDescription

Specified by:

getType in class OperationCommons

Returns:

type the transmission type of this operation

isOneWay

public final boolean isOneWay()

Returns true if the transmission type of this operation is WSDLOperation.TYPE_ONE_WAY. Returns false in any other case.

Returns:

checks whether this is a one-way operation

isRequestResponse

public final boolean isRequestResponse()

Returns true if the transmission type of this operation is WSDLOperation.TYPE_REQUEST_RESPONSE. Returns false in any other case.

Returns:

checks whether this is a request-response operation

invoke

public abstract ParameterValue invoke(ParameterValue parameterValue)
                               throws InvocationException,
                                      TimeoutException

Invokes the operation.

The "business" logic of this operation. This method MUST be implemented by the children classes. This method is the center of the universe!

When implementing this method, an easy way to create a suitable container for the return value for operations with output parameters is provided by method OperationCommons.createOutputValue(). Similarly, clients invoking this operation can create the input parameters to pass to it by means of OperationCommons.createInputValue(). If this operation declares any faults which may occur during invocation, these are indicated by throwing an appropriate InvocationException and including information about the fault within it. In case a particular fault needs user-defined parameters to be provided, creating a value container can be accomplished by OperationCommons.createFaultValue(String) (given the fault's name).

An example implementation of a simple request-response operation could look like:

 public ParameterValue invoke(ParameterValue params)
     throws InvocationException, TimeoutException {
     ... // extract argument values from params and call business logic
     ParameterValue result = createOutputValue(); // create result container
     
     ... // fill-in return value(s) within result
     return result;
 }
 

And here is an example of how to indicate that a faulty condition was discovered during execution by means of a declared fault:

 public ParameterValue invoke(ParameterValue params)
     throws InvocationException, TimeoutException {
     try {
         ... // extract argument values from params and call business logic
     } catch(Exception e) {
         String faultName = ...; // determine type of fault that occurred
         Fault fault = getFault(faultName); // obtain corresponding fault instance
         
         // create container for additional fault information
         ParameterValue additionalFaultDetails = fault.createValue();
         ... // fill-in value(s) within additionalFaultDetails
         
         // create exception and wrap fault and detail data within it
         throw new InvocationException(fault, additionalFaultDetails);
     }
 }
 

Parameters:

parameterValue - a container providing the input parameters of the operation

Returns:

the result of this operation in terms of output parameter value which should be delivered to the caller; in case this is just a one-way operation, this method must return null; returning an empty ParameterValue still means, that an empty response to the caller should be created

Throws:

InvocationException - thrown to indicate that a declared fault occurred during execution of this operation's business logic; clients can extract further fault-related information from this exception, such as user-defined data attached to it

TimeoutException - in case invoking an operation of a remote service times out