Java-to-XML Marshalling

While JAX-RPC does not define the actual marshalling mechanism, it does define the input and output types that result from that marshalling. Vendors write the marshalling code as part of their implementations.

In JAX-RPC, marshalling is different from the standard Java serialization mechanism, where all nontransient fields in the class are automatically serialized. JAX-RPC defines a standard set of Java types as method arguments and return types, meaning that a JAX-RPC—compliant system will provide the ready-to-use serializers and deserializers for these types:

1. All Java primitives, with the exception of a char (int, float, long, short, double, byte, Boolean). A char is treated as a String, since XML schemas have no char type primitive (see Appendix A).

2. An object that is an instance of

   • java.lang.String

   • java.util.Date

   • java.util.Calendar

   • java.math.BigInteger

   • java.math.BigDecimal

3. An object that is an instance of a class that conforms to the following restrictions:

   • It should conform to the JavaBean specification, so that its variables can be easily accessed.

   • It should not be a Remote object (i.e., should not implement java.rmi.Remote).

   • It should have a default no arguments constructor.

   These are important, because any other class is passed between the client and the server. For example, if a java.util.Map of com.flutebank.Account objects must be passed from the client to the server, a pluggable serializer and deserializer pair must be written. This is explored later in this chapter.

4. An array (with the caveat that it must contain bytes or a supported type)

5. A java.lang.Exception class

JAX-RPC does not support a pass by reference mode for parameters and does not support passing of remote objects, because both the SOAP 1.1 and SOAP 1.2 treat objects by reference as out of scope. JAX-RPC mandates support for pass by copy semantics for parameters and return values, similar to the way nonremote objects are passed in RMI.

The above rules differ from the standard Java serialization requirements. Table 10.1 lists the details for the same class to be used across an RMI/RMI-IIOP application as well as a JAX-RPC application. This is relevant where an existing EJB, RMI, or RMI-IIOP object must expose itself directly as a JAX-RPC service and the code must be reused across these interfaces.

Once the parameter types have been defined, rules and a standard mechanism to map these data types from Java to XML must also be defined. JAX-RPC does this, as Table 10.2 shows.

JSR-31 defines the XML Data Binding Specification with JAXB, for converting an XML schema into Java classes. In the future, JAX-RPC will include the data type mapping defined by JAXB.

XML-to-Java Unmarshalling

To invoke a procedure on an object with incoming XML data, an implementation must map XML data types into Java data types. This is identical to Table 10.2, with some differences explained in Tables 10.3a and 3b. XML type is declared as nillable in the schema, then it maps to its corresponding Java wrapper (primitives in Java cannot be null).

SOAP Bindings and Encoding

In Chapter 4, we looked at SOAP encoding in detail. Encoding refers to how data is serialized and sent over the wire. The parties exchanging messages have to agree on one rule to ensure that both correctly interpret the message sent from the other side. They can either agree beforehand, using a predefined encoding scheme, or use an XML schema directly in the data to define the data types. The message with the former notation is said to be an encoded message; the latter is said to be a literal message.

