...

Start with a WSDL portType, with a fault message defined in terms of a fault elem and generate the Java from that. If you use a tool like wsimport which you'll get a generated Java exception wrappering a fault in the JAX-WS Sec. 2.5 pattern. That's it. The top-down case is a lot simpler.

Bottom-Up (start with Java checked exception)

First, it might not be a best practice to design a remotable interface which throws a technology exception, e.g. java.sql.SQLException. This might be more appropriate for a local interface rather than a coarse-grained remotable interface.

If you're working bottom-up from Java and you have a genuine Java business exception, well, it does get a bit ugly, at least if your exception wrappers fault data (i.e. it wrappers some data like an error code or object which it needs to convey). If your exception only contains a String 'message', then you won't experience the pain.

There are two options:

1. Converts the exception to follow the JAX-WS Section 2.5 pattern (getFaultInfo(), ctor with faultBean as parm)
2. Rely on our Tuscany interpretation/implementation the JAX-WS Sec 3.7 pattern. This basically works the same whether you run a dev-time tool which supports this pattern (like wsgen) or if you leverage the runtime WSDL2Java.

Of these, the first is better, and if you are willing/able to modify your Java business exception in this fashion, you gain the ability to use this exception as part of the client programming model. The downside is it requires developer understanding of the pattern and the ability and effort to modify the exception.

The second option will be used in both the case where the user won't/can't change the exception class and also the case where the user is ignorant of the WSDL mapping.

In either of those two cases, as long as the exception doesn't contain fault data, this will "just work" without any complexity seen by the user. For exceptions with fault data, the data will be handled correctly (or not) field by field. For each exception data field with a public getter/setter (i.e. we will serialize the exception by viewing it as a JavaBean) we will handle the data correctly (and we will lose the data without a getter/setter pair.

Some issues with this second option:

...

• This seems an area for improvement, either by issuing warnings somewhere along the way or if we ever factor the Tuscany J2W functionality into a dev-time tool.

Start From WSDL

<wsdl:types>
    ...
    <element name="errorCode" type="xsd:int"/>
    ...
</wsdl:types>

<wsdl:message name="BadInputMsg">
    <wsdl:part element="tns:errorCode" name="parameters"/>
</wsdl:message>

<wsdl:portType name="GuessAndGreet">
    <wsdl:operation name="sendGuessAndName">
            <wsdl:input.../>
            <wsdl:fault message="tns:BadInputMsg" name="BadInputMsg"/>
 ...

Now generate Java (e.g. with wsimport) according to the JAX-WS Section 2.5 pattern:

Interface

    public Person sendGuessAndName(...) throws BadInputMsg;    

Anchor
topdownexcgen topdownexcgen

Exception wrappering Fault

import javax.xml.ws.WebFault;

@WebFault(name = "errorCode", targetNamespace = "....")
public class BadInputMsg extends Exception
{
    private int faultInfo;

    public BadInputMsg(String message, int faultInfo) {
        super(message);
        this.faultInfo = faultInfo;
    }

    public BadInputMsg(String message, int faultInfo, Throwable cause) {
        super(message, cause);
        this.faultInfo = faultInfo;
    }

    public int getFaultInfo() {
        return faultInfo;
    }
}

Bottom-Up (start with Java checked exception)

First, it might be best to avoid designing a remotable interface which throws a technology exception, e.g. java.sql.SQLException. This might be more appropriate for a local interface rather than a coarse-grained remotable interface.

If you have a genuine Java business exception then things get more complicated, at least if your exception wrappers fault data (i.e. it wrappers some data like an error code or object which it needs to pass back to the client catching the exception).

There are two options:

1. Convert the exception to follow the JAX-WS Section 2.5 pattern.
2. Rely on our Tuscany interpretation/implementation the JAX-WS Sec 3.7 pattern. This basically works the same whether you run a dev-time tool which supports this pattern (like wsgen) or if you leverage the runtime WSDL2Java.

Convert the exception to JAX-WS Section 2.5

If you are willing/able to modify your Java business exception in this fashion, this is probably the better choice. This exception will be more round-trip friendly as well. That is, if you modify the exception to follow the JAX-WS Sec. 2.5 pattern, run a Java->WSDL (e.g. with wsgen), and then do a later WSDL->Java (e.g. with wsimport), the exception should end up looking pretty similar to the one you just modified.

In practice this means you must do three things:

• add constructors which take the fault bean as input parameters
• implement a public getFaultInfo() method which returns the fault bean
• add the @javax.xml.ws.WebFault annotation

See above for an example

This assumes, though, that the user is actually reading the documentation in order to know to do this.

Rely on the JAX-WS Section 3.7 mapping

This second option will be used in the cases:

• when the user won't or can't change the exception class to follow the Sec. 2.5 pattern
• when the user leaves it entirely up to the runtime to map his Java into WSDL (e.g. user declares a <binding.ws> on a service with a wsdl-less deploy)

In either of those two cases, as long as the exception doesn't contain fault data, this will "just work" without any complexity seen by the user.

For exceptions with fault data, the data will be handled correctly (or not) field by field. For each exception data field with a public getter/setter we will handle the data correctly, and we will lose the data without a getter/setter pair. In other words, we will serialize/deserialize the exception by viewing it as a JavaBean.

Some issues with this second option:

• It won't be obvious to a user what the supported pattern is. One exception with fault data (and getter/setter) is handled correctly while another is not. Running wsgen at development time is no help either, since this generates the schema based on the exception's getters without assuring that the corresponding setters exist in order to populate the exception during unmarshalling.
  • This seems an area for improvement, either by issuing warnings somewhere along the way or if we ever factor out the Tuscany J2W functionality into a dev-time tool.
• If you run W2J against the generated WSDL you will end up with a different exception class. So your client/service programming model are different which might confuse the Java-centered programmer. (One positive is the newly generated Java exc should now follow the Sec 2.5 pattern). You might even need to add a JAXB customization to get around some mapping quirks to generate the client, and you might see weird names like MyException_Exception.
• Another issue might be the fact that, although the pattern is outlined in JAX-WS Sec. 3.7, the spec does not go so far as to specify every detail, and maybe other software implementing JAX-WS does things differently. Not a showstopper since only WSDL has to treated interoperably across platforms.

Example - no fault, works OK

Actually the String message is the fault here and it is handled (serialized/deserialized successfully)

public class RealSimpleException extends Exception {
    public RealSimpleException(String message) {
        super(message);
    }
    public RealSimpleException(String message, Throwable cause) {
        super(message, cause);
    }
}

Example - Exception as Java bean, works OK

This works because the String userdata fault has an associated public getter/setter (and the String message is handled as well).

public class TestException extends Exception {

    private String userdata;

    public TestException(String message) {
        super(message);
    }

    public TestException(String message, String userdata) {
        super(message);
        this.userdata = userdata;
    }

    public String getUserdata() {
        return userdata;
    }

    public void setUserdata(String userdata) {
        this.userdata = userdata;
    }

}

Example - Exception doesn't follow pattern, DOES NOT WORK

This does not work because the errorCode fault data does not have a setter. Our runtime is then
not able to figure out how to populate the exception with this piece of fault data. The exception
will still be thrown but WITH DATA LOSS.

package java.sql;

public class SQLException extends Exception ... {
 ...
 public SQLException(String theReason, String theSQLState, int theErrorCode) ...

 public int getErrorCode() 
}

...

Tuscany

TODO - Add some details of which bits of tuscany do what w.r.t databindings, mappings and transformations in typical scenarios, e.g.

...