Note that Example 1 is invalid WSDL for a document/literal service. When using document/literal, the message part definition must always reference an element rather than a type. You may reference a type only when using RPC style.
Anne
Lets consider some of the issues when using a schema-defined type to represent the XML document being exchanged between a client and service.
In describing this strategy, we will use an example of passing a PurchaseOrder XML document from a client to a service which receives the purchase order. The purchase order document being exchanged is a typical purchase order which includes data such as the order id, the contact information, and the line items for the goods being purchased.
Strategy: Using a Type Defined in Schema to Represent the XML Document
In this strategy the service interface artifacts (WSDL file, Java interface and implementation) would contain all the details of the PurchaseOrder structure since it would be exposed as part of the interface. A Web Service such as this when deployed with a document-literal formatting passes the XML document in the body of the SOAP message. For the WSDL file this means that all the elements of the schema would be embedded in the WSDL file or alternatively the schema of the document can be defined in a separate schema file and imported into the WSDL file. For the corresponding Java interface this means that all PurchaseOrder schema elements would need corresponding Java types to represent the PurchaseOrder. From the WSDL point of view, there is a coupling of WSDL to the schema for the document being exchanged for this operation.
For the choice of embedding the schema defenition directly into the WSDL file, this means that your interface would contain all the details of the fields and types for the structure of the document. The snippet of the WSDL in Code Example 1 below, the interface and implementation class below illustrate the purchase order details being embedded in the interface. This can be tricky to maintain since the purchase order type is actually part of the WSDL.
<?xml version="1.0" encoding="UTF-8" ?>
<definitions xmlns="http://schema.xmlsoap.org/wsdl/" xmlns:tns="urn:ObjectPurchaseOrderService" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schema.xmlsoap.org/wsdl/soap/" name="ObjectPurchaseOrderService" targetNamespace="urn:ObjectPurchaseOrderService">
<types>
<schema xmlns:soap11-enc="http://schema.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsdl="http://schema.xmlsoap.org/wsdl/" xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="urn:ObjectPurchaseOrderService">
<xsd:complexType name="Address">
<xsd:sequence>
<xsd:element name="street" type="xsd:string" nillable="false"/>
<xsd:element name="city" type="xsd:string" nillable="false"/>
<xsd:element name="state" type="xsd:string" nillable="false"/>
<xsd:element name="postalCode" type="xsd:string" nillable="false"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="LineItem">
<xsd:sequence>
<xsd:element name="itemId" type="xsd:string" nillable="false"/>
<xsd:element name="price" type="xsd:float" nillable="false"/>
<xsd:element name="quantity" type="xsd:int" nillable="false"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="PurchaseOrder">
<xsd:sequence>
<xsd:element name="poId" type="xsd:string" nillable="false"/>
<xsd:element name="createDate" type="xsd:date" nillable="false"/>
<xsd:element name="shipTo" type="Address" nillable="false"/>
<xsd:element name="billTo" type="Address" nillable="false"/>
<xsd:element name="items" type="LineItem" nillable="false" minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
</schema>
</types>
<message name="PurchaseOrderServiceSEI_submitPO">
<part name="PurchaseOrder_1" type="tns:PurchaseOrder" />
</message>
...
</definitions>
Code Example 1: WSDL File Snippet Showing a Purchase Order Schema Definition as a Parameter Type Definition Embedded in the WSDLAn alternative to embedding the document schema definition inside the WSDL is to define a type in a separate file and import it into the WSDL file. This makes it easier to maintain. In this strategy a purchaseorder.xsd schema file would be created. And then the WSDL file would import this type into the WSDL. Then just use it for the input parameter to service operations. Code Example 2 illustrates this strategy.
<types>
<schema targetNamespace="urn:SchemaDefinedPurchaseOrderService"
xmlns:soap11-enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns="http://www.w3.org/2001/XMLSchema">
<xsd:import namespace="http://java.sun.com/blueprints/ns/po" schemaLocation="PurchaseOrder.xsd"/>
<element name="submitPO">
<complexType>
<sequence>
<element name="inputDoc" type="pons:PurchaseOrder" nillable="true"/>
</sequence>
</complexType>
</element>
...
</schema>
</types>
<message name="SchemaDefinedPurchaseOrderServiceSEI_submitPO">
<part name="parameters" element="tns:submitPO"/>
</message>
...
<portType name="SchemaDefinedPurchaseOrderServiceSEI">
<operation name="submitPO">
<input message="tns:SchemaDefinedPurchaseOrderServiceSEI_submitPO"/>
...
</operation>
</portType>
Code Example 2: Snippet from the WSDL Showing a Purchase Order Schema Being ImportedNow lets consider the Java files that would be generated from these types of WSDL files. Just as the WSDL file must have all the details specified for the purchase order, the Java Interface would also need to reflect the types to represent a purchase order.
Make sure you choose type as wrapped when generating the WSDL. So that when u generated the java files using WSDL2Java you'll get a method signature like this:
public void purchaseOrder(String item, int quantity, String description)
So the endpoint will need a WSDL file, a Java interface, a Java implementation class with a
submitPOmethod that accepts the PurchaseOrder with the structure and types defined in the PurchaseOrder schema, and also possibly some helper Java classes to represent the PurchaseOrder. This seems like a natural interface for many Java programmers since it is similar to passing objects, which makes it a comfortable strategy for many developers. This strategy applies well for scenarios where there is a well defined schema for a document and a service needs to be built based on that schema. For example, building a service around a vertical industry standard Invoice document. This strategy benefits from being able to leverage the automatic schema validation of JAX-RPC. For example, when a PurchaseOrder document is received, the JAX-RPC runtime automatically validates an incoming PurchaseOrder against the PurchaseOrder schema before dispatching to the service implementation class, which can save the developer some coding. Also, this strategy can benefit form the automatic binding to Java objects provided by JAX-RPC. For instance, in the purchase order example above, the XML PurchaseOrder document is automatically bound to PurchaseOrder.java objects which are available in the signature of the submitPO method. This can save a developer from writing code to create Java objects from a received XML document.Note that the description of the document is tightly coupled to the service interface. So if you try to change the document definition, then you may need to change the interface or the WSDL. This can impact the evolution of the interface. With this strategy, it can be difficult to build a more generic service with a method that accepts many different types of documents since the service operation is tightly bound to the schema of a single document. In cases where the type of the document being exchanged is known, for example a vertical industry-defined schema, then this solution of using a schema defined type in the interface works very well. This also is a commonly used solution.
DISCLAIMER:
This email (including any attachments) is intended for the sole use of the intended recipient/s and may contain material that is CONFIDENTIAL AND PRIVATE COMPANY INFORMATION. Any review or reliance by others or copying or distribution or forwarding of any or all of the contents in this message is STRICTLY PROHIBITED. If you are not the intended recipient, please contact the sender by email and delete all copies; your cooperation in this regard is appreciated..