SOAP encoding refers to the rules defined by the SOAP specification that the parties can follow to interpret the contents of the Body element. SOAP defines an encoding scheme, also referred to as Section 5 encoding (since it is specified in section 5 of the SOAP specifications). It outlines a schema (http://schemas.xmlsoap.org/soap/encoding/) containing certain basic data types that participants in the conversation can use to describe the elements in the body of the SOAP message. This encoding is not mandatory, and there is no default.

In Chapter 4, we also looked at the use of the encodingStyle attribute and the use of simple and compound types. To recall, the encodingStyle attribute in the SOAP message can be used to indicate the encoding in use. For example, the message below indicates that SOAP encodings are in use:

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:enc="http://
schemas.xmlsoap.org/soap/encoding/" xmlns:ns0="http://www.flutebank.com/xml"
env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<env:Body>
<ns0:getLastPayment>
    <vendor xsi:type="enc:string">my cable tv provider</vendor>
</ns0:getLastPayment>
</env:Body>
</env:Envelope>

The message shows that the vendor element is of type enc:string defined in the encoding schema, represented by the encodingStyle attribute. The receiver of this message, processing the vendor element, knows it is a SOAP-encoded string, which it can then translate into the language in which the service is implemented.

The SOAP specification does not define any language bindings for the data types described by its encoding schema. Instead, the types are generic enough to model some of the typical data types found in Java and most other programming languages. JAX-RPC defines how the simple types in the SOAP encoding are mapped to Java, as per Table 10.4.

Note that the data types in Table 10.4 are the same as the nillable types in Table 10.3a, because they map to the same underlying basic XML schema types. Of particular interest is the Array type, which maps to Java arrays. In the previous extract, if the SOAP body contained something like the following, it would be mapped to an array of String[] objects in the Java side by JAX-RPC, and vice versa:

   <complexType name="PaymentConfirmation">
       <sequence>
             <element name="confirmationNum" type="int"/>
             <element name="payee" type="string"/>
             <element name="amt" type="double"/>
       </sequence>
   </complexType>

   public class PaymentConfirmation {
       private int confirmationNum;
       private String payee;
       private double amt;
       public PaymentConfirmation() {
       }

       public PaymentConfirmation(int confirmationNum,
                                 java.lang.String payee, double amt) {
           this.confirmationNum = confirmationNum;
           this.payee = payee;
           this.amt = amt;
       }

   // getXXX/setXXX methods for each member property
   }

   <simpleType name="PaymentDetail" >
       <restriction base="xsd:string" >
           <enumeration value="checking"/>
           <enumeration value="saving"/>
           <enumeration value="brokerage"/>
       </restriction>
   </simpleType>

   public class PaymentDetail implements Serializable {
       private String value;
       public static final String _checkingString = "checking";
       public static final String _savingString = "saving";
       public static final String _brokerageString = "brokerage";

       public static final String _checking = new String
                                        (_checkingString);
       public static final String _saving = new String(_savingString);
       public static final String _brokerage = new String
                                        (_brokerageString);

       public static final PaymentDetail checking =
                                        new PaymentDetail(_checking);
       public static final PaymentDetail saving = new PaymentDetail
                                        (_saving);
       public static final PaymentDetail brokerage =
                                        new PaymentDetail(_brokerage);
       protected PaymentDetail(String value) {
           this.value = value;
       }

       public String getValue() {
           return value;
       }

       public static PaymentDetail fromValue(String value)
           throws IllegalStateException {
           if (checking.value.equals(value)) {
               return checking;
           } else if (saving.value.equals(value)) {
               return saving;
           } else if (brokerage.value.equals(value)) {
               return brokerage;
           }
           throw new IllegalArgumentException();
       }

       public static PaymentDetail fromString(String value)
           throws IllegalStateException {
           if (value.equals(_checkingString)) {
               return checking;
           } else if (value.equals(_savingString)) {
               return saving;
           } else if (value.equals(_brokerageString)) {
               return brokerage;
           }
           throw new IllegalArgumentException();
           }
       }
   // other methods not shown
   }

<ns0:getLastPayment>
<vendor enc:arrayType="xsd:string[4]" xsi:type="enc:Array">
   <item xsi:type="xsd:string">AT&T</item>
   <item xsi:type="xsd:string">Sprint PCS</item>
   <item xsi:type="xsd:string">Flute Electric Co</item>
</vendor>
</ns0:getLastPayment>

While mapping arrays, the type of the array is determined from the schema type. The size is determined at runtime rather than at declaration time. JAX-RPC also supports multidimensional arrays, where the types are supported JAX-RPC types. Listing 10.1 shows how a multidimensional array of application-defined PaymentDetail objects may be mapped on the wire using SOAP encoding:

Listing 10.1: A multidimensional array of application-defined PaymentDetail objects mapped on the wire using SOAP encoding

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:ns0="http://www.flutebank.com/xml"
// other namespaces >
<env:Body>
// other XML
<ns0:ArrayOfArrayOfPaymentDetail id="ID1" xsi:type="enc:Array"
enc:arrayType="ns0:PaymentDetail[2,2]">
           <item href="#ID2"/>
           <item href="#ID3"/>
           <item href="#ID4"/>
           <item href="#ID5"/>
</ns0:ArrayOfArrayOfPaymentDetail>
     <ns0:PaymentDetail id="ID2" xsi:type="ns0:PaymentDetail">
           <date xsi:type="xsd:dateTime">2002-08-26T21:17:37.678Z</date>
           <account xsi:type="xsd:string">Credit</account>
           <payeeName xsi:type="xsd:string">Digital Credit Union</payeeName>
           <amt xsi:type="xsd:double">2000.0</amt>
     </ns0:PaymentDetail>

     <ns0:PaymentDetail id="ID3" xsi:type="ns0:PaymentDetail">
           <date xsi:type="xsd:dateTime">2002-08-26T21:17:37.678Z</date>
           <account xsi:type="xsd:string">Credit</account>
           <payeeName xsi:type="xsd:string">Auto Loan Company</payeeName>
           <amt xsi:type="xsd:double">299.0</amt>
     </ns0:PaymentDetail>

     <ns0:PaymentDetail id="ID4" xsi:type="ns0:PaymentDetail">
           <date xsi:type="xsd:dateTime">2002-08-26T21:17:37.678Z</date>
           <account xsi:type="xsd:string">Credit</account>
           <payeeName xsi:type="xsd:string">AT&amp;T Wireless</payeeName>
           <amt xsi:type="xsd:double">20.0</amt>
     </ns0:PaymentDetail>

     <ns0:PaymentDetail id="ID5" xsi:type="ns0:PaymentDetail">
           <date xsi:type="xsd:dateTime">2002-08-26T21:17:37.678Z</date>
           <account xsi:type="xsd:string">Credit</account>
           <payeeName xsi:type="xsd:string">AT&amp;T Long distance</payeeName>
           <amt xsi:type="xsd:double">12.0</amt>
     </ns0:PaymentDetail>
