You are viewing a plain text version of this content. The canonical link for it is here.
Posted to axis-cvs@ws.apache.org by ds...@apache.org on 2006/10/10 11:41:06 UTC
svn commit: r454672 - in /webservices/axis2/branches/java/1_1/xdocs:
1_1/jibx/ jibx/
Author: dsosnoski
Date: Tue Oct 10 02:41:05 2006
New Revision: 454672
URL: http://svn.apache.org/viewvc?view=rev&rev=454672
Log:
AXIS2-729 JiBX documentation link fix and improvements, including unwrapped support (1.1)
Added:
webservices/axis2/branches/java/1_1/xdocs/1_1/jibx/jibx-doclit-example.html
webservices/axis2/branches/java/1_1/xdocs/1_1/jibx/jibx-unwrapped-example.html
webservices/axis2/branches/java/1_1/xdocs/jibx/jibx-doclit-example.html
webservices/axis2/branches/java/1_1/xdocs/jibx/jibx-unwrapped-example.html
Modified:
webservices/axis2/branches/java/1_1/xdocs/1_1/jibx/jibx-codegen-integration.html
webservices/axis2/branches/java/1_1/xdocs/jibx/jibx-codegen-integration.html
Modified: webservices/axis2/branches/java/1_1/xdocs/1_1/jibx/jibx-codegen-integration.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/jibx/jibx-codegen-integration.html?view=diff&rev=454672&r1=454671&r2=454672
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/1_1/jibx/jibx-codegen-integration.html (original)
+++ webservices/axis2/branches/java/1_1/xdocs/1_1/jibx/jibx-codegen-integration.html Tue Oct 10 02:41:05 2006
@@ -1,34 +1,42 @@
<html>
<head>
<meta http-equiv="content-type" content="">
- <title></title>
+ <title>JiBX Integration with Axis2</title>
</head>
<body>
<h1>JiBX Integration With Axis2</h1>
-<p>This document will explain the usage of JiBX with Axis2 in order to expose
-existing Java code as a Web service and to implement a client for an existing
-Web service (or the service stubs for implementing the service).</p>
+<p>This document describes using JiBX data binding with Axis2. JiBX differs from
+the other data binding techniques supported by Axis2 in that it allows you to
+use your own Java data objects (as opposed to Java data objects generated from a
+schema definition). JiBX also provides a nicer form of unwrapped Web services
+interface than is supported by the other data binding techniques. On the
+downside, JiBX requires more setup than the other data binding techniques - in
+particular, you need to come up with a set of data classes and a binding
+definition in order to work with JiBX in Axis2.</p>
<h2>Content</h2>
<ul>
<li><a href="#intro">Introduction</a></li>
+ <li><a href="#wrapped">Wrapped vs. unwrapped</a></li>
<li><a href="#java">Starting from Java</a></li>
<li><a href="#wsdl">Starting from WSDL</a></li>
<li><a href="#codegen">Axis2 JiBX Code Generation</a></li>
<li><a href="#coming">Coming Attractions</a></li>
</ul>
-<a name="intro"></a>
-<h2>Introduction</h2>
+<a name="intro"></a><h2>Introduction</h2>
<p><a href="http://www.jibx.org">JiBX data binding</a> supports fast and
flexible conversions between plain old Java objects (POJOs) and XML. JiBX
-uses a mapped binding approach that's based on a binding definition document
-you provide. This lets you customize the way your Java objects are converted
-to and from XML. These features make JiBX especially useful if you're
-developing a Web service based on existing Java code.</p>
+uses a mapped binding approach that's based on binding definition documents
+you provide. This approach lets you customize the way your Java objects are
+converted to and from XML. You can even define multiple bindings to use the same
+Java objects with different XML representations. These features make JiBX
+especially useful if you're developing a Web service based on existing Java
+code, or when you need to support multiple XML representations for a Web service
+(as when you're using versioned schema definitions).</p>
<p>Axis2 supports using JiBX with your Web services, including generating the
necessary linkage code for both client and server sides. However, the Axis2
@@ -48,87 +56,123 @@
users understand the basic approach to working with JiBX in Axis2. You can
find full instructions on the standard JiBX parts of this sequence on the <a
href="http://www.jibx.org">JiBX Web site</a>.</p>
-<a name="java"></a>
-<h2>Starting from Java</h2>
+<a name="intro"></a><h2>Wrapped vs. unwrapped</h2>
+
+<p>Axis2 support for JiBX currently only works with the document-literal
+(doc/lit) form of Web services definitions. Doc/lit Web services generally use
+particular schema elements as input and output from each operation, and the
+Axis2 support for JiBX assumes this structure (which is also the structure
+required for compatibility with the
+<a href="http://www.ws-i.org/Profiles/BasicProfile-1.1.html">WS-I Basic Profile</a>).</p>
+
+<p>A popular subset of doc/lit Web services use a form called "wrapped". Wrapped
+doc/lit Web services define service operations that correspond to method calls,
+using input and output element names based on the method name and embedding the
+actual parameter values for the method call within the input element.</p>
+
+<p>When used with Axis2, JiBX supports both general doc/lit and wrapped service
+definitions. Wrapped service definitions can be "unwrapped" during code
+generation to provide a greatly simplified interface. JiBX unwrapping of service
+definitions is not compatible with the unwrapping support for other data binding
+frameworks used with Axis2, but most users will find the JiBX approach easy and
+convenient. See the <a href="./jibx-unwrapped-example.html">JiBX Unwrapped
+Example</a> and the <a href="./jibx-doclit-example.html">JiBX Document/Literal
+Example</a> pages for a detailed comparison of the two forms of service
+interface.</p>
+
+<a name="java"></a><h2>Starting from Java</h2>
<p>Here's the sequence of steps for using JiBX with Axis2 to expose existing
Java code as a Web service:</p>
<ol>
<li>Create a JiBX binding definition for the data being transferred by the
- Web service</li>
+ Web service (you may be able to use the JiBX binding generator to help with
+ this step).</li>
<li>Create a schema that matches the XML defined by your binding (you may
- be able to use the JiBX schema generator to help with this)</li>
+ be able to use the JiBX schema generator to help with this). If you're using
+ a wrapped form of interface to your service you'll also need to create
+ schema definitions for the wrapper input and output elements used by each
+ operation.</li>
<li>Create a WSDL document for your service, with the schema embedded or
imported.</li>
<li>Generate Axis2 server-side linkage code using WSDL2Java with the WSDL
- and your binding definition</li>
+ and your binding definition.</li>
<li>Run the JiBX binding compiler on your Java classes to add the actual
- binding code</li>
+ binding code.</li>
<li>Include the <i>axis2-jibx.jar</i> in your runtime classpath, along with
- the <i>jibx-runtime.jar</i> (normally done by including these in the
- <i>axis2/WEB-INF/lib</i> directory)</li>
+ the <i>jibx-runtime.jar</i>.</li>
</ol>
-<p><strong>The above is assuming:</strong></p>
-<ol>
- <li>Your code already provides methods to implement the operations you want
- to expose as a Web service</li>
- <li>These methods each take a single parameter object that's unique to the
- method</li>
- <li>Each return a single response object.</li>
-</ol>
+<p>If you use a wrapped interface for your Web service you can expose method
+calls in your existing code directly as operations in the service. In this case
+you normally just use your existing data objects with JiBX data binding, and add
+schema definitions for the wrapper elements. See the
+<a href="./jibx-unwrapped-example.html">JiBX Unwrapped Example</a> page for more
+details on how this works.</p>
+
+<p>If you use a non-wrapped interface for your Web service you need to define
+classes to hold the data input and output from each operation. In this case
+these holder classes need to be included in the JiBX binding definition. See the
+<a href="./jibx-doclit-example.html">JiBX Document/Literal Example</a> page for
+more details on this case.</p>
-<p>If this is <i>not</i> the case, you'll also need to create wrapper classes
-and perhaps wrapper methods for now. See the <a
-href="jibx-example.html">JiBX example</a> for more details on this.</p>
-<a name="wsdl"></a>
-
-<h2>Starting from WSDL</h2>
+<a name="wsdl"></a><h2>Starting from WSDL</h2>
<p>Here's the sequence of steps for using JiBX with Axis2 to implement a
-client for an existing Web service (or the service stubs for implementing the
-service):</p>
+client for an existing Web service (or the actual service, when you've been
+supplied with the WSDL your service is to implement):</p>
<ol>
<li>Create Java classes for the data being transferred by the Web service,
and a JiBX binding definition that maps these classes to the schema
defined by the Web service (you may be able to use the JiBX xsd2jibx tool
- to help with this)</li>
+ to help with this).</li>
<li>Generate Axis2 client linkage code using WSDL2Java with the WSDL and
- your binding definition</li>
+ your binding definition.</li>
<li>Run the JiBX binding compiler on your Java classes to add the actual
- binding code</li>
+ binding code.</li>
<li>Include the <i>axis2-jibx.jar</i> in your runtime classpath, along with
the <i>jibx-runtime.jar</i></li>
</ol>
-<a name="codegen"></a>
-<h2>Axis2 JiBX Code Generation</h2>
+<p>As with the starting from Java case, there are some differences in the
+handling depending on whether your service definition fits the wrapped form. See
+the <a href="./jibx-unwrapped-example.html">JiBX Unwrapped Example</a> and
+<a href="./jibx-doclit-example.html">JiBX Document/Literal Example</a> pages for
+more details.</p>
+
+<a name="codegen"></a><h2>WSDL2Java usage</h2>
<p>To run the WSDL2Java tool for JiBX data binding you need:</p>
<ol>
<li>To specify <i>-d jibx</i> to select JiBX binding.</li>
<li>You also need an additional parameter, <i>-Ebindingfile {file}</i>
- (where <i>{file}</i> is the file path to your JiBX binding
- definition).</li>
- <li>Finally, you need to have the <i>axis2-jibx.jar</i>, the
- <i>jibx-bind-1.1beta2.jar</i>, and the <i>jibx-run-1.1beta2.jar</i> files
+ (where <i>{file}</i> is the file path to your JiBX binding definition).</li>
+ <li>Finally, you need to have the <i>axis2-jibx-XXXX.jar</i>, the
+ <i>jibx-bind-XXXX.jar</i>, and the <i>jibx-run-XXXX.jar</i> files
from your Axis2 distribution included in the WSDL2Java classpath.</li>
</ol>
-<a name="coming"></a>
-
-<h2>Coming Attractions</h2>
-<p>Soon after the release of Axis2 1.0 the JiBX support will be extended to
-support automatic handling of "wrapped" doc/lit services. This will
-dramatically reduce the number of classes that need to be defined for working
-with simple services, and simplify both starting from Java and starting from
-WSDL.</p>
-
-<p>The full JiBX 1.1 release will also provide much improved support for code
-generation from schemas, and for binding+schema generation from code, and
-these features will be integrated into the Axis2 JiBX support. Check the <a
-href="http://www.jibx.org">JiBX project site</a> for updates on both JiBX 1.1
+<p>If you want to use the unwrapped form of interface you also need to specify
+the <i>-uw</i> option to WSDL2Java. In this case your JiBX binding definition
+must include abstact mappings for all the complex objects which correspond to
+method parameters, and each abstract mapping must specify a <i>type-name</i>
+attribute that matches the schema <i>complexType</i> used in the WSDL. You can
+also use formats in the binding definition to define the handling of schema
+<i>simpleType</i>s. Schema types corresponding to Java primitives and simple
+objects with build-in JiBX conversions are handled automatically.</p>
+
+<p>If you're not unwrapping the interface, your JiBX binding definition must
+include a concrete mapping for each element used as input or output by any
+operation.</p>
+
+<a name="coming"></a><h2>Coming Attractions</h2>
+
+<p>Work is in-progress on better tools to support generating Java classes and
+corresponding JiBX binding definitions from an input schema, and also for
+generating binding+schema generation from existing code. These features will be
+integrated into the Axis2 JiBX support when they're available. Check the <a
+href="http://www.jibx.org">JiBX project site</a> for updates on both JiBX
and the Axis2 JiBX support.</p>
<h2>References</h2>
Added: webservices/axis2/branches/java/1_1/xdocs/1_1/jibx/jibx-doclit-example.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/jibx/jibx-doclit-example.html?view=auto&rev=454672
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/1_1/jibx/jibx-doclit-example.html (added)
+++ webservices/axis2/branches/java/1_1/xdocs/1_1/jibx/jibx-doclit-example.html Tue Oct 10 02:41:05 2006
@@ -0,0 +1,285 @@
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>JiBX general document/literal</title>
+</head>
+
+<body>
+<h1>JiBX general document/literal</h1>
+
+<p>Code generation for JiBX data binding converts operations defined by a Web
+service to method calls. With general document/literal (doc/lit) Web services
+the generated methods each take a single parameter object and return a single
+result object. Here's a sample doc/lit WSDL (partial) by way of an example:</p>
+
+<pre>
+<wsdl:definitions targetNamespace="http://ws.sosnoski.com/library/wsdl"
+ xmlns:tns="http://ws.sosnoski.com/library/types"
+ xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
+ xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/">
+
+ <wsdl:types>
+
+ <schema elementFormDefault="qualified"
+ targetNamespace="http://ws.sosnoski.com/library/types"
+ xmlns="http://www.w3.org/2001/XMLSchema">
+
+ <element name="getBook">
+ <complexType>
+ <sequence>
+ <element name="isbn" type="string"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="getBookResponse">
+ <complexType>
+ <sequence>
+ <element name="book" minOccurs="0" type="tns:BookInformation"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="addBook">
+ <complexType>
+ <sequence>
+ <element name="type" type="string"/>
+ <element name="isbn" type="string"/>
+ <element name="author" minOccurs="0" maxOccurs="unbounded" type="string"/>
+ <element name="title" type="string"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="addBookResponse">
+ <complexType>
+ <sequence>
+ <element name="success" type="boolean"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <complexType name="BookInformation">
+ <sequence>
+ <element name="author" minOccurs="0" maxOccurs="unbounded" type="string"/>
+ <element name="title" type="string"/>
+ </sequence>
+ <attribute name="type" use="required" type="string"/>
+ <attribute name="isbn" use="required" type="string"/>
+ </complexType>
+
+ </schema>
+
+ </wsdl:types>
+
+ <wsdl:message name="getBookRequest">
+ <wsdl:part element="wns:getBook" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:message name="getBookResponse">
+ <wsdl:part element="wns:getBookResponse" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:message name="addBookRequest">
+ <wsdl:part element="wns:addBook" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:message name="addBookResponse">
+ <wsdl:part element="wns:addBookResponse" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:portType name="Library">
+
+ <wsdl:operation name="getBook">
+ <wsdl:input message="wns:getBookRequest" name="getBookRequest"/>
+ <wsdl:output message="wns:getBookResponse" name="getBookResponse"/>
+ </wsdl:operation>
+
+ <wsdl:operation name="addBook">
+ <wsdl:input message="wns:addBookRequest" name="addBookRequest"/>
+ <wsdl:output message="wns:addBookResponse" name="addBookResponse"/>
+ </wsdl:operation>
+
+ </wsdl:portType>
+ ...
+</wsdl:definitions>
+</pre>
+
+<p>This WSDL defines a service with just two operations: <b>getBook</b> and
+<b>addBook</b>. The <b>getBook</b> operation takes a <i>getBook</i> element as
+input, and returns a <i>getBookResponse</i> element as output, while
+<b>addBook</b> takes an <i>addBook</i> element as input and returns an
+<i>addBookResponse</i> as output. Here's the body of the client interface
+generated by the standard JiBX code generation:</p>
+
+<pre>
+ public interface LibraryJibxUnwrapped {
+
+
+ /**
+ * Auto generated method signatures
+ * @param addBook
+ */
+ public com.sosnoski.ws.library.jibx.wrappers.AddBookResponse addBook(
+ com.sosnoski.ws.library.jibx.wrappers.AddBookRequest addBook) throws java.rmi.RemoteException
+
+
+ ;
+
+
+ /**
+ * Auto generated method signatures
+ * @param getBook
+ */
+ public com.sosnoski.ws.library.jibx.wrappers.GetBookResponse getBook(
+ com.sosnoski.ws.library.jibx.wrappers.GetBookRequest getBook) throws java.rmi.RemoteException
+
+
+ ;
+
+
+
+ //
+ }
+</pre>
+
+<p>You can see that the JiBX code generation converted the operations into
+simple method call interfaces using objects corresponding to the input and
+output elements of the operation (see
+<a href="./jibx-unwrapped-example.html">JiBX Unwrapped Example</a> for the
+interface generated when unwrapping is instead used). The server-side interface
+is the same.</p>
+
+<p>You need to supply an appropriate JiBX binding definition for use in code
+generation (using the <i>-Ebindingfile {file}</i> parameter for WSDL2Java - see
+<a href="./jibx-codegen-integration.html#codegen">JiBX Codegen Integration -
+WSDL2Java usage</a> for more details). This must define concrete <i>mapping</i>s
+for each element used as the input or output of an operation. The JiBX code
+generation extension matches the element names to the binding in order to
+determine the corresponding class to use in generated code.</p>
+
+<p>For example, here's a binding definition that matches the above WSDL:</p>
+
+<pre>
+<binding add-constructors="true">
+
+ <namespace uri="http://ws.sosnoski.com/library/types" default="elements"/>
+
+ <mapping name="getBook"
+ class="com.sosnoski.ws.library.jibx.wrappers.GetBookRequest">
+ <value name="isbn" field="m_isbn"/>
+ </mapping>
+
+ <mapping name="getBookResponse"
+ class="com.sosnoski.ws.library.jibx.wrappers.GetBookResponse">
+ <structure name="book" field="m_book"/>
+ </mapping>
+
+ <mapping name="addBook"
+ class="com.sosnoski.ws.library.jibx.wrappers.AddBookRequest">
+ <structure field="m_book">
+ <value name="type" field="m_type"/>
+ <value name="isbn" field="m_isbn"/>
+ <collection field="m_authors">
+ <value name="author" type="java.lang.String"/>
+ </collection>
+ <value name="title" field="m_title"/>
+ </structure>
+ </mapping>
+
+ <mapping name="addBookResponse"
+ class="com.sosnoski.ws.library.jibx.wrappers.AddBookResponse"/>
+
+ <mapping abstract="true" class="com.sosnoski.ws.library.jibx.beans.Book">
+ <value name="type" style="attribute" field="m_type"/>
+ <value name="isbn" style="attribute" field="m_isbn"/>
+ <collection field="m_authors">
+ <value name="author" type="java.lang.String"/>
+ </collection>
+ <value name="title" field="m_title"/>
+ </mapping>
+
+</binding>
+</pre>
+
+<p>And here are the actual data object classes:</p>
+
+<pre>
+package com.sosnoski.ws.library.jibx.wrappers;
+
+import com.sosnoski.ws.library.jibx.beans.Book;
+
+public class AddBookRequest
+{
+ private Book m_book;
+
+ public AddBookRequest(Book book) {
+ m_book = book;
+ }
+
+ public Book getBook() {
+ return m_book;
+ }
+}
+
+public class AddBookResponse
+{
+}
+
+public class GetBookRequest
+{
+ private String m_isbn;
+
+ public GetBookRequest(String isbn) {
+ m_isbn = isbn;
+ }
+
+ public String getIsbn() {
+ return m_isbn;
+ }
+}
+
+public class GetBookResponse
+{
+ private Book m_book;
+
+ public GetBookResponse(Book book) {
+ m_book = book;
+ }
+
+ public Book getBook() {
+ return m_book;
+ }
+}
+
+package com.sosnoski.ws.library.jibx.beans;
+
+public class Book
+{
+ private String m_type;
+ private String m_isbn;
+ private String m_title;
+ private String[] m_authors;
+
+ public Book() {}
+
+ public String getType() {
+ return m_type;
+ }
+
+ public String getIsbn() {
+ return m_isbn;
+ }
+
+ public String getTitle() {
+ return m_title;
+ }
+
+ public String[] getAuthors() {
+ return m_authors;
+ }
+}
+</pre>
+
+</body>
+</html>
Added: webservices/axis2/branches/java/1_1/xdocs/1_1/jibx/jibx-unwrapped-example.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/jibx/jibx-unwrapped-example.html?view=auto&rev=454672
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/1_1/jibx/jibx-unwrapped-example.html (added)
+++ webservices/axis2/branches/java/1_1/xdocs/1_1/jibx/jibx-unwrapped-example.html Tue Oct 10 02:41:05 2006
@@ -0,0 +1,264 @@
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>JiBX unwrapped document/literal</title>
+</head>
+
+<body>
+<h1>JiBX unwrapped document/literal</h1>
+
+<p>Code generation for JiBX data binding converts operations defined by a Web
+service to method calls. In the most general case of document/literal (doc/lit)
+Web services the generated methods each take a single parameter object and
+return a single result object. This type of interface can be painful for
+developers because it adds both a layer of indirection and potentially a large
+number of extra classes (one input and one output class for each generated
+method).</p>
+
+<p>Fortunately, there's an alternative way of generating methods that gives a
+much more usable API for many Web services. This alternative is called
+<i>unwrapping</i>, and the service definitions that it applies to are called
+<i>wrapped</i> definitions. The key difference that qualifies a service
+definition as wrapped is the structure of the input and output elements used
+for operations.</p>
+
+<p>Here's a sample wrapped WSDL (partial) by way of an example:</p>
+
+<pre>
+<wsdl:definitions targetNamespace="http://ws.sosnoski.com/library/wsdl"
+ xmlns:tns="http://ws.sosnoski.com/library/types"
+ xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
+ xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/">
+
+ <wsdl:types>
+
+ <schema elementFormDefault="qualified"
+ targetNamespace="http://ws.sosnoski.com/library/types"
+ xmlns="http://www.w3.org/2001/XMLSchema">
+
+ <element name="getBook">
+ <complexType>
+ <sequence>
+ <element name="isbn" type="string"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="getBookResponse">
+ <complexType>
+ <sequence>
+ <element name="book" minOccurs="0" type="tns:BookInformation"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="addBook">
+ <complexType>
+ <sequence>
+ <element name="type" type="string"/>
+ <element name="isbn" type="string"/>
+ <element name="author" minOccurs="0" maxOccurs="unbounded" type="string"/>
+ <element name="title" type="string"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="addBookResponse">
+ <complexType>
+ <sequence>
+ <element name="success" type="boolean"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <complexType name="BookInformation">
+ <sequence>
+ <element name="author" minOccurs="0" maxOccurs="unbounded" type="string"/>
+ <element name="title" type="string"/>
+ </sequence>
+ <attribute name="type" use="required" type="string"/>
+ <attribute name="isbn" use="required" type="string"/>
+ </complexType>
+
+ </schema>
+
+ </wsdl:types>
+
+ <wsdl:message name="getBookRequest">
+ <wsdl:part element="wns:getBook" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:message name="getBookResponse">
+ <wsdl:part element="wns:getBookResponse" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:message name="addBookRequest">
+ <wsdl:part element="wns:addBook" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:message name="addBookResponse">
+ <wsdl:part element="wns:addBookResponse" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:portType name="Library">
+
+ <wsdl:operation name="getBook">
+ <wsdl:input message="wns:getBookRequest" name="getBookRequest"/>
+ <wsdl:output message="wns:getBookResponse" name="getBookResponse"/>
+ </wsdl:operation>
+
+ <wsdl:operation name="addBook">
+ <wsdl:input message="wns:addBookRequest" name="addBookRequest"/>
+ <wsdl:output message="wns:addBookResponse" name="addBookResponse"/>
+ </wsdl:operation>
+
+ </wsdl:portType>
+ ...
+</wsdl:definitions>
+</pre>
+
+<p>This WSDL defines a service with just two operations: <b>getBook</b> and
+<b>addBook</b>. The <b>getBook</b> operation takes a <i>getBook</i> element as
+input, and returns a <i>getBookResponse</i> element as output, while
+<b>addBook</b> takes an <i>addBook</i> element as input and returns an
+<i>addBookResponse</i> as output. Each of these input and output elements in
+turn consists of a sequence of child elements, with some of the child elements
+defined directly using standard schema types and others referencing user-defined
+schema types.</p>
+
+<p>As I said up front, this WSDL qualifies for unwrapped handling using JiBX.
+Here's the body of the client interface generated when using unwrapping (the
+<i>-uw</i> option for WSDL2Java):</p>
+
+<pre>
+ public interface LibraryJibxUnwrapped {
+
+
+ /**
+ * Auto generated method signatures
+ * @param type* @param isbn* @param author* @param title
+ */
+ public boolean addBook(
+ java.lang.String type,java.lang.String isbn,java.lang.String[] author,java.lang.String title) throws java.rmi.RemoteException
+
+
+ ;
+
+
+ /**
+ * Auto generated method signatures
+ * @param isbn
+ */
+ public com.sosnoski.ws.library.jibx.beans.Book getBook(
+ java.lang.String isbn) throws java.rmi.RemoteException
+
+
+ ;
+
+
+
+ //
+ }
+</pre>
+
+<p>You can see that the JiBX code generation converted the operations into
+simple method call interfaces without introducing any extraneous objects (see
+<a href="./jibx-doclit-example.html">JiBX Document/Literal Example</a> for the
+interface generated when unwrapping is not used). The server-side interface is
+the same.</p>
+
+<p>The key points that allow unwrapped handling with JiBX are:</p>
+
+<ol>
+<li>Each operation either accepts no input, or the input consists of a single
+element.</li>
+<li>Each input element is defined as a schema <i>complexType</i> consisting of a
+<i>sequence</i> of any number of child elements.</li>
+<li>Each operation either generates no output, or the output consists of a
+single element.</li>
+<li>Each output element is defined as a schema <i>complexType</i> consisting of a
+<i>sequence</i> that's either empty or contains a single child element.</li>
+<li>The child elements of both inputs and outputs are defined using <i>type</i>
+references, rather than an embedded type definitions.</li>
+</ol>
+
+<p>You also need to supply an appropriate JiBX binding definition (using the
+<i>-Ebindingfile {file}</i> parameter for WSDL2Java - see
+<a href="./jibx-codegen-integration.html#codegen">JiBX Codegen Integration -
+WSDL2Java usage</a> for more details). This must define abstract <i>mapping</i>s
+for the <i>complexType</i>s referenced by child elements of the inputs and
+outputs, with a <i>type-name</i> attribute matching the schema
+<i>complexType</i> name. If the child elements reference schema <i>simpleType</i>
+definitions the binding must also define a <i>format</i>s for each
+<i>simpleType</i>, with a <i>label</i> attribute matching the schema
+<i>simpleType</i> name. The binding definition must also specify the
+<i>force-classes='true'</i> attribute on the <i>binding</i> element.</p>
+
+<p>For example, here's a binding definition that matches the above WSDL:</p>
+
+<pre>
+<binding force-classes="true" xmlns:tns="http://ws.sosnoski.com/library/types">
+
+ <namespace uri="http://ws.sosnoski.com/library/types" default="elements"/>
+
+ <mapping abstract="true" class="com.sosnoski.ws.library.jibx.beans.Book"
+ type-name="tns:BookInformation">
+ <value name="type" style="attribute" field="m_type"/>
+ <value name="isbn" style="attribute" field="m_isbn"/>
+ <collection field="m_authors">
+ <value name="author"/>
+ </collection>
+ <value name="title" field="m_title"/>
+ </mapping>
+
+</binding>
+</pre>
+
+<p>And here's the actual <code>com.sosnoski.ws.library.jibx.beans.Book</code>
+class:</p>
+
+<pre>
+package com.sosnoski.ws.library.jibx.beans;
+
+public class Book
+{
+ private String m_type;
+ private String m_isbn;
+ private String m_title;
+ private String[] m_authors;
+
+ public Book() {}
+
+ public String getType() {
+ return m_type;
+ }
+
+ public String getIsbn() {
+ return m_isbn;
+ }
+
+ public String getTitle() {
+ return m_title;
+ }
+
+ public String[] getAuthors() {
+ return m_authors;
+ }
+}
+</pre>
+
+<p>The JiBX code generation for Axis2 currently requires that classes
+coresponding to unwrapped child elements (such as
+<code>com.sosnoski.ws.library.jibx.beans.Book</code>, in this case) provide
+public default (no-argument) constructors.</p>
+
+<p>JiBX handling allows the child elements of both inputs and outputs to be
+optional (with <i>nillable='true'</i>, <i>minOccurs='0'</i>, or both), providing
+the binding converts these child elements to object types rather than primitive
+types. It also allows repeated child elements (with
+<i>minOccurs='unbounded'</i>, or any value of <i>minOccurs</i> greater than
+one), representing the repeated elements as arrays of the corresponding object
+or primitive types.</p>
+
+</body>
+</html>
Modified: webservices/axis2/branches/java/1_1/xdocs/jibx/jibx-codegen-integration.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/jibx/jibx-codegen-integration.html?view=diff&rev=454672&r1=454671&r2=454672
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/jibx/jibx-codegen-integration.html (original)
+++ webservices/axis2/branches/java/1_1/xdocs/jibx/jibx-codegen-integration.html Tue Oct 10 02:41:05 2006
@@ -1,34 +1,42 @@
<html>
<head>
<meta http-equiv="content-type" content="">
- <title></title>
+ <title>JiBX Integration with Axis2</title>
</head>
<body>
<h1>JiBX Integration With Axis2</h1>
-<p>This document will explain the usage of JiBX with Axis2 in order to expose
-existing Java code as a Web service and to implement a client for an existing
-Web service (or the service stubs for implementing the service).</p>
+<p>This document describes using JiBX data binding with Axis2. JiBX differs from
+the other data binding techniques supported by Axis2 in that it allows you to
+use your own Java data objects (as opposed to Java data objects generated from a
+schema definition). JiBX also provides a nicer form of unwrapped Web services
+interface than is supported by the other data binding techniques. On the
+downside, JiBX requires more setup than the other data binding techniques - in
+particular, you need to come up with a set of data classes and a binding
+definition in order to work with JiBX in Axis2.</p>
<h2>Content</h2>
<ul>
<li><a href="#intro">Introduction</a></li>
+ <li><a href="#wrapped">Wrapped vs. unwrapped</a></li>
<li><a href="#java">Starting from Java</a></li>
<li><a href="#wsdl">Starting from WSDL</a></li>
<li><a href="#codegen">Axis2 JiBX Code Generation</a></li>
<li><a href="#coming">Coming Attractions</a></li>
</ul>
-<a name="intro"></a>
-<h2>Introduction</h2>
+<a name="intro"></a><h2>Introduction</h2>
<p><a href="http://www.jibx.org">JiBX data binding</a> supports fast and
flexible conversions between plain old Java objects (POJOs) and XML. JiBX
-uses a mapped binding approach that's based on a binding definition document
-you provide. This lets you customize the way your Java objects are converted
-to and from XML. These features make JiBX especially useful if you're
-developing a Web service based on existing Java code.</p>
+uses a mapped binding approach that's based on binding definition documents
+you provide. This approach lets you customize the way your Java objects are
+converted to and from XML. You can even define multiple bindings to use the same
+Java objects with different XML representations. These features make JiBX
+especially useful if you're developing a Web service based on existing Java
+code, or when you need to support multiple XML representations for a Web service
+(as when you're using versioned schema definitions).</p>
<p>Axis2 supports using JiBX with your Web services, including generating the
necessary linkage code for both client and server sides. However, the Axis2
@@ -48,87 +56,123 @@
users understand the basic approach to working with JiBX in Axis2. You can
find full instructions on the standard JiBX parts of this sequence on the <a
href="http://www.jibx.org">JiBX Web site</a>.</p>
-<a name="java"></a>
-<h2>Starting from Java</h2>
+<a name="intro"></a><h2>Wrapped vs. unwrapped</h2>
+
+<p>Axis2 support for JiBX currently only works with the document-literal
+(doc/lit) form of Web services definitions. Doc/lit Web services generally use
+particular schema elements as input and output from each operation, and the
+Axis2 support for JiBX assumes this structure (which is also the structure
+required for compatibility with the
+<a href="http://www.ws-i.org/Profiles/BasicProfile-1.1.html">WS-I Basic Profile</a>).</p>
+
+<p>A popular subset of doc/lit Web services use a form called "wrapped". Wrapped
+doc/lit Web services define service operations that correspond to method calls,
+using input and output element names based on the method name and embedding the
+actual parameter values for the method call within the input element.</p>
+
+<p>When used with Axis2, JiBX supports both general doc/lit and wrapped service
+definitions. Wrapped service definitions can be "unwrapped" during code
+generation to provide a greatly simplified interface. JiBX unwrapping of service
+definitions is not compatible with the unwrapping support for other data binding
+frameworks used with Axis2, but most users will find the JiBX approach easy and
+convenient. See the <a href="./jibx-unwrapped-example.html">JiBX Unwrapped
+Example</a> and the <a href="./jibx-doclit-example.html">JiBX Document/Literal
+Example</a> pages for a detailed comparison of the two forms of service
+interface.</p>
+
+<a name="java"></a><h2>Starting from Java</h2>
<p>Here's the sequence of steps for using JiBX with Axis2 to expose existing
Java code as a Web service:</p>
<ol>
<li>Create a JiBX binding definition for the data being transferred by the
- Web service</li>
+ Web service (you may be able to use the JiBX binding generator to help with
+ this step).</li>
<li>Create a schema that matches the XML defined by your binding (you may
- be able to use the JiBX schema generator to help with this)</li>
+ be able to use the JiBX schema generator to help with this). If you're using
+ a wrapped form of interface to your service you'll also need to create
+ schema definitions for the wrapper input and output elements used by each
+ operation.</li>
<li>Create a WSDL document for your service, with the schema embedded or
imported.</li>
<li>Generate Axis2 server-side linkage code using WSDL2Java with the WSDL
- and your binding definition</li>
+ and your binding definition.</li>
<li>Run the JiBX binding compiler on your Java classes to add the actual
- binding code</li>
+ binding code.</li>
<li>Include the <i>axis2-jibx.jar</i> in your runtime classpath, along with
- the <i>jibx-runtime.jar</i> (normally done by including these in the
- <i>axis2/WEB-INF/lib</i> directory)</li>
+ the <i>jibx-runtime.jar</i>.</li>
</ol>
-<p><strong>The above is assuming:</strong></p>
-<ol>
- <li>Your code already provides methods to implement the operations you want
- to expose as a Web service</li>
- <li>These methods each take a single parameter object that's unique to the
- method</li>
- <li>Each return a single response object.</li>
-</ol>
+<p>If you use a wrapped interface for your Web service you can expose method
+calls in your existing code directly as operations in the service. In this case
+you normally just use your existing data objects with JiBX data binding, and add
+schema definitions for the wrapper elements. See the
+<a href="./jibx-unwrapped-example.html">JiBX Unwrapped Example</a> page for more
+details on how this works.</p>
+
+<p>If you use a non-wrapped interface for your Web service you need to define
+classes to hold the data input and output from each operation. In this case
+these holder classes need to be included in the JiBX binding definition. See the
+<a href="./jibx-doclit-example.html">JiBX Document/Literal Example</a> page for
+more details on this case.</p>
-<p>If this is <i>not</i> the case, you'll also need to create wrapper classes
-and perhaps wrapper methods for now. See the <a
-href="jibx-example.html">JiBX example</a> for more details on this.</p>
-<a name="wsdl"></a>
-
-<h2>Starting from WSDL</h2>
+<a name="wsdl"></a><h2>Starting from WSDL</h2>
<p>Here's the sequence of steps for using JiBX with Axis2 to implement a
-client for an existing Web service (or the service stubs for implementing the
-service):</p>
+client for an existing Web service (or the actual service, when you've been
+supplied with the WSDL your service is to implement):</p>
<ol>
<li>Create Java classes for the data being transferred by the Web service,
and a JiBX binding definition that maps these classes to the schema
defined by the Web service (you may be able to use the JiBX xsd2jibx tool
- to help with this)</li>
+ to help with this).</li>
<li>Generate Axis2 client linkage code using WSDL2Java with the WSDL and
- your binding definition</li>
+ your binding definition.</li>
<li>Run the JiBX binding compiler on your Java classes to add the actual
- binding code</li>
+ binding code.</li>
<li>Include the <i>axis2-jibx.jar</i> in your runtime classpath, along with
the <i>jibx-runtime.jar</i></li>
</ol>
-<a name="codegen"></a>
-<h2>Axis2 JiBX Code Generation</h2>
+<p>As with the starting from Java case, there are some differences in the
+handling depending on whether your service definition fits the wrapped form. See
+the <a href="./jibx-unwrapped-example.html">JiBX Unwrapped Example</a> and
+<a href="./jibx-doclit-example.html">JiBX Document/Literal Example</a> pages for
+more details.</p>
+
+<a name="codegen"></a><h2>WSDL2Java usage</h2>
<p>To run the WSDL2Java tool for JiBX data binding you need:</p>
<ol>
<li>To specify <i>-d jibx</i> to select JiBX binding.</li>
<li>You also need an additional parameter, <i>-Ebindingfile {file}</i>
- (where <i>{file}</i> is the file path to your JiBX binding
- definition).</li>
- <li>Finally, you need to have the <i>axis2-jibx.jar</i>, the
- <i>jibx-bind-1.1beta2.jar</i>, and the <i>jibx-run-1.1beta2.jar</i> files
+ (where <i>{file}</i> is the file path to your JiBX binding definition).</li>
+ <li>Finally, you need to have the <i>axis2-jibx-XXXX.jar</i>, the
+ <i>jibx-bind-XXXX.jar</i>, and the <i>jibx-run-XXXX.jar</i> files
from your Axis2 distribution included in the WSDL2Java classpath.</li>
</ol>
-<a name="coming"></a>
-
-<h2>Coming Attractions</h2>
-<p>Soon after the release of Axis2 1.0 the JiBX support will be extended to
-support automatic handling of "wrapped" doc/lit services. This will
-dramatically reduce the number of classes that need to be defined for working
-with simple services, and simplify both starting from Java and starting from
-WSDL.</p>
-
-<p>The full JiBX 1.1 release will also provide much improved support for code
-generation from schemas, and for binding+schema generation from code, and
-these features will be integrated into the Axis2 JiBX support. Check the <a
-href="http://www.jibx.org">JiBX project site</a> for updates on both JiBX 1.1
+<p>If you want to use the unwrapped form of interface you also need to specify
+the <i>-uw</i> option to WSDL2Java. In this case your JiBX binding definition
+must include abstact mappings for all the complex objects which correspond to
+method parameters, and each abstract mapping must specify a <i>type-name</i>
+attribute that matches the schema <i>complexType</i> used in the WSDL. You can
+also use formats in the binding definition to define the handling of schema
+<i>simpleType</i>s. Schema types corresponding to Java primitives and simple
+objects with build-in JiBX conversions are handled automatically.</p>
+
+<p>If you're not unwrapping the interface, your JiBX binding definition must
+include a concrete mapping for each element used as input or output by any
+operation.</p>
+
+<a name="coming"></a><h2>Coming Attractions</h2>
+
+<p>Work is in-progress on better tools to support generating Java classes and
+corresponding JiBX binding definitions from an input schema, and also for
+generating binding+schema generation from existing code. These features will be
+integrated into the Axis2 JiBX support when they're available. Check the <a
+href="http://www.jibx.org">JiBX project site</a> for updates on both JiBX
and the Axis2 JiBX support.</p>
<h2>References</h2>
Added: webservices/axis2/branches/java/1_1/xdocs/jibx/jibx-doclit-example.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/jibx/jibx-doclit-example.html?view=auto&rev=454672
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/jibx/jibx-doclit-example.html (added)
+++ webservices/axis2/branches/java/1_1/xdocs/jibx/jibx-doclit-example.html Tue Oct 10 02:41:05 2006
@@ -0,0 +1,285 @@
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>JiBX general document/literal</title>
+</head>
+
+<body>
+<h1>JiBX general document/literal</h1>
+
+<p>Code generation for JiBX data binding converts operations defined by a Web
+service to method calls. With general document/literal (doc/lit) Web services
+the generated methods each take a single parameter object and return a single
+result object. Here's a sample doc/lit WSDL (partial) by way of an example:</p>
+
+<pre>
+<wsdl:definitions targetNamespace="http://ws.sosnoski.com/library/wsdl"
+ xmlns:tns="http://ws.sosnoski.com/library/types"
+ xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
+ xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/">
+
+ <wsdl:types>
+
+ <schema elementFormDefault="qualified"
+ targetNamespace="http://ws.sosnoski.com/library/types"
+ xmlns="http://www.w3.org/2001/XMLSchema">
+
+ <element name="getBook">
+ <complexType>
+ <sequence>
+ <element name="isbn" type="string"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="getBookResponse">
+ <complexType>
+ <sequence>
+ <element name="book" minOccurs="0" type="tns:BookInformation"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="addBook">
+ <complexType>
+ <sequence>
+ <element name="type" type="string"/>
+ <element name="isbn" type="string"/>
+ <element name="author" minOccurs="0" maxOccurs="unbounded" type="string"/>
+ <element name="title" type="string"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="addBookResponse">
+ <complexType>
+ <sequence>
+ <element name="success" type="boolean"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <complexType name="BookInformation">
+ <sequence>
+ <element name="author" minOccurs="0" maxOccurs="unbounded" type="string"/>
+ <element name="title" type="string"/>
+ </sequence>
+ <attribute name="type" use="required" type="string"/>
+ <attribute name="isbn" use="required" type="string"/>
+ </complexType>
+
+ </schema>
+
+ </wsdl:types>
+
+ <wsdl:message name="getBookRequest">
+ <wsdl:part element="wns:getBook" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:message name="getBookResponse">
+ <wsdl:part element="wns:getBookResponse" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:message name="addBookRequest">
+ <wsdl:part element="wns:addBook" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:message name="addBookResponse">
+ <wsdl:part element="wns:addBookResponse" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:portType name="Library">
+
+ <wsdl:operation name="getBook">
+ <wsdl:input message="wns:getBookRequest" name="getBookRequest"/>
+ <wsdl:output message="wns:getBookResponse" name="getBookResponse"/>
+ </wsdl:operation>
+
+ <wsdl:operation name="addBook">
+ <wsdl:input message="wns:addBookRequest" name="addBookRequest"/>
+ <wsdl:output message="wns:addBookResponse" name="addBookResponse"/>
+ </wsdl:operation>
+
+ </wsdl:portType>
+ ...
+</wsdl:definitions>
+</pre>
+
+<p>This WSDL defines a service with just two operations: <b>getBook</b> and
+<b>addBook</b>. The <b>getBook</b> operation takes a <i>getBook</i> element as
+input, and returns a <i>getBookResponse</i> element as output, while
+<b>addBook</b> takes an <i>addBook</i> element as input and returns an
+<i>addBookResponse</i> as output. Here's the body of the client interface
+generated by the standard JiBX code generation:</p>
+
+<pre>
+ public interface LibraryJibxUnwrapped {
+
+
+ /**
+ * Auto generated method signatures
+ * @param addBook
+ */
+ public com.sosnoski.ws.library.jibx.wrappers.AddBookResponse addBook(
+ com.sosnoski.ws.library.jibx.wrappers.AddBookRequest addBook) throws java.rmi.RemoteException
+
+
+ ;
+
+
+ /**
+ * Auto generated method signatures
+ * @param getBook
+ */
+ public com.sosnoski.ws.library.jibx.wrappers.GetBookResponse getBook(
+ com.sosnoski.ws.library.jibx.wrappers.GetBookRequest getBook) throws java.rmi.RemoteException
+
+
+ ;
+
+
+
+ //
+ }
+</pre>
+
+<p>You can see that the JiBX code generation converted the operations into
+simple method call interfaces using objects corresponding to the input and
+output elements of the operation (see
+<a href="./jibx-unwrapped-example.html">JiBX Unwrapped Example</a> for the
+interface generated when unwrapping is instead used). The server-side interface
+is the same.</p>
+
+<p>You need to supply an appropriate JiBX binding definition for use in code
+generation (using the <i>-Ebindingfile {file}</i> parameter for WSDL2Java - see
+<a href="./jibx-codegen-integration.html#codegen">JiBX Codegen Integration -
+WSDL2Java usage</a> for more details). This must define concrete <i>mapping</i>s
+for each element used as the input or output of an operation. The JiBX code
+generation extension matches the element names to the binding in order to
+determine the corresponding class to use in generated code.</p>
+
+<p>For example, here's a binding definition that matches the above WSDL:</p>
+
+<pre>
+<binding add-constructors="true">
+
+ <namespace uri="http://ws.sosnoski.com/library/types" default="elements"/>
+
+ <mapping name="getBook"
+ class="com.sosnoski.ws.library.jibx.wrappers.GetBookRequest">
+ <value name="isbn" field="m_isbn"/>
+ </mapping>
+
+ <mapping name="getBookResponse"
+ class="com.sosnoski.ws.library.jibx.wrappers.GetBookResponse">
+ <structure name="book" field="m_book"/>
+ </mapping>
+
+ <mapping name="addBook"
+ class="com.sosnoski.ws.library.jibx.wrappers.AddBookRequest">
+ <structure field="m_book">
+ <value name="type" field="m_type"/>
+ <value name="isbn" field="m_isbn"/>
+ <collection field="m_authors">
+ <value name="author" type="java.lang.String"/>
+ </collection>
+ <value name="title" field="m_title"/>
+ </structure>
+ </mapping>
+
+ <mapping name="addBookResponse"
+ class="com.sosnoski.ws.library.jibx.wrappers.AddBookResponse"/>
+
+ <mapping abstract="true" class="com.sosnoski.ws.library.jibx.beans.Book">
+ <value name="type" style="attribute" field="m_type"/>
+ <value name="isbn" style="attribute" field="m_isbn"/>
+ <collection field="m_authors">
+ <value name="author" type="java.lang.String"/>
+ </collection>
+ <value name="title" field="m_title"/>
+ </mapping>
+
+</binding>
+</pre>
+
+<p>And here are the actual data object classes:</p>
+
+<pre>
+package com.sosnoski.ws.library.jibx.wrappers;
+
+import com.sosnoski.ws.library.jibx.beans.Book;
+
+public class AddBookRequest
+{
+ private Book m_book;
+
+ public AddBookRequest(Book book) {
+ m_book = book;
+ }
+
+ public Book getBook() {
+ return m_book;
+ }
+}
+
+public class AddBookResponse
+{
+}
+
+public class GetBookRequest
+{
+ private String m_isbn;
+
+ public GetBookRequest(String isbn) {
+ m_isbn = isbn;
+ }
+
+ public String getIsbn() {
+ return m_isbn;
+ }
+}
+
+public class GetBookResponse
+{
+ private Book m_book;
+
+ public GetBookResponse(Book book) {
+ m_book = book;
+ }
+
+ public Book getBook() {
+ return m_book;
+ }
+}
+
+package com.sosnoski.ws.library.jibx.beans;
+
+public class Book
+{
+ private String m_type;
+ private String m_isbn;
+ private String m_title;
+ private String[] m_authors;
+
+ public Book() {}
+
+ public String getType() {
+ return m_type;
+ }
+
+ public String getIsbn() {
+ return m_isbn;
+ }
+
+ public String getTitle() {
+ return m_title;
+ }
+
+ public String[] getAuthors() {
+ return m_authors;
+ }
+}
+</pre>
+
+</body>
+</html>
Added: webservices/axis2/branches/java/1_1/xdocs/jibx/jibx-unwrapped-example.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/jibx/jibx-unwrapped-example.html?view=auto&rev=454672
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/jibx/jibx-unwrapped-example.html (added)
+++ webservices/axis2/branches/java/1_1/xdocs/jibx/jibx-unwrapped-example.html Tue Oct 10 02:41:05 2006
@@ -0,0 +1,264 @@
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>JiBX unwrapped document/literal</title>
+</head>
+
+<body>
+<h1>JiBX unwrapped document/literal</h1>
+
+<p>Code generation for JiBX data binding converts operations defined by a Web
+service to method calls. In the most general case of document/literal (doc/lit)
+Web services the generated methods each take a single parameter object and
+return a single result object. This type of interface can be painful for
+developers because it adds both a layer of indirection and potentially a large
+number of extra classes (one input and one output class for each generated
+method).</p>
+
+<p>Fortunately, there's an alternative way of generating methods that gives a
+much more usable API for many Web services. This alternative is called
+<i>unwrapping</i>, and the service definitions that it applies to are called
+<i>wrapped</i> definitions. The key difference that qualifies a service
+definition as wrapped is the structure of the input and output elements used
+for operations.</p>
+
+<p>Here's a sample wrapped WSDL (partial) by way of an example:</p>
+
+<pre>
+<wsdl:definitions targetNamespace="http://ws.sosnoski.com/library/wsdl"
+ xmlns:tns="http://ws.sosnoski.com/library/types"
+ xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
+ xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/">
+
+ <wsdl:types>
+
+ <schema elementFormDefault="qualified"
+ targetNamespace="http://ws.sosnoski.com/library/types"
+ xmlns="http://www.w3.org/2001/XMLSchema">
+
+ <element name="getBook">
+ <complexType>
+ <sequence>
+ <element name="isbn" type="string"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="getBookResponse">
+ <complexType>
+ <sequence>
+ <element name="book" minOccurs="0" type="tns:BookInformation"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="addBook">
+ <complexType>
+ <sequence>
+ <element name="type" type="string"/>
+ <element name="isbn" type="string"/>
+ <element name="author" minOccurs="0" maxOccurs="unbounded" type="string"/>
+ <element name="title" type="string"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="addBookResponse">
+ <complexType>
+ <sequence>
+ <element name="success" type="boolean"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <complexType name="BookInformation">
+ <sequence>
+ <element name="author" minOccurs="0" maxOccurs="unbounded" type="string"/>
+ <element name="title" type="string"/>
+ </sequence>
+ <attribute name="type" use="required" type="string"/>
+ <attribute name="isbn" use="required" type="string"/>
+ </complexType>
+
+ </schema>
+
+ </wsdl:types>
+
+ <wsdl:message name="getBookRequest">
+ <wsdl:part element="wns:getBook" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:message name="getBookResponse">
+ <wsdl:part element="wns:getBookResponse" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:message name="addBookRequest">
+ <wsdl:part element="wns:addBook" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:message name="addBookResponse">
+ <wsdl:part element="wns:addBookResponse" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:portType name="Library">
+
+ <wsdl:operation name="getBook">
+ <wsdl:input message="wns:getBookRequest" name="getBookRequest"/>
+ <wsdl:output message="wns:getBookResponse" name="getBookResponse"/>
+ </wsdl:operation>
+
+ <wsdl:operation name="addBook">
+ <wsdl:input message="wns:addBookRequest" name="addBookRequest"/>
+ <wsdl:output message="wns:addBookResponse" name="addBookResponse"/>
+ </wsdl:operation>
+
+ </wsdl:portType>
+ ...
+</wsdl:definitions>
+</pre>
+
+<p>This WSDL defines a service with just two operations: <b>getBook</b> and
+<b>addBook</b>. The <b>getBook</b> operation takes a <i>getBook</i> element as
+input, and returns a <i>getBookResponse</i> element as output, while
+<b>addBook</b> takes an <i>addBook</i> element as input and returns an
+<i>addBookResponse</i> as output. Each of these input and output elements in
+turn consists of a sequence of child elements, with some of the child elements
+defined directly using standard schema types and others referencing user-defined
+schema types.</p>
+
+<p>As I said up front, this WSDL qualifies for unwrapped handling using JiBX.
+Here's the body of the client interface generated when using unwrapping (the
+<i>-uw</i> option for WSDL2Java):</p>
+
+<pre>
+ public interface LibraryJibxUnwrapped {
+
+
+ /**
+ * Auto generated method signatures
+ * @param type* @param isbn* @param author* @param title
+ */
+ public boolean addBook(
+ java.lang.String type,java.lang.String isbn,java.lang.String[] author,java.lang.String title) throws java.rmi.RemoteException
+
+
+ ;
+
+
+ /**
+ * Auto generated method signatures
+ * @param isbn
+ */
+ public com.sosnoski.ws.library.jibx.beans.Book getBook(
+ java.lang.String isbn) throws java.rmi.RemoteException
+
+
+ ;
+
+
+
+ //
+ }
+</pre>
+
+<p>You can see that the JiBX code generation converted the operations into
+simple method call interfaces without introducing any extraneous objects (see
+<a href="./jibx-doclit-example.html">JiBX Document/Literal Example</a> for the
+interface generated when unwrapping is not used). The server-side interface is
+the same.</p>
+
+<p>The key points that allow unwrapped handling with JiBX are:</p>
+
+<ol>
+<li>Each operation either accepts no input, or the input consists of a single
+element.</li>
+<li>Each input element is defined as a schema <i>complexType</i> consisting of a
+<i>sequence</i> of any number of child elements.</li>
+<li>Each operation either generates no output, or the output consists of a
+single element.</li>
+<li>Each output element is defined as a schema <i>complexType</i> consisting of a
+<i>sequence</i> that's either empty or contains a single child element.</li>
+<li>The child elements of both inputs and outputs are defined using <i>type</i>
+references, rather than an embedded type definitions.</li>
+</ol>
+
+<p>You also need to supply an appropriate JiBX binding definition (using the
+<i>-Ebindingfile {file}</i> parameter for WSDL2Java - see
+<a href="./jibx-codegen-integration.html#codegen">JiBX Codegen Integration -
+WSDL2Java usage</a> for more details). This must define abstract <i>mapping</i>s
+for the <i>complexType</i>s referenced by child elements of the inputs and
+outputs, with a <i>type-name</i> attribute matching the schema
+<i>complexType</i> name. If the child elements reference schema <i>simpleType</i>
+definitions the binding must also define a <i>format</i>s for each
+<i>simpleType</i>, with a <i>label</i> attribute matching the schema
+<i>simpleType</i> name. The binding definition must also specify the
+<i>force-classes='true'</i> attribute on the <i>binding</i> element.</p>
+
+<p>For example, here's a binding definition that matches the above WSDL:</p>
+
+<pre>
+<binding force-classes="true" xmlns:tns="http://ws.sosnoski.com/library/types">
+
+ <namespace uri="http://ws.sosnoski.com/library/types" default="elements"/>
+
+ <mapping abstract="true" class="com.sosnoski.ws.library.jibx.beans.Book"
+ type-name="tns:BookInformation">
+ <value name="type" style="attribute" field="m_type"/>
+ <value name="isbn" style="attribute" field="m_isbn"/>
+ <collection field="m_authors">
+ <value name="author"/>
+ </collection>
+ <value name="title" field="m_title"/>
+ </mapping>
+
+</binding>
+</pre>
+
+<p>And here's the actual <code>com.sosnoski.ws.library.jibx.beans.Book</code>
+class:</p>
+
+<pre>
+package com.sosnoski.ws.library.jibx.beans;
+
+public class Book
+{
+ private String m_type;
+ private String m_isbn;
+ private String m_title;
+ private String[] m_authors;
+
+ public Book() {}
+
+ public String getType() {
+ return m_type;
+ }
+
+ public String getIsbn() {
+ return m_isbn;
+ }
+
+ public String getTitle() {
+ return m_title;
+ }
+
+ public String[] getAuthors() {
+ return m_authors;
+ }
+}
+</pre>
+
+<p>The JiBX code generation for Axis2 currently requires that classes
+coresponding to unwrapped child elements (such as
+<code>com.sosnoski.ws.library.jibx.beans.Book</code>, in this case) provide
+public default (no-argument) constructors.</p>
+
+<p>JiBX handling allows the child elements of both inputs and outputs to be
+optional (with <i>nillable='true'</i>, <i>minOccurs='0'</i>, or both), providing
+the binding converts these child elements to object types rather than primitive
+types. It also allows repeated child elements (with
+<i>minOccurs='unbounded'</i>, or any value of <i>minOccurs</i> greater than
+one), representing the repeated elements as arrays of the corresponding object
+or primitive types.</p>
+
+</body>
+</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org