You are viewing a plain text version of this content. The canonical link for it is here.

Posted to java-user@axis.apache.org by Mohit_Goyal <Mo...@satyam.com> on 2006/03/10 05:11:31 UTC

Re: Confused about more advanced WSDD usage

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
<mhtml:file://C:\Documents%20and%20Settings\mg18310\Desktop\Web%20Servic
es%20Docs\Web%20Services%20in%20a%20Service-Oriented%20Architecture%20bl
ueprints.mht!https://bpcatalog.dev.java.net/nonav/soa/doc-schema/index.h
tml#code-example-1#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 WSDL

An 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
<mhtml:file://C:\Documents%20and%20Settings\mg18310\Desktop\Web%20Servic
es%20Docs\Web%20Services%20in%20a%20Service-Oriented%20Architecture%20bl
ueprints.mht!https://bpcatalog.dev.java.net/nonav/soa/doc-schema/index.h
tml#code-example-2#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 Imported

Now 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 submitPO method 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.

Re: Confused about more advanced WSDD usage

Posted by Anne Thomas Manes <at...@gmail.com>.

Did you have a question?

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

On 3/9/06, Mohit_Goyal <Mo...@satyam.com> wrote:
>
>  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 WSDL*
>
> An 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.xsdschema 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 Imported*
>
> Now 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 submitPO method 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.javaobjects 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..
>