org.ws4d.java.service
Class OperationCommons

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

All Implemented Interfaces:

OperationDescription, Attributable

Direct Known Subclasses:

DefaultEventSource, Operation

public abstract class OperationCommons
extends AttributableSupport
implements OperationDescription

This class is the common base for both Operations and DefaultEventSources within the DPWS framework. It contains all common properties for WSDL 1.1 compliant operations. It is further used to declare an operation's or event's input and output parameters as well as any faults that may occur on invocation. Overall in this class' documentation, the term "operation" is used to mean either an actual operation or an event.

Note: According to WSDL 1.1 Specification, an operation's 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.

Method Summary

void	addCustomComplexType(ComplexType type) This method adds a custom xsd:ComplexType to the operation.
void	addFault(Fault fault) Adds the given fault to this operation.
void	addInputParameter(java.lang.String parameterName, Type type) Adds an input parameter with the given parameterName and of the specified type to this operation.
void	addOutputParameter(java.lang.String parameterName, Type type) Adds an output parameter with the given parameterName and of the specified type to this operation.
void	clearCustomComplexTypes() Clears the list of custom types.
ParameterValue	createFaultValue(java.lang.String faultName) This method creates a parameter value container for the fault with the given unique faultName (within the scope of this operation).
ParameterValue	createInputValue() This is a shorthand method for creating a parameter value container for the input of this operation.
ParameterValue	createOutputValue() This is a shorthand method for creating a parameter value container for the output of this operation.
boolean	equals(java.lang.Object obj)
Iterator	getCustomComplexTypes() Returns an iterator containing ComplexType.
Fault	getFault(java.lang.String faultName) Returns this operation's fault with the given faultName, which is considered to be unique within the operation's scope.
CustomAttributeValue	getFaultAttribute(java.lang.String faultName, QName attributeName) Returns the value of the fault attribute with the given name for the fault with the specified unique faultName or null, either if this attribute is not available (or if its value is actually explicitly set to null).
HashMap	getFaultAttributes(java.lang.String faultName) Returns all fault attributes explicitly set on this instance for the fault with the given unique faultName.
int	getFaultCount() Returns the number of declared faults for this operation.
Iterator	getFaults() Returns an Iterator over all faults declared for this operation.
Element	getInput() Returns the input element of this operation.
java.lang.String	getInputAction() Returns the WS-Addressing [action] property for the input message of this operation.
CustomAttributeValue	getInputAttribute(QName attributeName) Returns the value of the input attribute with the given name or null if this attribute is not available (or if its value is explicitly set to null).
HashMap	getInputAttributes() Returns all input attributes explicitly set on this instance.
java.lang.String	getInputName() Returns the name of this operation's input.
Element	getInputParameter(java.lang.String parameterName) TODO
java.lang.String	getName() Returns the local name of this operation.
Element	getOutput() Returns the output element of this operation.
java.lang.String	getOutputAction() Returns the WS-Addressing [action] property for the output message of this operation.
CustomAttributeValue	getOutputAttribute(QName attributeName) Returns the value of the output attribute with the given name or null, if this attribute is not available (or if its value is actually explicitly set to null).
HashMap	getOutputAttributes() Returns all output attributes explicitly set on this instance.
java.lang.String	getOutputName() Returns the name of this operation's output.
Element	getOutputParameter(java.lang.String parameterName) TODO
QName	getPortType() Returns the port type that this operation belongs to.
Service	getService() Returns the service to which this operation is associated.
abstract int	getType() Returns the transmission type of this operation according to WSDL 1.1 specification.
boolean	hasFaultAttributes(java.lang.String faultName) Returns true only if this instance has at least one fault attribute set for the fault with the specified unique faultName.
int	hashCode()
boolean	hasInputAttributes() Returns true only if this instance has at least one input attribute set.
boolean	hasOutputAttributes() Returns true only if this instance has at least one output attribute set.
boolean	isInputActionExtended()
boolean	isInputActionSet()
boolean	isInputNameSet()
boolean	isOutputActionExtended()
boolean	isOutputActionSet()
boolean	isOutputNameSet()
void	removeCustomComplexType(ComplexType type) Remove a given custom xsd:ComplexType from the operation.
void	removeFault(java.lang.String faultName) Removes the fault with the given faultName from this operation.
java.lang.String	setExtendedDefaultInputAction()
java.lang.String	setExtendedDefaultOutputAction()
void	setFaultAttribute(java.lang.String faultName, QName attributeName, CustomAttributeValue value) Sets the value for the fault attribute with the specified name of the fault with the given unique faultName.
void	setFaultAttributes(java.lang.String faultName, HashMap attributes) Sets at once all fault attributes of the fault with unique faultName to those contained within argument attributes.
void	setInput(Element element) Sets the input of this operation.
void	setInputAction(java.lang.String inputAction) Sets the WS-Addressing [action] property for this operation's input message
void	setInputAttribute(QName attributeName, CustomAttributeValue value) Sets the value for the input attribute with the specified name.
void	setInputAttributes(HashMap attributes) Sets all input attributes at once to those contained within argument attributes.
void	setInputName(java.lang.String inputName) Sets the name of this operation's input.
void	setInputNameInternal(java.lang.String inputName) This method doesn't toggle the inputNameSet flag
void	setOutput(Element element) Sets the output of this operation.
void	setOutputAction(java.lang.String outputAction) Sets the WS-Addressing [action] property for this operation's output message.
void	setOutputAttribute(QName attributeName, CustomAttributeValue value) Sets the value of the output attribute with the specified name.
void	setOutputAttributes(HashMap attributes) Sets all output attributes at once to those contained within argument attributes.
void	setOutputName(java.lang.String outputName) Sets the name of this operation's output.
void	setOutputNameInternal(java.lang.String outputName) This method doesn't toggle the outputNameSet flag
void	setService(Service service)
java.lang.String	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

