1501 lines
71 KiB
HTML
1501 lines
71 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<META http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<LINK rel="stylesheet" type="text/css" href="../../../rzahg/ic.css">
|
|
|
|
<title>Map between Java, WSDL, and XML</title>
|
|
</head>
|
|
|
|
<BODY>
|
|
<!-- Java sync-link -->
|
|
<SCRIPT LANGUAGE="Javascript" SRC="../../../rzahg/synch.js" TYPE="text/javascript"></SCRIPT>
|
|
|
|
<h4><a name="wsdevmap"></a>Map between Java, WSDL, and XML</h4>
|
|
|
|
<p>This topic contains the mappings between Java and XML technologies, including XML Schema, Web Services Description Language (WSDL) and Simple Object Access Protocol (SOAP), supported by WebSphere Application Server - Express. Most of these mappings are specified by Java API for XML-based remote procedure call (JAX-RPC). Some mappings optional or unspecified in JAX-RPC are also supported.</p>
|
|
|
|
<!-- <p>There are references to the JAX-RPC specification throughout this topic. You can review the JAX-RPC specification through Web services: Resources for learning.</p> -->
|
|
|
|
<p><strong>Notational conventions</strong></p>
|
|
|
|
<p>The following table specifies the namespace prefixes and corresponding namespaces used.</p>
|
|
|
|
<table cellspacing="2" cellpadding="2" border="1">
|
|
<tr>
|
|
<th id="col1">Namespace prefix</th>
|
|
<th id="col2">Namespace</th>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd</td>
|
|
<td headers="col2">http://www.w3.org/2001/XMLSchema</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsi</td>
|
|
<td headers="col2">http://www.w3.org/2001/XMLSchema-instance</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">soapenc</td>
|
|
<td headers="col2">http://schemas.xmlsoap.org/soap/encoding/</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">wsdl</td>
|
|
<td headers="col2">http://schemas.xmlsoap.org/wsdl/</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">wsdlsoap</td>
|
|
<td headers="col2">http://schemas.xmlsoap.org/wsdl/soap/</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">ns</td>
|
|
<td headers="col2">user defined namespace</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">apache</td>
|
|
<td headers="col2">http://xml.apache.org/xml-soap</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">wasws</td>
|
|
<td headers="col2">http://websphere.ibm.com/webservices/</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Detailed mapping information</strong></p>
|
|
|
|
<p>See these sections for information on the supported mappings:</p>
|
|
|
|
<ul>
|
|
<li><a href="#j2w">Java-to-WSDL mapping</a></li>
|
|
<li><a href="#w2j">WSDL-to-Java mapping</a></li>
|
|
<li><a href="#w2s">Mapping between WSDL and SOAP messages</a></li>
|
|
</ul>
|
|
|
|
<p><strong><a name="j2w"></a>Java-to-WSDL mapping</strong></p>
|
|
|
|
<p>This section summarizes the Java-to-WSDL mapping rules. The Java-to-WSDL mapping rules are used by the Java2WSDL command tool for bottom-up processing. In bottom-up processing, an existing Java service implementation is used to create a WSDL file defining the Web service. The generated WSDL file can require additional manual editing for the following reasons:</p>
|
|
<ul>
|
|
<li>Not all Java classes and constructs have mappings to WSDL. For example, Java classes that do not comply with the Java bean specification rules might not map to a WSDL construct.</li>
|
|
<li>Some Java classes and constructs have multiple mappings to WSDL. For example, a java.lang.String class can be mapped to either an xsd:string or soapenc:string. The Java2WSDL command chooses one of these mappings, but the WSDL file must be edited if a different mapping is desired.</li>
|
|
<li>There are multiple ways to generate WSDL constructs. For example, the part element in the wsdl:message can be generated with a type or element attribute. The Java2WSDL command makes an informed choice based on the settings of the -style and -use options.</li>
|
|
<li>The WSDL file describes the instance data elements sent in the SOAP message. If you want to modify the names or format used in the message, the WSDL file must be edited.</li>
|
|
<li>The WSDL file requires editing if header or attachment support is desired.</li>
|
|
<li>The WSDL file requires editing if a multipart WSDL, one using wsdl:import, is desired.</li>
|
|
</ul>
|
|
|
|
<p>For simple services, the generated WSDL file is sufficient. For complicated services, the generated WSDL file is a good starting point.</p>
|
|
<p><strong>General issues</strong></p>
|
|
|
|
<ul>
|
|
<li><p><strong>Package to namespace mapping</strong>
|
|
<br>The JAX-RPC does not specify the default mapping of Java package names to XML namespaces. The JAX-RPC does specify that each Java package must map to a single XML namespace, and likewise. A default mapping algorithm is provided that constructs the namespace by reversing the names of the Java package and adding an http:// prefix. For example, a package named, com.ibm.webservice, is mapped to the namespace http://webservice.ibm.com.</p>
|
|
<p>The default mapping between XML namespaces and Java package names can be overridden using the -NStoPkg and -PkgtoNS options of the WSDL2Java and Java2WSDL commands.</p></li>
|
|
|
|
<li><p><strong>Identifier mapping</strong>
|
|
<br>Java identifiers are mapped directly to WSDL file and XML identifiers.</p>
|
|
<p>Java bean property names are mapped to the WSDL file and XML identifiers. For example, a Java bean, with getInfo and setInfo methods, maps to an XML construct with the name, info.</p>
|
|
<p>The Service Endpoint Interface method parameter names, if available, are mapped directly to the XML identifiers. See the WSDL2Java command -implClass option for more details.</p></li>
|
|
|
|
<li><p><strong>WSDL construction summary</strong>
|
|
<br>The following table summarizes the mapping from a Java construct to the related WSDL and XML construct.</p>
|
|
<table cellspacing="2" cellpadding="2" border="1">
|
|
<tr>
|
|
<th id="col1">Java construct</th>
|
|
<th id="col2">WSDL and XML construct</th>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">Service Endpoint Interface</td>
|
|
<td headers="col2">wsdl:portType</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">Method</td>
|
|
<td headers="col2">wsdl:operation</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">Parameters</td>
|
|
<td headers="col2">wsdl:input, wsdl:message, wsdl:part (1)</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">Return</td>
|
|
<td headers="col2">wsdl:output, wsdl:message, wsdl:part (1)</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">Throws</td>
|
|
<td headers="col2">wsdl:fault, wsdl:message, wsdl:part (1)</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">Primitive types</td>
|
|
<td headers="col2">xsd and soapenc simple types</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">Java beans</td>
|
|
<td headers="col2">xsd:complexType</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">Java bean properties</td>
|
|
<td headers="col2">Nested xsd:elements of xsd:complexType</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">Arrays</td>
|
|
<td headers="col2">JAX-RPC defined array xsd:complexType</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">User defined exceptions</td>
|
|
<td headers="col2">xsd:complexType</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Note:</strong> The generated WSDL file is affected by the -style and -use options. A wsdl:binding that conforms to the generated wsdl:portType is generated. The style and use constructs of the wsdl:binding are determined from the -style and -use options. A wsdl:service containing a port that references the generated wsdl:binding is generated. The names and values of the wsdl:service are controlled by the Java2WSDL command options.</p></li>
|
|
|
|
<li><p><strong>Style and use</strong>
|
|
<br>Use the -style and -use options to generate different kinds of WSDL files. The four supported combinations are:</p>
|
|
<ul>
|
|
<li>-style RPC -use ENCODED</li>
|
|
<li>-style DOCUMENT -use LITERAL</li>
|
|
<li>-style RPC -use LITERAL</li>
|
|
<li>-style DOCUMENT -use LITERAL -wrapped false</li>
|
|
</ul>
|
|
<p>The -use LITERAL option affects the generated WSDL file in the following ways:</p>
|
|
<ul>
|
|
<li>The soap:body elements in the wsdl:binding are specified as use="literal".</li>
|
|
<li>The soap:fault elements in the wsdl:binding are specified as use="literal".</li>
|
|
<li>The soap encoded types are not used.</li>
|
|
<li>The soap encoded array style is not used. The maxOccurs attribute is used to indicate arrays.</li>
|
|
</ul>
|
|
<p>The -use ENCODED option affects the generated WSDL file in the following ways:</p>
|
|
<ul>
|
|
<li>The soap:body elements in the wsdl:binding are specified as use="encoded" and the encodingStyle is set.</li>
|
|
<li>The soap:fault elements in the wsdl:binding are specified as use="encoded" and the encodingStyle is set.</li>
|
|
<li>The -style RPC option affects the generated WSDL file in the following ways:</li>
|
|
<li>The wsdl:part elements use the type attribute to reference XML types.</li>
|
|
<li>The wsdl:binding is specified as style="rpc".</li>
|
|
</ul>
|
|
<p>The -style DOCUMENT -wrapped false option affects the generated WSDL file in the following ways:</p>
|
|
<ul>
|
|
<li>The wsdl:part elements use the type attribute to reference simple types. The element attribute is used to reference the root xsd:elements for everything that is not a simple type.</li>
|
|
<li>The wsdl:binding is specified as style="document".</li>
|
|
</ul>
|
|
<p>The -style DOCUMENT -wrapped true option generates a WSDL file that conforms to the .NET WSDL file format:</p>
|
|
<ul>
|
|
<li>A request xsd:element is generated for each method in the Service Endpoint Interface as follows:
|
|
<ul>
|
|
<li>The name of the xsd:element is the same as the name of the wsdl:operation.</li>
|
|
<li>The xsd:element contains an xsd:sequence that contains xsd:elements defining each parameter.</li>
|
|
<li>The request wsdl:message references the wrapper xsd:element using a single part:</li>
|
|
<li>The name of the part is parameters.</li>
|
|
<li>The element attribute is used to reference the wrapper xsd:element.</li>
|
|
</ul></li>
|
|
<li>A response xsd:element is generated for each method in the Service Endpoint Interface as follows:
|
|
<ul>
|
|
<li>The name of the xsd:element is the same as the name of the wsdl:operation appended with Response</li>
|
|
<li>The xsd:element contains an xsd:sequence that contains xsd:elements defining the return value.</li>
|
|
<li>The request wsdl:message references this wrapper xsd:element using a single part.</li>
|
|
<li>The element attribute is used to reference the wrapper xsd:element.</li>
|
|
<li>The wsdl:binding is specified as style="document".</li>
|
|
</ul></li>
|
|
</ul><p></p></li>
|
|
</ul>
|
|
|
|
|
|
<p><strong>Mapping of standard XML types from Java types</strong></p>
|
|
|
|
<p>Some Java types map directly to standard XML types. These types do not require additional XML definitions in the wsdl:types section.</p>
|
|
|
|
<ul>
|
|
<li><p><strong>JAX-RPC Java primitive type mapping</strong>
|
|
<br>The following table describes the mapping from the Java primitive and standard types to XML standard types. For more information see the JAX-RPC specification.</p>
|
|
<table cellspacing="2" cellpadding="2" border="1">
|
|
<!-- cols="53 47" width="page" -->
|
|
<tbody>
|
|
<tr>
|
|
<th id="col1">Java type</th>
|
|
<th id="col2">XML type</th>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">int</td>
|
|
<td headers="col2">xsd:int</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">long</td>
|
|
<td headers="col2">xsd:long</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">short</td>
|
|
<td headers="col2">xsd:short</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">float</td>
|
|
<td headers="col2">xsd:float</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">double</td>
|
|
<td headers="col2">xsd:double</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">boolean</td>
|
|
<td headers="col2">xsd:boolean</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">byte</td>
|
|
<td headers="col2">xsd:byte</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">byte[]</td>
|
|
<td headers="col2">xsd:base64Binary
|
|
<p><strong>Note:</strong> The default mapping for byte[] is xsd:base64Binary. The data in byte[] is passed over the wire as a text string encoded in the base64 format. An alternative format is xsd:hexBinary. To use the xsd:hexBinary format:</p>
|
|
<ul>
|
|
<li>Edit the WSDL file and change xsd:base64Binary to xsd:hexBinary, or</li>
|
|
<li>Change your implementation to use the specialized com.ibm.ws.webservices.engine.types.HexBinary class.</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">java.lang.String</td>
|
|
<td headers="col2">xsd:string</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">java.math.BigInteger</td>
|
|
<td headers="col2">xsd:integer</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">java.math.BigDecimal</td>
|
|
<td headers="col2">xsd:decimal</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">java.util.Calendar</td>
|
|
<td headers="col2">xsd:dateTime</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">java.util.Date
|
|
<p><strong>Note:</strong> This mapping is not covered by the JAX-RPC.</p></td>
|
|
<td headers="col2">xsd:date</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">java.lang.Boolean</td>
|
|
<td headers="col2">xsd:boolean xsi:nillable=true</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">java.lang.Float</td>
|
|
<td headers="col2">xsd:float xsi:nillable=true</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">java.lang.Double</td>
|
|
<td headers="col2">xsd:double xsi:nillable=true</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">java.lang.Integer</td>
|
|
<td headers="col2">xsd:int xsi:nillable=true</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">java.lang.Short</td>
|
|
<td headers="col2">xsd:short xsi:nillable=true</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">java.lang.Byte</td>
|
|
<td headers="col2">xsd:byte xsi:nillable=true</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p><strong>Note:</strong> The java.lang wrapper classes in the last six lines of the table map to the same XML construct as the corresponding Java primitive type. In addition, the xsi:nillable attribute is generated to indicate that such elements can be null.</p></li>
|
|
|
|
<li><p><strong>Additional Java class mappings</strong>
|
|
<br>In addition to the standard JAX-RPC mapping, the following classes are mapped directly to XML types:</p>
|
|
<table cellspacing="2" cellpadding="2" border="1">
|
|
<!-- cols="53 47" width="page" -->
|
|
<tbody>
|
|
<tr>
|
|
<th id="col1">Java type</th>
|
|
<th id="col2">XML type</th>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">com.ibm.ws.webservices.engine.types.HexBinary</td>
|
|
<td headers="col2">xsd:hexBinary</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">javax.xml.namespace.QName</td>
|
|
<td headers="col2">xsd:qname</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">com.ibm.ws.webservices.engine.types.Token</td>
|
|
<td headers="col2">xsd:token</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">com.ibm.ws.webservices.engine.types.NormalizedString</td>
|
|
<td headers="col2">xsd:normalizedString</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">com.ibm.ws.webservices.engine.types.Name</td>
|
|
<td headers="col2">xsd:Name</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">com.ibm.ws.webservices.engine.types.NCName</td>
|
|
<td headers="col2">xsd:NCName</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">com.ibm.ws.webservices.engine.types.NMToken</td>
|
|
<td headers="col2">xsd:NMTOKEN</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">com.ibm.ws.webservices.engine.types.URI</td>
|
|
<td headers="col2">xsd:anyURI</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">com.ibm.ws.webservices.engine.types.UnsignedLong</td>
|
|
<td headers="col2">xsd:unsignedLong</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">com.ibm.ws.webservices.engine.types.UnsignedInt</td>
|
|
<td headers="col2">xsd:unsignedInt</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">com.ibm.ws.webservices.engine.types.UnsignedByte</td>
|
|
<td headers="col2">xsd:unsignedByte</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">com.ibm.ws.webservices.engine.types.NonNegativeInteger</td>
|
|
<td headers="col2">xsd:nonNegativeInteger</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">com.ibm.ws.webservices.engine.types.PositiveInteger</td>
|
|
<td headers="col2">xsd:positiveInteger</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">com.ibm.ws.webservices.engine.types.NonPositiveInteger</td>
|
|
<td headers="col2">xsd:nonPositiveInteger</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">com.ibm.ws.webservices.engine.types.Time</td>
|
|
<td headers="col2">xsd:time</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">com.ibm.ws.webservices.engine.types.YearMonth</td>
|
|
<td headers="col2">xsd:gYearMonth</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">com.ibm.ws.webservices.engine.types.Year</td>
|
|
<td headers="col2">xsd:gYear</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">com.ibm.ws.webservices.engine.types.Month</td>
|
|
<td headers="col2">xsd:gMonth</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">com.ibm.ws.webservices.engine.types.Day</td>
|
|
<td headers="col2">xsd:gDay</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">com.ibm.ws.webservices.engine.types.MonthDay</td>
|
|
<td headers="col2">xsd:gMonthDay</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">com.ibm.ws.webservices.engine.types.Duration</td>
|
|
<td headers="col2">xsd:duration</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">java.util.Map</td>
|
|
<td headers="col2">apache:Map
|
|
<p><strong>Note:</strong> Any classes that implement java.util.Map are also mapped to apache:Map.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">java.util.Collection</td>
|
|
<td headers="col2">soapenc:Array
|
|
<p><strong>Note:</strong> Each Java array, except byte[], and every class that implements java.util.Collection is mapped to a JAX-RPC defined soapenc:Array type.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">org.w3c.dom.Element</td>
|
|
<td headers="col2">apache:Element</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">java.util.Vector</td>
|
|
<td headers="col2">apache:Vector</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">java.awt.Image
|
|
<p><strong>Note:</strong> Used for attachment support.</p></td>
|
|
<td headers="col2">apache:Image</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">javax.mail.internet.MimeMultiPart
|
|
<p><strong>Note:</strong> Used for attachment support.</p></td>
|
|
<td headers="col2">apache:Multipart</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">javax.xml.transform.Source
|
|
<p><strong>Note:</strong> Used for attachment support.</p></td>
|
|
<td headers="col2">apache:Source</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">javax.activation.DataHandler
|
|
<p><strong>Note:</strong> Used for attachment support.</p></td>
|
|
<td headers="col2">apache:DataHandler</td>
|
|
</tr>
|
|
</tbody>
|
|
</table></li>
|
|
</ul>
|
|
|
|
<p><strong>Generation of wsdl:types</strong></p>
|
|
|
|
<p>Java types that cannot be mapped directly to standard XML types are generated in the wsdl:types section.</p>
|
|
|
|
<ul>
|
|
<li><p><strong>Java arrays</strong>
|
|
<br>Java arrays for the -use ENCODED option, with the exception of byte[], are generated using the following format. See the JAX-RPC specification for more details. Alternative mappings can be found in Table 18.1 of the JAX-RPC specification.</p>
|
|
|
|
<p>Java:</p>
|
|
<pre> Item[]</pre>
|
|
|
|
<p>Mapped to:</p>
|
|
<pre><xsd:complexType name="ArrayOfItem">
|
|
<xsd:complexContent>
|
|
<xsd:restriction base="soapenc:Array">
|
|
<xsd:attribute ref="soapenc:arrayType" wsdl:arrayType="ns:Item" />
|
|
</xsd:restriction>
|
|
</xsd:complexContent
|
|
</xsd:complexType></pre></li>
|
|
|
|
<li><p><strong>JAX-RPC value type and bean mapping</strong>
|
|
<br>A Java class that matches the Java value type or bean pattern is mapped to an xsd:complexType. In order for a Java class to be mapped to XML, follow these conditions:</p>
|
|
<ul>
|
|
<li>The class must have a public default constructor.</li>
|
|
<li>The class must not implement, directly or indirectly, java.rmi.Remote.</li>
|
|
<li>Public, nonstatic, nonfinal, nontransient fields are mapped. The class can contain other fields and methods, but they are not mapped.</li>
|
|
<li>If the class follows the Java bean pattern and has public getter and setter methods, the property is mapped.</li>
|
|
</ul>
|
|
<p>Additional mapping rules can be found in the JAX-RPC specification. This example indicates the mapping for sample base and derived Java classes:</p>
|
|
|
|
<p>Java:</p>
|
|
<pre>public abstract class Base {
|
|
public Base() {}
|
|
public int a; // mapped
|
|
private int b; // mapped via setter/getter
|
|
private int c; // not mapped
|
|
private int[] d; // mapped via indexed setter/getter
|
|
|
|
public int getB() { return b;} // map property b
|
|
public void setB(int b) {this.b = b;}
|
|
|
|
public int[] getD() { return d;} // map indexed property d
|
|
public void setD(int[] d) {this.d = d;}
|
|
public int getD(int index) { return d[index];}
|
|
public void setB(int index, int value) {this.d[index] = value;}
|
|
|
|
public void someMethod() {...} // not mapped
|
|
}
|
|
|
|
public class Derived extends Base {
|
|
public int x; // mapped
|
|
private int y; // not mapped
|
|
}</pre>
|
|
|
|
<p>Mapped to:</p>
|
|
<pre><xsd:complexType name="Base" abstract="true">
|
|
<xsd:sequence>
|
|
<xsd:element name="a" type="xsd:int" />
|
|
<xsd:element name="b" type="xsd:int" />
|
|
<xsd:element name="d" minOccurs="0" maxOccurs="unbounded" type="xsd:int"/>
|
|
</xsd:sequence>
|
|
</xsd:complexType>
|
|
|
|
<xsd:complexType name="Derived">
|
|
<xsd:complexContent>
|
|
<xsd:extension base="ns:Base">
|
|
<xsd:sequence>
|
|
<xsd:element name="x" type="xsd:int" />
|
|
</xsd:sequence>
|
|
</xsd:extension>
|
|
</xsd:complexContent>
|
|
</xsd:complexType></pre>
|
|
|
|
<p>Inheritance and abstract classes</p>
|
|
<p>The example contains two optional JAX-RPC features that are supported by WebSphere Application Server:</p>
|
|
<ul>
|
|
<li>An abstract class is mapped to an xsd:complexType with abstract="true".</li>
|
|
<li>An indexed bean property (see the methods for d in Base) are mapped to a nested element specified with maxOccurs="unbounded". This format is similar to an XML array, but the SOAP message is different. An XML array defines an element for the array and nested elements for each item in the array. An element defined with maxOccurs indicates a series of items without the surrounding array wrapper element. Both formats are popular.</li>
|
|
</ul><p></p></li>
|
|
|
|
<li><p><strong>JAX-RPC enumeration class mapping</strong>
|
|
<br>Section 4.2.4 of the JAX-RPC specification defines the mapping from an XML enumeration to a Java class. Though not specifically required by the JAX-RPC, the Java2WSDL command performs the reverse mapping. If you have a class that has the same format as a JAX-RPC enumeration class, it is mapped to an XML enumeration.</p></li>
|
|
|
|
<li><p><strong>Holder classes</strong>
|
|
<br>The JAX-RPC specification defines Holder classes in section 4.3.5. A Holder class is used to support in and out parameter passing. Every Holder class implements thejavax.xml.rpc.holders.Holder interface. The Java2WSDL command maps Holder classes to the same XML type as the held type. In addition, references to Holder classes affect the generation of wsdl:messages.</p></li>
|
|
|
|
<li><p><strong>Exception classes</strong>
|
|
<br>If a class extends the exception, java.lang.Exception, it is mapped to an xsd:complexType similar to the Java bean mapping. The getter methods of the exception are mapped as nested xsd:elements of the xsd:complexType. See section 5.5.5 of the JAX-RPC specification for more details.</p>
|
|
<p><strong>Note:</strong> You need to generate implementation specific exception classes by invoking the WSDL2Java command on the resulting WSDL file.</p></li>
|
|
|
|
<li><p><strong>Unsupported classes</strong>
|
|
<br>If a class cannot be mapped to an XML type, the Java2WSDL command issues a message and an xsd:anyType reference is generated in the WSDL file. In these situations, modify the Web service implementation to use the JAX-RPC compliant classes.</p></li>
|
|
|
|
<li><p><strong>Generation of root elements</strong>
|
|
<br>If the Java2WSDL command generates an xsd:complexType or xsd:simpleType for a parameter reference, a corresponding xsd:element is also generated. The xsd:element has the same name as the xsd:complexType/xsd:simpleType and uses the type attribute to reference the xsd:complexType/xsd:simpleType. The wsdl:message part can use the element attribute or the type attribute to reference the xsd:element or type. This choice is determined by the -style and -use options.</p></li>
|
|
</ul>
|
|
|
|
<p><strong>Generation from the interface or implementation class</strong></p>
|
|
|
|
<p>The class passed to the Java2WSDL command represents the interface of the wsdl:service. The wsdl:portType and wsdl:message elements generate from this interface or implementation class.</p>
|
|
|
|
<ul>
|
|
<li><p><strong>Generation of the wsdl:portType</strong>
|
|
<br>The name of the wsdl:portType is the name of the class unless overridden by the -portTypeName option.</p></li>
|
|
|
|
<li><p><strong>Generation of wsdl:operation</strong>
|
|
<br>A wsdl:operation generates for each public method in the interface that throws the exception, java.rmi.RemoteException.</p>
|
|
<ul>
|
|
<li>The name of the wsdl:operation is the name of the method.</li>
|
|
<li>The wsdl:operation has a parameterOrder attribute, which defines the order of the parameters in the signature. Specifically, the parameterOrder lists the order of the parts of the request or response wsdl:messages.</li>
|
|
<li>The wsdl:operation has a nested wsdl:input element that references the request wsdl:message using the message attribute.</li>
|
|
<li>The wsdl:operation has a nested wsdl:output element that references the response wsdl:message using the message attribute.</li>
|
|
<li>The wsdl:operation has a nested wsdl:fault element that references the default wsdl:message using the message attribute.</li>
|
|
</ul>
|
|
<p>See sections 5.5.4 and 5.5.5 of the JAX-RPC specification for more information.</p></li>
|
|
|
|
<li><p><strong>Generation of wsdl:message</strong>
|
|
<br>Generating the wsdl:message is directly related to the -style and -use options. The following is the default mapping (-style RPC -use ENCODED):</p>
|
|
<ul>
|
|
<li><p>A wsdl:message is created to represent the request. A wsdl:part representing each parameter is added to the wsdl:message.</p>
|
|
<ul>
|
|
<li>The wsdl:part has the same name as the parameter.</li>
|
|
<li>The wsdl:part uses the type attribute to locate the XML type of the parameter.</li>
|
|
</ul><p></p></li>
|
|
|
|
<li><p>A wsdl:message is created to represent the response. A wsdl:part representing the method return is created.</p>
|
|
<ul>
|
|
<li>The wsdl:part has the same name as the method with Return appended.
|
|
<p>Note:</p> The name of the part is not specified by the JAX-RPC and is typically not checked by SOAP engines.
|
|
The wsdl:part has the same name as the parameter.</p></li>
|
|
<li>The wsdl:part uses the type attribute to locate the XML type of the parameter.</li>
|
|
<li>A wsdl:part is created for each parameter that is a Holder.</li>
|
|
<li>The wsdl:part has the same name as the parameter.</li>
|
|
<li>A wsdl:message is created to represent the fault if the operation has a wsdl:fault.</li>
|
|
<li>A wsdl:part representing the fault is created.</li>
|
|
<li>The wsdl:part has the same name as the exception.</li>
|
|
<li>The wsdl:part uses the type attribute to locate the complexType representing the exception.</li>
|
|
</ul><p></p></li>
|
|
</ul>
|
|
<p>The same mapping is used as described if you use the -style RPC and -use LITERAL options. It is also valid to use the wsdl:part element attribute instead of the type attribute to reference the XML schema. If you use the -style DOCUMENT -wrapped false and -use LITERAL options, the same mapping is used as described except the wsdl:part element attribute is used to reference the XML schema. If the XML schema is a primitive type, like xsd:string, the type attribute is used to reference the XML type. The -style DOCUMENT, -wrapped true and -use LITERAL options result in completely different mappings for the request and response messages. For example:</p>
|
|
<ul>
|
|
<li><p>A request xsd:element is generated for each method in the Service Endpoint Interface.</p>
|
|
<ul>
|
|
<li>The name of the xsd:element is the same as the name of the wsdl:operation.</li>
|
|
<li>The xsd:element contains an xsd:sequence that contains xsd:elements defining each parameter.</li>
|
|
<li>The request wsdl:message references the wrapper xsd:element using a single part.
|
|
<ul>
|
|
<li>The name of the part is parameters.</li>
|
|
<li>The element attribute is used to reference the wrapper xsd:element.</li>
|
|
</ul></li>
|
|
</ul><p></p></li>
|
|
<li><p>A response xsd:element is generated for each method in the Service Endpoint Interface.</p>
|
|
<ul>
|
|
<li>The name of the xsd:element is the same as the name of the wsdl:operation appended with Response.</li>
|
|
<li>The xsd:element contains an xsd:sequence that contains xsd:elements defining the return value.</li>
|
|
<li>The request wsdl:message references this wrapper xsd:element using a single part.</li>
|
|
<li>The element attribute is used to reference the wrapper xsd:element.</li>
|
|
</ul><p></p></li>
|
|
</ul><p></p></li>
|
|
|
|
<li><p><strong>Generation of wsdl:binding</strong>
|
|
<br>Generate a wsdl:binding with a name defined by the Java2WSDL -bindingName command.</p>
|
|
<ul>
|
|
<li>The wsdlsoap:binding style attribute is set to rpc if you use the -style RPC option; otherwise it is set to document.</li>
|
|
<li>A wsdl:operation generates for each wsdl:operation defined in the wsdl:portType.</li>
|
|
<li>Each wsdl:operation has corresponding wsdl:input, wsdl:output and wsdl:fault elements.</li>
|
|
<li>The wsdl:input, wsdl:output and wsdl:fault elements each contain a wsdlsoap:body element.</li>
|
|
<li>The wsdlsoap:body use attribute is set to literal or encoded according to the -use argument. Set the encodingStyle attribute to http://schemas.xmlsoap.org/soap/encoding/ when use is encoded.</li>
|
|
</ul><p></p></li>
|
|
|
|
<li><p><strong>Generation of the wsdl:service</strong>
|
|
<br>Generate a wsdl:service with a name defined by the Java2WSDL -serviceElement command. For example:</p>
|
|
<ul>
|
|
<li>The wsdl:service contains a port with a name defined by the Java2WSL -servicePortName command.</li>
|
|
<li>The port references the generated wsdl:binding with the binding attribute.</li>
|
|
<li>The port contains a wsdlsoap:address element with a</li>
|
|
<li>The location attribute is set to the value of the Java2WSDL -location command.</li>
|
|
</ul><p></p></li>
|
|
</ul>
|
|
|
|
<p><strong><a name="w2j"></a>WSDL-to-Java mapping</strong></p>
|
|
|
|
<p>The WSDL2Java command tool uses the following rules to generate Java classes when developing your Web services client and server. In addition, implementation specific Java classes are generated that assist in the serialization and deserialization, and invocation of the Web service.</p>
|
|
|
|
<p><strong>General issues</strong></p>
|
|
|
|
<ul>
|
|
<li><p><strong>Mapping of namespace to package</strong>
|
|
<br>The JAX-RPC does not specify the mapping of XML namespaces to Java package names. The JAX-RPC does specify that each Java package map to a single XML namespace, and likewise. A default mapping algorithm omits any protocol from the XML namespace and reverses the names. For example, an XML namespace http://websphere.ibm.com becomes a Java package with the name com.ibm.websphere.</p>
|
|
<p>The default mapping of XML namespace to Java package disregards the context-root. If two namespaces are the same up until the first slash, they map to the same Java package. For example, the XML namespaces http://websphere.ibm.com/foo and http://websphere.ibm.com/bar map to the Java package com.ibm.websphere. The default mapping between XML namespaces and Java package names can be overridden using the -NStoPkg and -PkgtoNS options of WSDL2Java and Java2WSDL commands.</p></li>
|
|
|
|
<li><p><strong>Identifier mapping</strong>
|
|
<br>XML names are much richer than Java identifiers. They can include characters that are not permitted in Java identifiers. See section 20 of the JAX-RPC specification for the rules to map an XML name to a Java identifier.</p>
|
|
<p>The mapping rules attempt to follow accepted Java coding conventions. Class names always begin with an uppercase letter. Method names begin with a lowercase letter. The WSDL2Java command generates metadata in the _Helper class so that the values are serialized or deserialized using the XML names specified in the WSDL file.</p></li>
|
|
|
|
<li><p><strong>Java construction summary</strong></p>
|
|
<table cellspacing="2" cellpadding="2" border="1">
|
|
<tr>
|
|
<th id="col1">WSDL and XML</th>
|
|
<th id="col2">Java</th>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:complexType (struct)
|
|
<p><strong>Note:</strong> The xsd:complexType can also represent a Java exception if referenced by a wsdl:message for a wsdl:fault.</p></td>
|
|
<td headers="col2">Java Bean Class
|
|
<p><strong>Note:</strong> The classes, _Helper, _Ser, and _Deser, generate for each Java bean class. These implementation classes aid serialization and deserialization.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">nested xsd:element/xsd:attribute</td>
|
|
<td headers="col2">Java bean property</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:complexType (array)</td>
|
|
<td headers="col2">Java array</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:simpleType (enumeration)</td>
|
|
<td headers="col2">JAX-RPC enumeration class</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:complexType (wrapper) The method parameter signature typically is determined by the wsdl:message. However, if the WSDL file is a .NET wrapped style, the method parameter signature is determined by the wrapper xsd:element</td>
|
|
<td headers="col2">Service Endpoint Interface method parameter signature
|
|
<p><strong>Note:</strong> If a parameter is out or inout, a Holder class generates.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">wsdl:message The method parameter signature typically is determined by the wsdl:message. However, if the WSDL file is a .NET wrapped style, the method parameter signature is determined by the wrapper xsd:element</td>
|
|
<td headers="col2">Service Endpoint Interface method signature
|
|
<p><strong>Note:</strong> If a parameter is out or inout, a Holder class generates.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">wsdl:portType</td>
|
|
<td headers="col2">Service Endpoint Interface</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">wsdl:operation</td>
|
|
<td headers="col2">Service Endpoint Interface method</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">wsdl:binding</td>
|
|
<td headers="col2">Stub
|
|
<p><strong>Note:</strong> The Stub and ServiceLocator classes are implementation specific.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">wsdl:service</td>
|
|
<td headers="col2">Service Interface and ServiceLocator
|
|
<p><strong>Note:</strong> The Stub and ServiceLocator classes are implementation specific.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">wsdl:port</td>
|
|
<td headers="col2">Port accessor method in Service Interface</td>
|
|
</tr>
|
|
</table><p></p></li>
|
|
</ul>
|
|
|
|
<p><strong>Mapping standard XML types</strong></p>
|
|
|
|
<ul>
|
|
<li><p><strong>JAX-RPC simple XML types mapping</strong>
|
|
<br>The following mappings are XML types to Java types. For more information about these mappings, see section 4.2.1 of the JAX-RPC specification.</p>
|
|
<table cellspacing="2" cellpadding="2" border="1">
|
|
<tr>
|
|
<th id="col1">XML type</th>
|
|
<th id="col2">Java type</th>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:string</td>
|
|
<td headers="col2">java.lang.String</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:integer</td>
|
|
<td headers="col2">java.math.BigInteger</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:int
|
|
<p><strong>Note:</strong> If an element with this type has the xsi:nillable attribute set to true, it is mapped to the Java wrapper class of the primitive type.</p></td>
|
|
<td headers="col2">int</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:long
|
|
<p><strong>Note:</strong> If an element with this type has the xsi:nillable attribute set to true, it is mapped to the Java wrapper class of the primitive type.</p></td>
|
|
<td headers="col2">long</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:short
|
|
<p><strong>Note:</strong> If an element with this type has the xsi:nillable attribute set to true, it is mapped to the Java wrapper class of the primitive type.</p></td>
|
|
<td headers="col2">short</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:decimal</td>
|
|
<td headers="col2">java.math.BigDecimal</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:float
|
|
<p><strong>Note:</strong> If an element with this type has the xsi:nillable attribute set to true, it is mapped to the Java wrapper class of the primitive type.</p></td>
|
|
<td headers="col2">float</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:double
|
|
<p><strong>Note:</strong> If an element with this type has the xsi:nillable attribute set to true, it is mapped to the Java wrapper class of the primitive type.</p></td>
|
|
<td headers="col2">double</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:boolean
|
|
<p><strong>Note:</strong> If an element with this type has the xsi:nillable attribute set to true, it is mapped to the Java wrapper class of the primitive type.</p></td>
|
|
<td headers="col2">boolean</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:byte
|
|
<p><strong>Note:</strong> If an element with this type has the xsi:nillable attribute set to true, it is mapped to the Java wrapper class of the primitive type.</p></td>
|
|
<td headers="col2">byte</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:dateTime</td>
|
|
<td headers="col2">java.util.Calendar</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:date
|
|
<p><strong>Note:</strong> This mapping is not supported by the JAX-RPC.</p></td>
|
|
<td headers="col2">java.util.Date</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:base64Binary</td>
|
|
<td headers="col2">byte[]</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:hexBinary</td>
|
|
<td headers="col2">byte[]</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">soapenc:base64</td>
|
|
<td headers="col2">byte[]</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">soapenc:base64Binary</td>
|
|
<td headers="col2">byte[]</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">soapenc:string</td>
|
|
<td headers="col2">java.lang.String</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">soapenc:boolean</td>
|
|
<td headers="col2">java.lang.Boolean</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">soapenc:float</td>
|
|
<td headers="col2">java.lang.Float</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">soapenc:double</td>
|
|
<td headers="col2">java.lang.Double</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">soapenc:decimal</td>
|
|
<td headers="col2">java.math.BigDecimal</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">soapenc:int</td>
|
|
<td headers="col2">java.lang.Integer</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">soapenc:integer
|
|
<p><strong>Note:</strong> This mapping is not supported by the JAX-RPC.</p></td>
|
|
<td headers="col2">java.math.BigInteger</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">soapenc:short</td>
|
|
<td headers="col2">java.lang.Short</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">soapenc:long
|
|
<p><strong>Note:</strong> This mapping is not supported by the JAX-RPC.</p></td>
|
|
<td headers="col2">java.lang.Long</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">soapenc:byte</td>
|
|
<td headers="col2">java.lang.Byte</td>
|
|
</tr>
|
|
</table><p></p></li>
|
|
|
|
<li><p><strong>JAX-RPC optional simple XML type mapping</strong>
|
|
<br>The WSDL2Java command supports the following JAX-RPC optional simple XML types.</p>
|
|
<table cellspacing="2" cellpadding="2" border="1">
|
|
<tr>
|
|
<th id="col1">XML type</th>
|
|
<th id="col2">Java type</th>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:qname</td>
|
|
<td headers="col2">javax.xml.namespace.QName</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:time</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.Time</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:gYearMonth</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.YearMonth</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:gYear</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.Year</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:gMonth</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.Month</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:gDay</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.Day</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:gMonthDay</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.MonthDay</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:token</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.Token</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:normalizedString</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.NormalizedString</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:unsignedLong</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.UnsignedLong</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:unsignedInt</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.UnsignedInt</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:unsignedShort</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.UnsignedShort</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:unsignedByte</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.UnsignedByte</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:nonNegativeInteger</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.NonNegativeInteger</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:negativeInteger</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.NegativeInteger</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:positiveInteger</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.PositiveInteger</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:nonPositiveInteger</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.NonPositiveInteger</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:Name</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.Name</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:NCName</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.NCName</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:NMTOKEN</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.NMTOKEN</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:duration</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.Duration</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">xsd:anyURI</td>
|
|
<td headers="col2">com.ibm.ws.webservices.engine.types.URI</td>
|
|
</tr>
|
|
</table><p></p></li>
|
|
|
|
<li><p><strong>JAX-RPC xsd:anyType mapping</strong>
|
|
<br>The WSDL2Java command maps an xsd:anyType to a java.lang.Object. This is an optional feature of the JAX-RPC specification. The xsd:anyType can be used to store any XML type other than the XML primitive type. An xsd:anyType is always serialized along with an xsi:type that specifies the actual type.</p></li>
|
|
|
|
<li><p><strong>Additional supported mappings</strong>
|
|
<br>The following mappings are also supported by the WSDL2Java command. These mappings are not defined by the JAX-RPC specification.</p>
|
|
<table cellspacing="2" cellpadding="2" border="1">
|
|
<tr>
|
|
<th id="col1">XML type</th>
|
|
<th id="col2">Java type</th>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">apache:PlainText
|
|
<p><strong>Note:</strong> For MIME attachments.</p></td>
|
|
<td headers="col2">java.lang.String</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">apache:Map</td>
|
|
<td headers="col2">java.util.Map</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">apache:Element</td>
|
|
<td headers="col2">org.w3c.dom.Element</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">wasws:SOAPElement</td>
|
|
<td headers="col2">com.ibm.ws.webservices.xmlsoap.SOAPElement</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">apache:Vector</td>
|
|
<td headers="col2">java.util.Vector</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">apache:Image
|
|
<p><strong>Note:</strong> For MIME attachments.</p></td>
|
|
<td headers="col2">java.awt.Image</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">apache:Multipart
|
|
<p><strong>Note:</strong> For MIME attachments.</p></td>
|
|
<td headers="col2">javax.mail.internet.MimeMultipart</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">apache:Source
|
|
<p><strong>Note:</strong> For MIME attachments.</p></td>
|
|
<td headers="col2">javax.xml.transform.Source</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">apache:octetStream
|
|
<p><strong>Note:</strong> For MIME attachments.</p></td>
|
|
<td headers="col2">javax.activation.DataHandler</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">apache:DataHandler
|
|
<p><strong>Note:</strong> For MIME attachments.</p></td>
|
|
<td headers="col2">javax.activation.DataHandler</td>
|
|
</tr>
|
|
</table><p></p></li>
|
|
</ul>
|
|
|
|
<p><strong>Mapping XML defined in the wsdl:types section</strong></p>
|
|
|
|
<p>The WSDL2Java command generates Java types for the XML schema constructs defined in the wsdl:types section. The XML schema language is broader than the required or optional subset defined by the JAX-RPC specification. The WSDL2Java command supports all required mappings and most optional mappings. In addition, the command supports some XML schema mappings that are outside the JAX-RPC specification. In general, the WSDL2Java command ignores constructs that it does not support. For example, the WSDL2Java command does not support the default attribute. If an xsd:element is defined with the default attribute, the default attribute is ignored. In some cases it maps unsupported constructs to wasws:SOAPElement.</p>
|
|
|
|
<ul>
|
|
<li><p><strong>Mapping of xsd:complexType to Java bean</strong>
|
|
<br>The most common mapping is from an xsd:complexType to a Java bean class.</p>
|
|
<ul>
|
|
<li><p><strong>Standard Java bean mapping</strong>
|
|
<br>The standard Java bean mapping is defined in section 4.2.3 of the JAX-RPC specification The xsd:complexType defines the type. The nested xsd:elements within the xsd:sequence or xsd:all groups are mapped to Java bean properties. For example:</p>
|
|
|
|
<p>XML:</p>
|
|
<pre><xsd:complexType name="Sample">
|
|
<xsd:sequence>
|
|
<xsd:element name="a" type="xsd:string"/>
|
|
<xsd:element name="b" maxOccurs="unbounded" type="xsd:string"/>
|
|
</xsd:sequence>
|
|
</xsd:complexType></pre>
|
|
|
|
<p>Java:</p>
|
|
<pre>public class Sample {
|
|
// ..
|
|
public Sample() {}
|
|
|
|
// Bean Property a
|
|
public String getA() {...}
|
|
public void setA(String value) {...}
|
|
|
|
// Indexed Bean Property b
|
|
public String[] getB() {...}
|
|
public String getB(int index) {...}
|
|
public void setB(String[] values) {...}
|
|
public void setB(int index, String value) {...}
|
|
|
|
}</pre></li>
|
|
|
|
<li><p><strong>Methods equals() and hashCode()</strong>
|
|
<br>The generated Java bean classes contain an implementation of the equals() method. The generation of this method is outside the JAX-RPC specification. The equals() method returns true if equals() is true for each contained bean property. The implementation accounts for self-referencing loops. This version of the equals() method is typically more useful than the "identity" equals provided by java.lang.Object. A corresponding hashCode() method is also generated in the Java bean class.</p></li>
|
|
|
|
<li><p><strong>Properties and indexed properties</strong>
|
|
<br>In the standard Java bean mapping example, the nested xsd:element for property a is mapped to a Java bean property. In addition, the WSDL2Java command maps a nested xsd:element with maxOccurs > 1 to a Java bean indexed property.</p></li>
|
|
|
|
<li><p><strong>Attributes</strong>
|
|
<br>The WSDL2Java command also supports the xsd:attribute element, as shown in the following example.</p>
|
|
<p>Attribute a is mapped as a Java bean property, which is exactly the same mapping as a nested xsd:element. Implementation specific metadata is generated in the Sample2_Helper class to ensure that property a is serialized and deserialized as an attribute, and not as a nested element. For example:</p>
|
|
|
|
<p>XML:</p>
|
|
<pre><xsd:complexType name="Sample2">
|
|
<xsd:sequence>
|
|
<xsd:attribute name="a" type="xsd:string"/>
|
|
</xsd:sequence>
|
|
</xsd:complexType></pre>
|
|
|
|
<p>Java:</p>
|
|
<pre>public class Sample2 {
|
|
// ..
|
|
public Sample2() {}
|
|
|
|
// Bean Property a
|
|
public String getA() {...}
|
|
public void setA(String value) {...}
|
|
}</pre></li>
|
|
|
|
<li><p><strong>Qualified versus unqualified names</strong>
|
|
<br><p>The WSDL2Java command supports the elementForm and attributeForm schema attributes. This support is not specified in the JAX-RPC specification. These attributes are used to indicate whether an element or attribute is serialized and deserialized with a qualified or unqualified name. The default setting for elementForm is qualified and the default setting for attributeForm is unqualified. These settings do not affect the Java bean class that is generated, but the information is captured in the _Helper class metadata.</p></li>
|
|
|
|
<li><p><strong>Extension and the abstract attribute</strong>
|
|
<br>The WSDL2Java command supports extension of an xsd:complexType through the xsd:extension element. This support is required by the JAX-RPC specification.</p>
|
|
<p>The WSDL2Java command supports the abstract attribute. This feature is listed as optional by the JAX-RPC specification.</p>
|
|
<p>The following example shows the accepted use of the extension and abstract constructs. WebSphere Application Server uses the extension and abstract constructs to support polymorphism.</p>
|
|
|
|
<p>XML:</p>
|
|
<pre><xsd:complexType name="Base" abstract="true">
|
|
<xsd:sequence>
|
|
<xsd:element name="a" type="xsd:int" />
|
|
</xsd:sequence>
|
|
</xsd:complexType>
|
|
|
|
<xsd:complexType name="Derived">
|
|
<xsd:complexContent>
|
|
<xsd:extension base="ns:Base">
|
|
<xsd:sequence>
|
|
<xsd:element name="b" type="xsd:int" />
|
|
</xsd:sequence>
|
|
</xsd:extension>
|
|
</xsd:complexContent>
|
|
</xsd:complexType></pre>
|
|
|
|
<p>Java:</p>
|
|
<pre> public abstract class Base {
|
|
// ...
|
|
public Base() {}
|
|
|
|
public int getA() {...}
|
|
public void setA(int a) {...}
|
|
}
|
|
|
|
public class Derived extends Base {
|
|
// ...
|
|
public Derived() {}
|
|
|
|
public int getB() {...}
|
|
public void setB(int b) {...}
|
|
}</pre></li>
|
|
|
|
<li><p><strong>Support for xsd:any</strong>
|
|
<br>The WSDL2Java command supports xsd:anyelement, which is different than xsd:anyType. This feature is not defined within the JAX-RPC specification and is subject to change.</p>
|
|
<p>If an <xsd:any/> element is defined within xsd:sequence or xsd:all group, SOAP values that do match one of the xsd:elements are stored in the Java bean as com.ibm.ws.webservices.engine.xmlsoap.SOAPElement objects. Values can be accessed from the Java bean using the get_any() and set_any() methods.</p></li>
|
|
</ul><p></p></li>
|
|
|
|
<li><p><strong>Mapping of xsd:element</strong>
|
|
<br><p>An xsd:element is a construct that has a name or name attribute, and a type defined by a complexType or primitive type. There are two different kinds of xsd:elements:</p>
|
|
<ul>
|
|
<li>Root: Defined directly underneath the schema elements and referenced by other constructs.</li>
|
|
<li>Nested: Nested underneath group elements and are not referenced by other constructs.</li>
|
|
</ul>
|
|
<p>Root elements are referenced by the WSDL file constructs, especially if the WSDL file is used to describe a literal service. Typically, root elements and types have the same names, which is allowed in the schema language. Under most circumstances the WSDL2Java command can produce Java artifacts without name collisions.</p>
|
|
<ul>
|
|
<li><p><strong>Four ways to reference a type</strong>
|
|
<br>There are four ways that a nested or root xsd:element can reference a type:</p>
|
|
<ul>
|
|
<li><p>Use the type attribute:
|
|
<br>This is the most common way to reference a type, for example:</p>
|
|
<pre><xsd:element name="one" type="ns:myType" /></pre>
|
|
<p>The WSDL2Java command recognizes the type attribute as a reference to a complexType or simpleType named, myType. The WSDL2Java command generates a Java type based on the characteristics of myType. Support for the type attribute is required by the JAX-RPC specification.</p></li>
|
|
|
|
<li><p>Use the ref attribute:
|
|
<br>For example:</p>
|
|
<pre><xsd:element ref="ns:myElement" /></pre>
|
|
<p>The WSDL2Java command recognizes the ref attribute as a reference to another root element named myElement. The name of the element is obtained from the referenced element, such as myElement. The type of the element is the type of the referenced element. The WSDL2Java command generates a Java type based on the characteristics of the referenced type. The ref attribute is an optional feature of the JAX-RPC specification.</p></li>
|
|
|
|
<li><p>Use no attribute:
|
|
<br>For example:</p>
|
|
<pre><xsd:element name="three" /></pre>
|
|
<p>When you do not use an attribute, the WSDL2Java command recognizes a reference to the xsd:anyType as defined by the XML schema specification. The xsd:anyType is an optional type of the JAX-RPC specification.</p></li>
|
|
|
|
<li><p>Use an anonymous type:
|
|
<br>For example:</p>
|
|
<pre><xsd:element name="four">
|
|
<xsd:complexType>
|
|
<xsd:sequence>
|
|
<xsd:element name="foo" type="xsd:string" />
|
|
</xsd:sequence>
|
|
</xsd:complexType>
|
|
</ xsd:element></pre>
|
|
<p>When you use an anonymous type, the WSDL2Java command recognizes a reference to the type defined within the element.</p>
|
|
<p><strong>Note:</strong> The complexType does not have a name.</p>
|
|
<p>The WSDL2Java command generates a Java type based on the characteristics of this type. Since the anonymous type does not have a name, the WSDL2Java command uses the name of the container element, which can result in collisions with defined types and other anonymous types. The WSDL2Java command automatically detects and renames classes to avoid collisions. Support for anonymous types is not defined by the JAX-RPC specification, however using anonymous types is common.
|
|
Note: An xsd:attribute is like an xsd:element; it contains a name and refers to a type. An xsd:attribute can refer to its type with the type attribute or using an anonymous type.</p>
|
|
</ul><p></p></li>
|
|
|
|
<li><p><strong>Element specific attributes</strong>
|
|
<br>Some attributes can be applied to xsd:elements and not to XML types.</p>
|
|
<p>The maxOccurs attribute indicates the maximum number of occurrences of the element in the SOAP message. The default value is 1. If the value is greater than 1, or unbounded, the WSDL2Java command maps the construct to a Java array or bean indexed property. Metadata is also generated to properly serialize and deserialize a series of elements versus a normal XML array. The maxOccurs attribute is an optional feature of the JAX-RPC specification.</p>
|
|
<p>The minOccurs attribute indicates the minimum number of occurrences of the element in the SOAP message. The default value is 1. The xsi:nillable attribute indicates whether the element can have a nil value. The minOccurs and xsi:nillable settings affect how a null value is serialized in a SOAP message. If minOccurs=0, the null value is not serialized. If xsi:nillable=true, the value is serialized with the xsi:nil=true attribute.</p></li>
|
|
</ul><p></p></li>
|
|
|
|
<li><p><strong>Mapping of xsd:complexType to Java array</strong>
|
|
<br>The WSDL2Java command maps the following three kinds of XML formats to Java arrays:</p>
|
|
|
|
<p>XML:</p>
|
|
<pre><xsd:element name="array1" type="soapenc:Array" /></pre>
|
|
|
|
<p>Java:</p>
|
|
<pre>Object[] array1;</pre>
|
|
|
|
<p>XML:</p>
|
|
<pre><xsd:complexType name="arrayOfInt">
|
|
<xsd:complexContent>
|
|
<xsd:restriction base:"soapenc:Array">
|
|
<xsd:attribute ref:"soapenc:arrayType" wsdl:arrayType="xsd:int[]" />
|
|
</xsd:restriction>
|
|
</xsd:complexContext>
|
|
</xsd:complexType>
|
|
<xsd:element name="array2" type="ns:arrayOfInt" /></pre>
|
|
|
|
<p>Java:</p>
|
|
<pre> int[] array2;</pre>
|
|
|
|
<p>XML:</p>
|
|
<pre><xsd:complexType name="arrayOfInt">
|
|
<xsd:complexContent>
|
|
<xsd:restriction base:"soapenc:Array">
|
|
<xsd:sequence>
|
|
<xsd:element name="item" type="xsd:int" maxOccurs="unbounded" />
|
|
</xsd:sequence>
|
|
</xsd:restriction>
|
|
</xsd:complexContent>
|
|
</xsd:complexType>
|
|
<xsd:element name="array3" type="ns:arrayOfInt" /></pre>
|
|
|
|
<p>Java:</p>
|
|
<pre> int[] array3;</pre></li>
|
|
|
|
<li><p><strong>Mapping of xsd:simpleType enumeration</strong>
|
|
<br>The WSDL2Java command maps the following XML enumeration to a JAX-RPC specified enumeration class. See section 4.2.4 of the JAX-RPC specification for more details.</p>
|
|
|
|
<pre><xsd:simpleType name="EyeColorType" >
|
|
<xsd:restriction base="xsd:string">
|
|
<xsd:enumeration value="brown"/>
|
|
<xsd:enumeration value="green"/>
|
|
<xsd:enumeration value="blue"/>
|
|
</xsd:restriction>
|
|
</xsd:simpleType></pre></li>
|
|
|
|
<li><p><strong>Mapping of xsd:complexType to exception class</strong>
|
|
<br>If a complexType is referenced in a wsdl:message for a wsdl:fault, the complexType is mapped to a class that extends the exception, java.lang.Exception. This mapping is similar to the mapping of a complexType to a Java bean class, except a full constructor is generated, and only getter methods are generated. See section 4.3.6 of the JAX-RPC specification for more details.</p></li>
|
|
|
|
<li><p><strong>Other mappings</strong>
|
|
<br>The WSDL2Java command supports the mapping of xsd:simpleType and xsd:complexTypes that extend xsd:simpleTypes. These constructs are mapped to Java bean classes. The simple value is mapped to a Java bean property named, value. This is an optional feature of the JAX-RPC specification.</p></li>
|
|
</ul>
|
|
|
|
<p><strong>Mapping of wsdl:portType</strong></p>
|
|
|
|
<p>The wsdl:portType construct is mapped to the Service Endpoint Interface. The name of the wsdl:portType is mapped to the name of the class of the Service Endpoint Interface.</p>
|
|
|
|
<p><strong>Mapping of wsdl:operation</strong></p>
|
|
|
|
<p>A wsdl:operation within a wsdl:portType is mapped to a method of the Service Endpoint Interface. The name of the wsdl:operation is mapped to the name of the method. The wsdl:operation contains wsdl:input and wsdl:output elements that reference the request and response wsdl:message constructs using the message attribute. The wsdl:operation can contain a wsdl:fault element that references a wsdl:message describing the fault. These faults are mapped to Java classes that extend the exception, java.lang.Exception as discussed in section 4.3.6 of the JAX-RPC specification.</p>
|
|
|
|
<ul>
|
|
<li><p><strong>Effect of document literal wrapped format</strong>
|
|
<br>If the WSDL file uses the .NET document and literal wrapped format, the method parameters are mapped from the wrapper xsd:element. The .NET document and literal format is automatically detected by the WSDL2Java command. The following criteria must be met:</p>
|
|
<ul>
|
|
<li>The WSDL file must have style="document" in its wsdl:binding constructs.</li>
|
|
<li>The WSDL file must have use="literal" in its wsdl:binding constructs.</li>
|
|
<li>The wsdl:message referenced by the wsdl:operation input construct must have a single part.</li>
|
|
<li>The part must use the element attribute to reference an xsd:element.</li>
|
|
<li>The referenced xsd:element, or wrapper element, must have the same name as the wsdl:operation.</li>
|
|
<li>The wrapper element must not contain any xsd:attributes.</li>
|
|
</ul>
|
|
<p>In such cases, each parameter name is mapped from a nested xsd:element contained within wrapper element. The type of the parameter is mapped from the type of the nested xsd:element. For example:</p>
|
|
|
|
<p>XML:</p>
|
|
<pre><xsd:element name="myMethod" >
|
|
<xsd:complexType>
|
|
<xsd:sequence>
|
|
<xsd:element name="param1" type="xsd:string" />
|
|
<xsd:element name="param2" type="xsd:int" />
|
|
</xsd:sequence>
|
|
</xsd:complexType>
|
|
</xsd:element>
|
|
...
|
|
<wsdl:message name="response" />
|
|
<part name="parameters" element="ns:myMethod" />
|
|
</wsdl:message name="response" />
|
|
|
|
<wsdl:message name="response" />
|
|
...
|
|
<wsdl:operation name="myMethod">
|
|
<input name="input" message="request" />
|
|
<output name="output" message="response" />
|
|
</wsdl:operation></pre>
|
|
|
|
<p>Java:</p>
|
|
<pre>void myMethod(String param1, int param2) ...</pre></li>
|
|
|
|
<li><p><strong>Parameter mapping</strong>
|
|
<br>If the document and literal wrapped format is not detected, the parameter mapping follows the normal JAX-RPC mapping rules set in section 4.3.4 of the JAX-RPC specification.</p>
|
|
<p>Each parameter is defined by a wsdl:message part referenced from the input and output elements.</p>
|
|
<ul>
|
|
<li>A wsdl:part in the request wsdl:message is mapped to an input parameter.</li>
|
|
<li>A wsdl:part in the response wsdl:message is mapped to the return value. If there are multiple wsdl:parts in the response message, they are mapped to output parameters.
|
|
<ul>
|
|
<li>A Holder class is generated for each output parameter as discussed in section 4.3.5 of the JAX-RPC specification.</li>
|
|
</ul></li>
|
|
<li>A wsdl:part that is both the request and response wsdl:message is mapped to an inout parameter.
|
|
<ul>
|
|
<li>A Holder class is generated for each inout parameter as discussed in section 4.3.5 of the JAX-RPC specification.</li>
|
|
<li>The wsdl:operation parameterOrder attribute defines the order of the parameters.</li>
|
|
</ul></li>
|
|
</ul>
|
|
<p>The WSDL2Java command supports overloaded methods, but confirm that the part names of the overloaded methods are unique. For example:</p>
|
|
|
|
<p>XML:</p>
|
|
<pre><wsdl:message name="request" >
|
|
<part name="param1" type="xsd:string" />
|
|
<part name="param2" type="xsd:int" />
|
|
</wsdl:message name="response" />
|
|
|
|
<wsdl:message name="response" />
|
|
...
|
|
<wsdl:operation name="myMethod" parameterOrder="param1, param2">
|
|
<input name="input" message="request" />
|
|
<output name="output" message="response" />
|
|
</wsdl:operation></pre>
|
|
|
|
<p>Java:</p>
|
|
<pre>void myMethod(String param1, int param2) ...</pre></li>
|
|
</ul>
|
|
|
|
<p><strong>Mapping of wsdl:binding</strong></p>
|
|
|
|
<p>The WSDL2Java command uses the wsdl:binding information to generate an implementation specific client side stub. WebSphere Application Server uses the wsdl:binding information on the server side to properly deserialize the request, invoke the Web service, and serialize the response. The information in the wsdl:binding should not affect the generation of the Service Endpoint Interface, but it can when the document and literal wrapped format is used or when there are MIME attachments.</p>
|
|
|
|
<ul>
|
|
<li><p><strong>MIME attachments</strong>
|
|
<br>For a WSDL 1.1 compliant WSDL file, a part of an operation message, which is defined in the binding to be a MIME attachment, becomes a parameter of the type of the attachment regardless of the part declared. For example:</p>
|
|
|
|
<p>XML:</p>
|
|
<pre><wsdl:types>
|
|
<schema ...>
|
|
<complexType name="ArrayOfBinary">
|
|
<restriction base="soapenc:Array">
|
|
<attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:binary[]" />
|
|
</restriction>
|
|
</complexType>
|
|
</schema>
|
|
</wsdl:types>
|
|
|
|
<wsdl:message name="request">
|
|
<part name="param1" type="ns:ArrayOfBinary" />
|
|
<wsdl:message name="response" />
|
|
|
|
<wsdl:message name="response" />
|
|
...
|
|
|
|
<wsdl:operation name="myMethod">
|
|
<input name="input" message="request" />
|
|
<output name="output" message="response" />
|
|
</wsdl:operation>
|
|
...
|
|
|
|
<binding ...
|
|
<wsdl:operation name="myMethod">
|
|
<input>
|
|
<mime:multipartRelated>
|
|
<mime:part>
|
|
<mime:content part="param1" type="image/jpeg"/>
|
|
</mime:part>
|
|
</mime:multipartRelated>
|
|
</input>
|
|
...
|
|
</wsdl:operation></pre>
|
|
|
|
<p>Java:</p>
|
|
<pre>void myMethod(java.awt.Image param1) ...</pre>
|
|
|
|
<p>The JAX-RPC requires support for the following MIME types:</p>
|
|
<table cellspacing="2" cellpadding="2" border="1">
|
|
<tr>
|
|
<th id="col1">MIME type</th>
|
|
<th id="col2">Java type</th>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">image/gif</td>
|
|
<td headers="col2">java.awt.Image</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">image/jpeg</td>
|
|
<td headers="col2">java.awt.Image</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">text/plain</td>
|
|
<td headers="col2">java.lang.String</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">multipart/*</td>
|
|
<td headers="col2">javax.mail.internet.MimeMultipart</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">text/xml</td>
|
|
<td headers="col2">javax.xml.transform.Source</td>
|
|
</tr>
|
|
<tr>
|
|
<td headers="col1">application/xml</td>
|
|
<td headers="col2">javax.xml.transform.Source</td>
|
|
</tr>
|
|
</table>
|
|
<p>There are a number of problems with MIME attachments as they are defined in WSDL 1.1, including:</p>
|
|
<ul>
|
|
<li>The semantics of the mime:multipartRelated clause are not fully defined.</li>
|
|
<li>The semantics do not allow for arrays of MIME attachments.</li>
|
|
</ul>
|
|
<p>Because of these problems, several types are not specified by the JAX-RPC for MIME attachments. These types are defined in the supported mappings previously discussed.</p></li>
|
|
|
|
<li><p><strong>Headers</strong>
|
|
<br>A wsdl:binding can also define SOAP headers, for example:</p>
|
|
|
|
<p>XML:</p>
|
|
<pre><wsdl:message name="request">
|
|
<part name="param1" type="xsd:string" />
|
|
</wsdl:message/>
|
|
|
|
<wsdl:message name="response" />
|
|
|
|
<wsdl:operation name="myMethod">
|
|
<input name="input" message="request" />
|
|
<output name="output" message="response" />
|
|
</wsdl:operation>
|
|
|
|
|
|
<binding ...
|
|
<wsdl:operation name="myMethod">
|
|
<input>
|
|
<soap:header message="request" part="param1" use="literal" />
|
|
</input>
|
|
|
|
</wsdl:operation></pre>
|
|
|
|
<p>Java:</p>
|
|
<pre>void myMethod(String param1) ...</pre>
|
|
|
|
<p>This is an example of an explicit header or a header with a value determined from a method parameter. Instead of appearing in the soap:body SOAP message, the value of param1 now appears in the soap:header SOAP message. The WSDL2Java command supports explicit headers and does not support implicit headers. Implicit headers have a value not determined by a parameter. For example, you could replace the soap:header clause in the example with:</p>
|
|
<pre><soap:header message="someOtherMsgNotAppearingInthePortType"
|
|
part="someOtherPart" use="literal"/> </pre>
|
|
<p><strong>Note:</strong> The WSDL2Java command supports explicit headers, but it is not considered good programming practice to use them. Headers are typically used for middleware logic, not business logic. Explicit headers place parameters used in business logic into the header.</p></li>
|
|
</ul>
|
|
|
|
<p><strong>Mapping of wsdl:service</strong></p>
|
|
|
|
<p>The wsdl:service element is mapped to a Generated Service interface. The Generated Service interface contains methods to access each of the ports in the wsdl:service. The Generated Service interface is discussed in sections 4.3.9, 4.3.10, and 4.3.11 of the JAX-RPC specification.</p>
|
|
|
|
<p>In addition, the wsdl:service element is mapped to the implementation-specific ServiceLocator class, which is an implementation of the Generated Service interface.</p>
|
|
|
|
<p><strong><a name="w2s"></a>Mapping between WSDL and SOAP messages</strong></p>
|
|
|
|
<p>The WSDL file defines the format of the SOAP message that is sent over the wire. The WSDL2Java command and the WebSphere Application Server run time use the information in the WSDL file to confirm that the SOAP message is properly serialized and deserialized.</p>
|
|
|
|
<p><strong>Document versus RPC, literal versus encoded</strong></p>
|
|
|
|
<p>If a wsdl:binding indicates a message is sent using an RPC format, the SOAP message contains an element defining the operation. If a wsdl:binding indicates the message is sent using a document format, the SOAP message does not contain the operation element.</p>
|
|
|
|
<p>If the wsdl:part is defined using the type attribute, the name and type of the part are used in the message. If the wsdl:part is defined using the element attribute, the name and type of the element are used in the message. The element attribute is not allowed by the JAX-RPC specification when use="encoded".</p>
|
|
|
|
<p>If a wsdl:binding indicates a message is encoded, the values in the message are sent with xsi:type information. If a wsdl:binding indicates that a message is literal, the values in the message are typically not sent with xsi:type information. For example:</p>
|
|
|
|
<p>WSDL:</p>
|
|
<pre><xsd:element name="c" type="xsd:int" />
|
|
...
|
|
<wsdl:message name="request">
|
|
<part name="a" type="xsd:string" />
|
|
<part name="b" element="ns:c" />
|
|
</wsdl:message>
|
|
...
|
|
<wsdl:operation name="method" >
|
|
<input message="request" />
|
|
...</pre>
|
|
|
|
<p>RPC/ENCODED:</p>
|
|
<pre><soap:body>
|
|
<ns:method>
|
|
<a xsi:type="xsd:string">ABC</a>
|
|
<element attribute is not allowed in rpc/encoded mode>
|
|
</ns:method>
|
|
</soap:body></pre>
|
|
|
|
<p>DOCUMENT/LITERAL:</p>
|
|
<pre><soap:body>
|
|
<a>ABC</a>
|
|
<c>123</a>
|
|
</soap:body></pre>
|
|
|
|
<p>DOCUMENT/LITERAL wrapped:</p>
|
|
<pre><soap:body>
|
|
<ns:method_wrapper>
|
|
<a>ABC</a>
|
|
<c>123</a>
|
|
<ns:method_wrapper>
|
|
</soap:body></pre>
|
|
|
|
<p>The document and literal wrapped mode is the same as the document and literal mode. However, in the document and literal wrapped mode, there is only a single element within the body, and the element has the same name as the operation.</p>
|
|
|
|
<p><strong>Multi-ref processing</strong></p>
|
|
|
|
<p>If use=encoded, XML types that are not simpleTypes are passed in the SOAP message using the multi-ref attributes, href and id. The following example assumes that parameters one and two reference the same Java bean named, info containing fields a and b:</p>
|
|
|
|
<p><strong>Note:</strong> Deserialization produces a single instance of the info class for the encoded case, and two instances for the literal case.</p>
|
|
|
|
<p>RPC/ENCODED:</p>
|
|
<pre><soap:body>
|
|
<ns:method>
|
|
<param1 href="#id1" />
|
|
<param2 href="#id2" />
|
|
<ns:method>
|
|
<multiref id="id1" xsi:type="ns:info">
|
|
<a xsi:type="xsi:string">hello<a>
|
|
<b xsi:type="xsi:string">world</b>
|
|
</multiref>
|
|
</soap:body></pre>
|
|
|
|
<p>RPC/LITERAL:</p>
|
|
<pre><soap:body>
|
|
<ns:method>
|
|
<param1>
|
|
<a>hello</a>
|
|
<b>world</b>
|
|
</param1>
|
|
<param2>
|
|
<a>hello</a>
|
|
<b>world</b>
|
|
</param2>
|
|
<ns:method>
|
|
</soap:body></pre>
|
|
|
|
<p><strong>XML arrays and the maxOccurs attribute</strong></p>
|
|
|
|
<p>A SOAP message is affected by whether the element is defined by an XML array or using the maxOccurs attribute.</p>
|
|
|
|
<p>WSDL:</p>
|
|
<pre><element name="foo" type="ns:ArrayOfString" /></pre>
|
|
|
|
<p>Literal Instance:</p>
|
|
<pre> <foo>
|
|
<item>A</item>
|
|
<item>B</item>
|
|
<item>C</item>
|
|
</foo></pre>
|
|
|
|
<p>WSDL:</p>
|
|
<pre><element name="foo" maxOccurs="unbounded" type="xsd:string"/></pre>
|
|
|
|
<p>Literal Instance:</p>
|
|
<pre> <foo>A</foo>
|
|
<foo>B</foo>
|
|
<foo>C</foo></pre>
|
|
|
|
<p><strong>minOccurs and nillable attributes</strong></p>
|
|
|
|
<p>An element specified with minOccurs=0 that has a null value is not serialized in the SOAP message. An element specifying nillable="true" has a null value and is serialized into a SOAP message with the xsi:nil=true attribute. For example:</p>
|
|
|
|
<pre><a xsi:nil="true" /></pre>
|
|
|
|
|
|
<p><strong>Qualified versus unqualified</strong></p>
|
|
|
|
<p>The XML schema attributeForm and elementForm attributes indicate whether the attributes and nested elements are serialized with qualified or unqualified names. If a part name is serialized, it is always serialized as an unqualified name.</p>
|
|
|
|
</body>
|
|
</html>
|