You can implement exceptions for remotable interfaces in the Service Component Architecture (SCA) environment to provide additional flow of control for error conditions to meet the needs of your business application.
To develop SCA service implementations, you can use either a top-down development approach starting with an existing Web Services Description Language (WSDL) file or you can use a bottom-up development approach starting from an existing Java interface or implementation. When using either the top-down or bottom-up development methodologies, you can use tools to map business exceptions on remotable interfaces.
In order to achieve the SOA goal of providing an interoperable platform that is both language and technology neutral, the SCA runtime environment takes an XML-centric view of interfaces and data. When working with Java code, the Java API for XML-Based Web Services (JAX-WS) standard is used to define the mapping between Java code and the XML-based Web Services Description Language (WSDL) file. This mapping also includes the Java programming model with respect to exceptions. Exceptions for remotable interfaces in the SCA environment is defined by the JAX-WS specification. This topic describes the best practices for using business exceptions with SCA interfaces.
To better understand the implications of implementing business exceptions in an SCA environment, it is helpful to understand differences between an exception and a fault bean.
The JAX-WS specification distinguishes between a checked exception and the fault bean that it wrappers. However, this distinction might not be clear because a single class can serve the checked exception and the fault bean functions, especially when you use the bottom-up approach of developing an SCA service starting with a Java interface. When you use the top-down development approach of developing an SCA service starting with a WSDL file, section 2.5 of the JAX-WS specification describes the wrapper pattern for how the fault message maps to a Java checked exception that wrappers a fault bean. The fault bean maps to the fault element and in SCA environments, the mapping is defined by Java Architecture for XML Binding (JAXB) data binding. The fault bean represents the cross-platform view of the fault message data and includes a schema description. You can use the Java exception within the Java runtime environment and as part of the Java programming model. However, the exception is not part of the interoperable data representation.
When developing SCA services using the bottom-up approach, the distinction between an exception, the fault bean, and the mapping from Java to WSDL or XSD schema is clear if you follow the wrapper pattern described in section 2.5 of the JAX-WS specification. If you have existing Java exceptions, use the standard mapping defined in section 3.7 of the JAX-WS specification for service specific exceptions. In SCA environments, these service specific exceptions are referred to as business exceptions. The mapping for the business exceptions is different than the mapping described in section 2.5 of the JAX-WS specification. Because this wrapper pattern only applies for certain exceptions, this approach has limitations when using the bottom-up development approach. The possible limitations of using the wrapper pattern to implement error handling when using bottom-up development of SCA applications provides additional reasons to consider the advantages of the best practice of top-down development of SCA applications.
It is a best practice to use the top-down methodology to develop SCA service implementations because this approach leverages the capabilities of the XML interface description and provides a greater ease in interoperability across platforms, bindings, and programming languages. A WSDL operation can be defined, along with one or more fault messages, provided each fault message is defined in terms of a fault element. When the wsimport command-line tool is used to generate Java code the tool generates Java exception code that wraps a fault element in the format specified by the Java API for XML-Based Web Services (JAX-WS) specification, section 2.5.
Bottom-up development of SCA services occurs when you start with existing Java code. Using this development approach, do not design a remotable interface that might cause a technology exception such as java.sql.SQLException. This exception is more appropriate for a local interface rather than a coarse-grained remotable interface.
The following examples illustrates using the bottom-up development of SCA applications and using the business exception mapping as described in section 3.7 of the JAX-WS specification.
Example 1: No fault
public class RealSimpleException extends Exception { public RealSimpleException(String message) { super(message); } public RealSimpleException(String message, Throwable cause) { super(message, cause); } }
Example 2: Exception as JavaBeans
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 3: Exception does not follow pattern
package java.sql; public class SQLException extends Exception ... { ... public SQLException(String theReason, String theSQLState, int theErrorCode) ... public int getErrorCode() }
Increase portability of your exception classes in top-down development
One issue that you might encounter with Java exceptions generated from WSDL in the top-down manner is that the fault bean might not be Java-serializable. In other words, the fault bean might not implement java.io.Serializable. This does not present a problem if the bindings that your application uses are in XML wireformat because, in that scenario, XML serialization is used instead of Java serialization. However, XML serialization limits the usefulness of your exception class. Therefore, it might not be suitable to use with SCA binding configurations using a wireformat with Java serialization, or in other contexts in which Java serialization is used to serialize and deserialize an exception.
To avoid this limitation, annotate your schema definition for the fault element type with a JAXB customization designed for this purpose. When this customization is present, the JAXB type that is generated, that corresponds to the fault bean, is marked as implementing the java.io.Serializable interface, and is therefore Java serializable, in addition to being serializable to XML, because the class is also still a conforming JAXB type.
Example:
<schema targetNamespace="http://com.mycompany/banking/" jaxb:version="2.0" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" xmlns="http://www.w3.org/2001/XMLSchema"> <annotation> <appinfo> <jaxb:globalBindings> <jaxb:serializable uid="1"/> </jaxb:globalBindings> </appinfo> </annotation> <!-- Continue with the rest of the schema definition--> </schema>
SCA programming tip for binding neutrality
The JAX-WS defined mapping between exceptions in Java and an XML wireformat relies on the use of the fault bean to pass back data from the service provider throwing the exception to the client that is catching it. Normal Java-centric mechanisms, such as exception chaining, are not preserved in mapping between the Java application and the wire. Therefore, the best way to write application code that can be used across binding configurations using either of a Java serialization wireformat or an XML wireformat is to rely exclusively on the fault bean for communicating useful application level data relating to the exception.
Even though using a chained exception across a binding that uses a Java-serialization based wireformat works fine, using a chained exception across a binding using XML wireformat might not work. Therefore relying on a chained exception would not be a recommended practice in an SCA environment, because SCA strives to provide a binding-neutral programming model.
In this information ... | IBM Redbooks, demos, education, and more(Index) |