</env:Body>
</env:Envelope>

In Chapter 4, we introduced the concept of RPC/document style. Recall that a SOAP message on the wire can be represented in either in RPC style or document style, which affects the body of the message. In RPC style, the client invokes a method on the server, by sending in the body of the SOAP message all information necessary for that method's execution. It receives a response in the same fashion. All SOAP messages shown till now in this chapter have been in RPC style.

In document style, the client and server communicate using XML documents. The client sends an XML document such as a purchase order; the server does something with it and returns an XML document such as an invoice as a result (Figure 10.3).

Figure 10.3: (a) RPC style. (b) Document style.

Thus, based on the style (RPC or document) and use (encoded or literal), four combinations result:

• RPC/encoded

• RPC/literal

• Document/encoded

• Document/literal

In Chapter 5, we looked at how WSDL could represent these combinations using the style and use attributes of the binding element. Let us elaborate on that with a detailed example. The WSDL extract below shows a sample schema and message extracts. The schema has two elements, Amount and details, and a custom type, PaymentDetail. The message element shown has four parts: part1, which is of type PaymentDetail; part2, which is of type int; part3, which is a simple element Amount; and part4, which is an element of complex type PaymentDetail. Table 10.5 compares the combinations.

   <operation name="schedulePayment" style="rpc" ... >
   <input>
   <soap:body parts="part1 part2"
             use="encoded"
             encoding= "http://schemas.xmlsoap.org/soap/encoding/"
    namespace="(namespace for message)"/>
   </input>
   </operation>

   <soapenv:body xmlns:mns="(namespace for message)">
   <mns:schedulePayment>
        <part1 HREF="#1" TARGET="_self"/>
        <part2>5688</part2>
   </mns:schedulePayment>

   <mns:PaymentDetails id="#1">
        <balance>8933</balance>
        <payeeName>johnmalkovich</payeeName>
   </mns:PaymentDetails>
   </soapenv:body>

   <operation name="schedulePayment"
              style="rpc" ... >
     <input>
         <soap:body use="literal"
                 parts="part1 part2 part3 part4"
    namespace="(namespace for message)"/>
     </input>
   // ...
   </operation>

   <soapenv:body xmlns:mns="(namespace for message)"
           xmlns:typens="(namespace for service schema)".. >
   <mns:schedulePayment>

   <mns:part1>

   <typens:balance>8933</typens:balance>
       <typens:payeeName>johnmalkovich
                    </typens:payeeName>
   </mns:part1>

   <mns:part2>5688</mns:part2>

   <mns:part3>

   <typens:Amount>5688</typens:Amount>
   </mns:part3>

   <mns:part4>
         <typens:PaymentDetail>
         <typens:balance>8933</typens:balance>
         <typens:payeeName>johnmalkovich
                        </typens:payeeName>
   </typens:PaymentDetail>
   </mns:part4>

   </mns:schedulePayment>
   </soapenv:body>

   <operation name="schedulePayment"
                  style="document" ... >
   <input>
   <soap:body parts="part1 part3 part4"
              use="literal">
   </input>
   </operation>

   <soapenv:body
               xmlns:typens="(namespace for service schema)" ... >

   <typens:balance>8933</typens:balance>
   <typens:payeeName>johnmalkovich
                 </typens:payeeName>

   <typens:Amount>5688</typens:Amount>

   <typens:details>
      <typens:balance>5688</typens:balance>
      <typens:payeeName>johnmalkovich

   </typens:payeeName>
   </typens:details>
   </soapenv:body>

   <operation name="schedulePayment"
              style="document" ... >
   <input>
   <soap:body parts="part1 part2"
              use="encoded"
              encoding=
   "http://schemas.xmlsoap.org/soap/encoding/"
      namespace="(namespace for message)"/>
   </input>
   </operation>

   <soapenv:body ...
                xmlns:mns="(namespace for message)">
   <mns:PaymentDetails>
       <balance>8933</balance>
       <payeeName>johnmalkovich</payeeName>
   </mns:PaymentDetails>

   <soapenc:int>5688</soapenc:int>
   </soapenv:body>

In document/literal style, the contents between <SOAP-ENC:Body> and </SOAP-ENC:Body> are sent as an XML string to the application, which is responsible for parsing the XML.

JAX-RPC requires RPC/encoded and document/literal support. These are optional for the other two combinations.

