org.ws4d.java.service
Class OperationStub

java.lang.Object
  extended by org.ws4d.java.types.AttributableSupport
      extended by org.ws4d.java.service.OperationCommons
          extended by org.ws4d.java.service.Operation
              extended by org.ws4d.java.service.OperationStub
All Implemented Interfaces:
OperationDescription, Attributable

public class OperationStub
extends Operation

Instances of this class are used during dynamic creation of a service via the method DefaultService.define(org.ws4d.java.types.URI). They provide a way to detach the business logic of an operation from its metadata by means of InvokeDelegate instances.


Constructor Summary
OperationStub(java.lang.String name, QName portType)
          Creates a new operation stub with the given name and port type.
 
Method Summary
 InvokeDelegate getDelegate()
          Returns the current delegate.
 ParameterValue invoke(ParameterValue parameterValue)
          Invokes the operation.
 void setDelegate(InvokeDelegate delegate)
          Sets the delegate which shall receive invocation requests from this operation.
 
Methods inherited from class org.ws4d.java.service.Operation
getType, isOneWay, isRequestResponse
 
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

OperationStub

public OperationStub(java.lang.String name,
                     QName portType)
Creates a new operation stub with the given name and port type.

Parameters:
name - the name of the operation
portType - the name of the port type to which this operation belongs
Method Detail

invoke

public ParameterValue invoke(ParameterValue parameterValue)
                      throws InvocationException,
                             TimeoutException
Description copied from class: Operation
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);
     }
 }
 

Specified by:
invoke in class Operation
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

getDelegate

public InvokeDelegate getDelegate()
Returns the current delegate. Returns null if either none set or explicitly set to null.

Returns:
the delegate the current delegate instance or null

setDelegate

public void setDelegate(InvokeDelegate delegate)
Sets the delegate which shall receive invocation requests from this operation. If delegate is null, a default one will be installed, which throws an InvocationException with a code of SOAPConstants.SOAP_FAULT_SENDER and a subcode of WS4DConstants.WS4D_FAULT_NOT_IMPLEMENTED. However, calling the method getDelegate() afterwards will return null instead of this default InvokeDelegate.

Parameters:
delegate - the delegate to set or null to fall back to a default implementation throwing an InvocationException with a code of SOAPConstants.SOAP_FAULT_SENDER and a subcode of WS4DConstants.WS4D_FAULT_NOT_IMPLEMENTED on each call to invoke(ParameterValue)