Method Detail

toString

public java.lang.String toString()

Overrides:

toString in class AttributableSupport

equals

public final boolean equals(java.lang.Object obj)

Overrides:

equals in class AttributableSupport

hashCode

public final int hashCode()

Overrides:

hashCode in class AttributableSupport

getName

public java.lang.String getName()

Returns the local name of this operation. See note on overloading operations.

Specified by:

getName in interface OperationDescription

Returns:

the local name of this operation

getPortType

public QName getPortType()

Returns the port type that this operation belongs to.

Specified by:

getPortType in interface OperationDescription

Returns:

this operation's port type

getType

public abstract 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, WSDLOperation.TYPE_REQUEST_RESPONSE, WSDLOperation.TYPE_NOTIFICATION and WSDLOperation.TYPE_SOLICIT_RESPONSE.

Specified by:

getType in interface OperationDescription

Returns:

the transmission type of this operation

getInputName

public java.lang.String getInputName()

Returns the name of this operation's input. If this operation doesn't have any input (i.e. its transmission type is WSDLOperation.TYPE_NOTIFICATION, null is returned. Otherwise, if no input name was previously set, a default input name is generated according to WSDL 1.1 Specification.

Specified by:

getInputName in interface OperationDescription

Returns:

this operation's input name

See Also:

setInputName(String)

setInputName

public void setInputName(java.lang.String inputName)

Sets the name of this operation's input. See note on overloading operations.

Parameters:

inputName - the new input name to set

Throws:

WS4DIllegalStateException - if this instance is already added to a service

See Also:

getInputName()

getInputAction

public java.lang.String getInputAction()

Returns the WS-Addressing [action] property for the input message of this operation. Will return null only if this operation's transmission type is WSDLOperation.TYPE_NOTIFICATION, i.e. the operation doesn't have any input. Otherwise, if no input action was explicitly set, this method will generate a default one according to the rules of WS-Addressing 1.0 - WSDL Binding.

Specified by:

getInputAction in interface OperationDescription

Returns:

the WS-Addressing [action] property of this operation's input

See Also:

setInputAction(String)

setInputAction

public void setInputAction(java.lang.String inputAction)

Sets the WS-Addressing [action] property for this operation's input message

Parameters:

inputAction - the new [action] to set; must be an absolute URI

Throws:

WS4DIllegalStateException - if this instance is already added to a service

See Also:

getInputAction()

getOutputName

public java.lang.String getOutputName()

Returns the name of this operation's output. If this operation doesn't have any output (i.e. its transmission type is WSDLOperation.TYPE_ONE_WAY, null is returned. Otherwise, if no output name was previously set a default output name is generated according to WSDL 1.1 Specification.

Specified by:

getOutputName in interface OperationDescription

Returns:

this operation's output name

See Also:

setOutputName(String)

setOutputName

public void setOutputName(java.lang.String outputName)

Sets the name of this operation's output. See note on overloading operations.

Parameters:

outputName - the new output name to set

Throws:

WS4DIllegalStateException - if this instance is already added to a service

See Also:

getOutputName()

getOutputAction

public java.lang.String getOutputAction()

Returns the WS-Addressing [action] property for the output message of this operation. Will return null only if this operation's transmission type is WSDLOperation.TYPE_ONE_WAY, i.e. the operation doesn't have any output. Otherwise, if no output action is explicitly set, this method will generate a default one according to the rules of WS-Addressing 1.0 - WSDL Binding.

Specified by:

getOutputAction in interface OperationDescription

Returns:

the WS-Addressing [action] property of this operation's output

See Also:

setOutputAction(String)

setOutputAction

public void setOutputAction(java.lang.String outputAction)

Sets the WS-Addressing [action] property for this operation's output message.

Parameters:

outputAction - the new [action] to set; must be an absolute URI

Throws:

WS4DIllegalStateException - if this instance has already been added to a service

See Also:

getOutputAction()

getInput

public Element getInput()

Returns the input element of this operation. The input element defines the data structure for the input parameters of this operation. It can be used to create a suitable ParameterValue container for the actual values when sending messages to the operation.

Specified by:

getInput in interface OperationDescription

Returns:

the input element

See Also:

setInput(Element)

getInputParameter

public Element getInputParameter(java.lang.String parameterName)

TODO

Parameters:

parameterName -

Returns:

setInput

public void setInput(Element element)

Sets the input of this operation. This element is assumed to contain all input parameters of this operation.

Parameters:

element - the input element

See Also:

getInput()

addInputParameter

public void addInputParameter(java.lang.String parameterName,
                              Type type)

Adds an input parameter with the given parameterName and of the specified type to this operation. This method creates a wrapper element of a complex type with a single top-most container of type ComplexType.CONTAINER_SEQUENCE and uses this as input of the operation. The wrapper element's name is equal to this operation's name. This conforms to the document-literal wrapped style binding for SOAP 1.2. The new parameter is then appended to the end of the sequence container of the wrapper element.

NOTE: Using this method is only possible when the input element for this operation was NOT previously set by a call to setInput(Element). Otherwise, this method will throw a WS4DIllegalStateException.

Parameters:

parameterName - the name of the input parameter to add

type - the type for the new input parameter

Throws:

WS4DIllegalStateException - if an input element was previously set on this operation

getOutput

public Element getOutput()

Returns the output element of this operation. The output element defines the data structure for the output parameters of this operation. It can be used to create a suitable ParameterValue container for the actual values an operation returns.

Specified by:

getOutput in interface OperationDescription

Returns:

the output element

See Also:

setOutput(Element)

getOutputParameter

public Element getOutputParameter(java.lang.String parameterName)

TODO

Parameters:

parameterName -

Returns:

setOutput

public void setOutput(Element element)

Sets the output of this operation. This element is assumed to contain all output parameters of this operation.

Parameters:

element - the output element

See Also:

getOutput()

addOutputParameter

public void addOutputParameter(java.lang.String parameterName,
                               Type type)

Adds an output parameter with the given parameterName and of the specified type to this operation. This method creates a wrapper element of a complex type with a single top-most container of type ComplexType.CONTAINER_SEQUENCE and uses this as output of the operation. The wrapper element's name is equal to this operation's name with a 'Response' suffix appended to it. This conforms to the document-literal wrapped style binding for SOAP 1.2. The new parameter is then appended to the end of the sequence container of the wrapper element.

NOTE: Using this method is only possible when the output element for this operation was NOT previously set by a call to setOutput(Element). Otherwise, this method will throw a WS4DIllegalStateException.

Parameters:

parameterName - the name of the output parameter to add

type - the type for the new output parameter

Throws:

WS4DIllegalStateException - if an output element was previously set on this operation

getFaults

public Iterator getFaults()

Returns an Iterator over all faults declared for this operation.

Specified by:

getFaults in interface OperationDescription

Returns:

an iterator over this operation's faults

See Also:

addFault(Fault)

getFaultCount

public int getFaultCount()

Description copied from interface: OperationDescription

Returns the number of declared faults for this operation.

Specified by:

getFaultCount in interface OperationDescription

Returns:

the number of declared faults

getFault

public Fault getFault(java.lang.String faultName)

Returns this operation's fault with the given faultName, which is considered to be unique within the operation's scope.

Specified by:

getFault in interface OperationDescription

Parameters:

faultName - the requested fault's name

Returns:

the fault with the given name or null if there is no fault with that name within this operation

See Also:

addFault(Fault), getFaults()

addFault

public void addFault(Fault fault)

Adds the given fault to this operation.

A fault on a web service operation corresponds to a checked declared exception on a Java method. If an operation's invocation causes a fault, the invoking client will receive an InvocationException providing additional information about this fault.

Parameters:

fault - the fault to add

Throws:

java.lang.NullPointerException - if fault is null

java.lang.IllegalArgumentException - if a fault with the given name already exists, as fault names must be unique within the scope of an operation

See Also:

getFaults(), getFault(String)

removeFault

public void removeFault(java.lang.String faultName)

Removes the fault with the given faultName from this operation.

Parameters:

faultName - the name of the fault to remove

See Also:

addFault(Fault), getFault(String)

createOutputValue

public ParameterValue createOutputValue()

This is a shorthand method for creating a parameter value container for the output of this operation. It is semantically equivalent to ParameterValue.createElementValue(getOutput());.

Specified by:

createOutputValue in interface OperationDescription

Returns:

a parameter container suitable for this operation's output

See Also:

getOutput(), ParameterValue.createElementValue(Element)

createInputValue

public ParameterValue createInputValue()

This is a shorthand method for creating a parameter value container for the input of this operation. It is semantically equivalent to ParameterValue.createElementValue(getInput()); .

Specified by:

createInputValue in interface OperationDescription

Returns:

a parameter container suitable for this operation's input

See Also:

getInput(), ParameterValue.createElementValue(Element)

createFaultValue

public ParameterValue createFaultValue(java.lang.String faultName)

This method creates a parameter value container for the fault with the given unique faultName (within the scope of this operation).

Specified by:

createFaultValue in interface OperationDescription

Parameters:

faultName - the name of the fault to create a parameter container for

Returns:

the parameter container suitable for the specified fault

Throws:

java.util.NoSuchElementException - if a fault with the given name is not declared within this operation

See Also:

getFault(String)

getService

public Service getService()

Returns the service to which this operation is associated. May return null, if this operation has yet not been added to a particular service.

Specified by:

getService in interface OperationDescription

Returns:

the service to which this operation belongs

getInputAttribute

public CustomAttributeValue getInputAttribute(QName attributeName)

Returns the value of the input attribute with the given name or null if this attribute is not available (or if its value is explicitly set to null).

Parameters:

attributeName - the name of the input attribute of which to query the value

Returns:

the value for the named input attribute or null

setInputAttribute

public void setInputAttribute(QName attributeName,
                              CustomAttributeValue value)

Sets the value for the input attribute with the specified name. Throws a java.lang.IllegalArgumentException in case name is null.

Parameters:

attributeName - the name of the input attribute to set, must not be null

value - the value to which to set the named input attribute (may be null

Throws:

java.lang.IllegalArgumentException - if name is null

getInputAttributes

public HashMap getInputAttributes()

Returns all input attributes explicitly set on this instance. Note that depending on the actual implementation the returned reference may point at the 'life map', i .e. the actual storage for the input attributes. Modifications to that map should therefore be performed with care and keeping this in mind.

Returns:

all already set input attributes

setInputAttributes

public void setInputAttributes(HashMap attributes)

Sets all input attributes at once to those contained within argument attributes. Note that depending on the actual implementation it is possible that the map attributes points at may be used for the actual internal storage of the input attributes (i.e. without copying it). This is why, after passing it to this method, modifications to this map should be made with care . This method throws a java.lang.IllegalArgumentException in case attributes is null.

Parameters:

attributes - the new input attributes to set

Throws:

java.lang.IllegalArgumentException - if attributes is null

hasInputAttributes

public boolean hasInputAttributes()

Returns true only if this instance has at least one input attribute set. Returns false in any other case.

Returns:

true only if there is at least one input attribute set within this instance

getOutputAttribute

public CustomAttributeValue getOutputAttribute(QName attributeName)

Returns the value of the output attribute with the given name or null, if this attribute is not available (or if its value is actually explicitly set to null).

Parameters:

attributeName - the name of the output attribute to query the value of

Returns:

the value for the named output attribute or null

setOutputAttribute

public void setOutputAttribute(QName attributeName,
                               CustomAttributeValue value)

Sets the value of the output attribute with the specified name. Throws a java.lang.IllegalArgumentException in case name is null.

Parameters:

attributeName - the name of the output attribute to set, must not be null

value - the value to set the named output attribute to (may be null

Throws:

java.lang.IllegalArgumentException - if name is null

getOutputAttributes

public HashMap getOutputAttributes()

Returns all output attributes explicitly set on this instance. Note that depending on the actual implementation the returned reference may point at the 'life map', i .e. the actual storage for the output attributes. Thus, modifications to that map should be performed with care and with this in mind.

Returns:

all already set output attributes

setOutputAttributes

public void setOutputAttributes(HashMap attributes)

Sets all output attributes at once to those contained within argument attributes. Note that depending on the actual implementation it is possible that the map attributes points at may be used for the actual internal storage of the output attributes (i.e. without copying it). That is why modifications to this map should be made with care after passing it to this method. This method throws a java.lang.IllegalArgumentException in case attributes is null.

Parameters:

attributes - the new output attributes to set

Throws:

java.lang.IllegalArgumentException - if attributes is null

hasOutputAttributes

public boolean hasOutputAttributes()

Returns true only if this instance has at least one output attribute set. Returns false in any other case.

Returns:

true only if there is at least one output attribute set within this instance

getFaultAttribute

public CustomAttributeValue getFaultAttribute(java.lang.String faultName,
                                              QName attributeName)

Returns the value of the fault attribute with the given name for the fault with the specified unique faultName or null, either if this attribute is not available (or if its value is actually explicitly set to null).

This method throws a java.lang.IllegalArgumentException if a fault with the given faultName is not found within this instance.

Parameters:

faultName - the unique name of the fault within the scope of this instance, see getFault(String)

attributeName - the name of the fault attribute to query the value of

Returns:

the value for the named fault attribute or null

Throws:

java.lang.IllegalArgumentException - if no fault with the given faultName is found

setFaultAttribute

public void setFaultAttribute(java.lang.String faultName,
                              QName attributeName,
                              CustomAttributeValue value)

Sets the value for the fault attribute with the specified name of the fault with the given unique faultName. Throws a java.lang.IllegalArgumentException in case there is no fault with the given faultName within this instance or if name is null.

Parameters:

faultName - the unique name of the fault within the scope of this instance, see getFault(String)

attributeName - the name of the fault attribute to set, must not be null

value - the value to set the named fault attribute to (may be null

Throws:

java.lang.IllegalArgumentException - if there is no fault with the given faultName within this instance or if name is null

getFaultAttributes

public HashMap getFaultAttributes(java.lang.String faultName)

Returns all fault attributes explicitly set on this instance for the fault with the given unique faultName. Note that depending on the actual implementation the returned reference may point at the 'life map', i .e. the actual storage for the fault attributes. Thus, modifications to that map should be performed with care and keeping this in mind.

This method throws a java.lang.IllegalArgumentException if a fault with the given faultName is not found within this instance.

Parameters:

faultName - the unique name of the fault within the scope of this instance, see getFault(String)

Returns:

all already set fault attributes

Throws:

java.lang.IllegalArgumentException - if no fault with the given faultName is found

setFaultAttributes

public void setFaultAttributes(java.lang.String faultName,
                               HashMap attributes)

Sets at once all fault attributes of the fault with unique faultName to those contained within argument attributes. Note that depending on the actual implementation, it is possible that the map attributes points at may be used for the actual internal storage of the fault attributes (i.e. without copying it). That is why, after passing it to this method, modifications to this map should be made with care. This method throws a java.lang.IllegalArgumentException in case attributes is null.

Parameters:

faultName - the unique name of the fault within the scope of this instance, see getFault(String)

attributes - the new fault attributes to set

Throws:

java.lang.IllegalArgumentException - if no fault with the given faultName is found or if attributes is null

hasFaultAttributes

public boolean hasFaultAttributes(java.lang.String faultName)

Returns true only if this instance has at least one fault attribute set for the fault with the specified unique faultName. Returns false in any other case, including when there is no fault with the given faultName.

Parameters:

faultName - the unique name of the fault within the scope of this instance, see getFault(String)

Returns:

true only if there is at least one fault attribute set for the named fault within this instance

setService

public void setService(Service service)

Parameters:

service - the service to set

setInputNameInternal

public void setInputNameInternal(java.lang.String inputName)

This method doesn't toggle the inputNameSet flag

Parameters:

inputName -

setOutputNameInternal

public void setOutputNameInternal(java.lang.String outputName)

This method doesn't toggle the outputNameSet flag

Parameters:

outputName -

setExtendedDefaultInputAction

public java.lang.String setExtendedDefaultInputAction()

setExtendedDefaultOutputAction

public java.lang.String setExtendedDefaultOutputAction()

isInputNameSet

public boolean isInputNameSet()

isInputActionSet

public boolean isInputActionSet()

isOutputNameSet

public boolean isOutputNameSet()

isOutputActionSet

public boolean isOutputActionSet()

isInputActionExtended

public boolean isInputActionExtended()

isOutputActionExtended

public boolean isOutputActionExtended()

addCustomComplexType

public void addCustomComplexType(ComplexType type)

This method adds a custom xsd:ComplexType to the operation. This custom type will be serialized in the WSDL document.

Notice

Do not add custom types with the same name as the types used for input or output definitions. This may overwrite the normal definitions.

The added custom type MUST have a valid name. If no name is set, this method will throw an RuntimeException.

Parameters:

type - the custom type which should be add to the WSDL document.

removeCustomComplexType

public void removeCustomComplexType(ComplexType type)

Remove a given custom xsd:ComplexType from the operation.

Parameters:

type - the custom type which should be removed.

See Also:

addCustomComplexType(ComplexType)

clearCustomComplexTypes

public void clearCustomComplexTypes()

Clears the list of custom types.

See Also:

addCustomComplexType(ComplexType)

getCustomComplexTypes

public Iterator getCustomComplexTypes()

Returns an iterator containing ComplexType. This list contains the custom types set for this operation.

Returns:

an iterator containing ComplexType.

See Also:

addCustomComplexType(ComplexType)