For more about the style use combinations of RPC/literal, document/literal, PRC/encoded, and document/encoded, see Chapter 5.

<definitions
  targetNamespace="(namespace for service WSDL)"
  xml:typens="(namespace for service schema)">

<types>
<schema targetNamespace="(namespace for the schema)">
  <element name="Amount" type="xsd:int"/>
  <element name="details" type="typens:PaymentDetail"/>
<!--user defined data type-->
  <complexType name="PaymentDetail">
     <sequence>
         <element name="balance" type="xsd:int"/>
         <element name="payeeName" type="xsd:string"/>
     </sequence>
  </complexType>
</schema>
</types>

<message...>
  <part name='part1' type="typens: PaymentDetail"/>
  <part name='part2' type="xsd:int"/>
  <part name='part3' element="typens:Amount"/>
  <part name='part4' element="typens:details"/>
</message>
...
</definitions>

When to Use RPC/Encoded and Document/Literal

To best choose a particular style, an architect would need to understand the implementation or desired use. In general, however, the effort and complexity involved in document style service is greater than for RPC style—for example, in negotiating the schema design with the business partners and validating the document against the schema. When architecting applications, these are some of the decision points for deciding between RPC or document style:

1. State maintenance. If multiple service invocations are involved in a single business transaction, with state maintained between the service invocations, the service must maintain state. Maintaining state is nontrivial and is usually not as simple as exposing a stateful EJB as a Web service over multiple RPC invocations. One alternative is to use document style, pass the contents of an entire transaction in the document, and allow the service implementation to ensure the sequence and state maintenance in the transaction. Information about that state can be returned in a token or in the resulting document to the client if needed.

   If the service consumer is only requesting information or persisting information in a specific format (e.g., industry-standard XML schema), a document style message makes more sense, because it is not constrained by the RPC-oriented encoding.

2. Integration with external parties and decoupled interfaces. Service consumers outside the enterprise typically have little control over the use and consequences of changes to the service interface. RPC interfaces are expected not to change, because any change would break the contract between the service and its consumers. In scenarios where a large number of applications have produced stub code from the service's WSDL document (we will see how to do this later in this chapter), changing the WSDL would cause all the applications that rely on a specific method signature to break. If you anticipate frequent changes, you can use a document/literal style, because the impact on the WSDL can be minimized. This is useful for the late binding pattern discussed in Chapter 5.

3. Validate business documents. A Web service can use the capabilities of a validating parser and schemas to describe and validate high-level business documents. This is opposed to RPC, where the XML describes the method and parameters encoded for that method call, which cannot be used to enforce high-level business rules.

   To enforce these rules for the document with RPC, a message must include an XML document as a string parameter or attachment and must hide the validation in the implementation of the method being called. If an attachment is not used, the service will have to deal with custom marshalling and unmarshalling code for a possibly complex XML structure. This often leads to valid calls with invalid parameters that are not detected till the entire structure has been processed. In short, if the service is accepting or returning a complex XML structure, a document style is better suited. The XML can be validated against the schema prior to calling the service, and no custom marshalling code is required.

4. Performance and memory limitations. Marshalling and unmarsalling parameters to XML in memory can be an intensive process. The SOAP model inherently requires DOM-based processing of the envelope, which can lead to large DOM trees in memory if the XML representation is complex. However, document style services can choose SAX handling of the including XML document, to perform quicker and less memory intensive parsing. This is critical for services that handle many simultaneous requests.

5. For fine-grained communication. With RPC calls, only a limited amount of data can be passed around in a single invocation, and it is not possible to include multiple RPC calls in a single SOAP envelope. If the application requires a significant amount of data to be passed around, RPC style with an attachment (e.g.. an XML document) is better suited.

6. Request-response processing. SOAP messages are, by nature, one-way transmissions from a sender to a receiver, but they are usually combined to implement a request/response model. SOAP piggybacking on top of a request-response-oriented transport, such as HTTP and JAX-RPC, is well suited to applications that require synchronous request-response processing. Such applications typically involve retrieval of results based on some remote procedure execution, for which RPC/encoded messages are well suited.

7. Encoding scheme. The default encoding scheme specified by SOAP is usually sufficient. If you determine a need to use custom encoding (e.g., the SOAP encoding doesn't meet your needs because you have complex types not addressed by JAX-RPC and SOAP), we recommend that you investigate the document style route instead, since schemas are by far a richer metalanguage than SOAP encoding. This allows for a more complex arrangement of information.

Document style combined with literal encoding allows validation. Changing that to RPC/literal takes that benefit away, because the surrounding RPC element does not appear in the schemas. A possible example where RPC/literal can be used instead of document/literal is when multiple RPC operations return XML documents using the same schema. Document/encoded takes away the benefits of RPC/encoded but does not add anything in return.