org.ws4d.java.service
Class Fault

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

All Implemented Interfaces:

Attributable

public class Fault
extends AttributableSupport

Faults are the web-services correspondents to exceptions from the Java world. They can be declared on Operations or DefaultEventSources just like exceptions may be declared on Java methods. A fault has a name, which must not be null and unique within the scope of the surrounding operation/event, and an action URI corresponding to the wsa:Action property of the fault message within which the fault is sent . The action URI must also not be null and must be unique within the operation. However, when creating a user-defined Fault, it is possible to omit specifying the action URI explicitly as the DPWS framework will provide an auto-generated one in case it was not set prior to adding the fault to an operation/event.

A Fault can also carry user-defined data, just like exceptions can be designed to encapsulate additional state within their instance variables. Within the Fault, this state is described by means of its associated element.

It is important to notice that modifications to a fault are not possible after it has been added to an operation. Calling any of the setter methods at this time will result in IllegalStateExceptions being thrown.

Constructor Summary

Fault(java.lang.String name)
Creates a fault with the given name, which must be unique within the scope of the surrounding operation.

Fault(java.lang.String name, java.lang.String action)
Creates a fault with the given name (must be unique within the scope of the surrounding operation).

Method Summary

ParameterValue	createValue() A shorthand method for creating a suitable data container for this fault's element.
java.lang.String	getAction() Returns the wsa:Action associated to this fault.
Element	getElement() Returns the element of this fault, which defines the type and structure of any user-defined data the fault may contain.
java.lang.String	getName() Returns the name of this Fault.
void	setAction(java.lang.String action) Sets the wsa:Action of this fault.
void	setElement(Element element) Sets the element of this Fault.
java.lang.String	toString()

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

equals, getAttribute, getAttributes, hasAttributes, hashCode, serializeAttributes, setAttribute, setAttribute, setAttributes

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Fault

public Fault(java.lang.String name)

Creates a fault with the given name, which must be unique within the scope of the surrounding operation. The fault will be assigned an auto-generated action when it is added to an operation or event.

Parameters:

name - the name of this fault; unique within the scope of the surrounding operation

Fault

public Fault(java.lang.String name,
             java.lang.String action)

Creates a fault with the given name (must be unique within the scope of the surrounding operation). The action argument should be a URI representing the wsa:Action associated to this fault.

Parameters:

name - the name of the fault; unique within the scope of the surrounding operation

action - the wsa:Action URI of this fault

Method Detail

toString

public java.lang.String toString()

Overrides:

toString in class AttributableSupport

getAction

public java.lang.String getAction()

Returns the wsa:Action associated to this fault.

As Faults are always required to have an action URI associated to them, one will be automatically generated when adding this Fault to an operation or event, if it was not specified explicitly.

Returns:

the action of this fault

setAction

public void setAction(java.lang.String action)

Sets the wsa:Action of this fault. This method may be called only before this Fault is added to an operation or event.

Parameters:

action - the action to set

Throws:

WS4DIllegalStateException - if the fault is currently attached to an operation or an event

getElement

public Element getElement()

Returns the element of this fault, which defines the type and structure of any user-defined data the fault may contain. It can be used to create a suitable ParameterValue container for the actual values when sending messages containing this fault.

Returns:

this fault's element

See Also:

setElement(Element)

setElement

public void setElement(Element element)

Sets the element of this Fault. The element describes the type and contents of a user-defined data structure providing additional information about the fault. Calling this method after having already added this Fault to an operation or event will result in an IllegalStateException being thrown.

Parameters:

element - the element to set

Throws:

WS4DIllegalStateException - if the fault is currently attached to an operation or an event

getName

public java.lang.String getName()

Returns the name of this Fault. This name must be unique within the scope of its surrounding operation or event.

Returns:

this fault's name

createValue

public ParameterValue createValue()

A shorthand method for creating a suitable data container for this fault's element. Technically equivalent to ParameterValue.createElementValue(getElement()).

Returns:

a data container suitable for this fault's element

See Also:

getElement()