<!DOCTYPE html>
<!--
 | Generated by Apache Maven Doxia Site Renderer 1.9.2 at 2021-08-01 
 | Rendered using Apache Maven Fluido Skin 1.6
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="Date-Revision-yyyymmdd" content="20210801" />
    <meta http-equiv="Content-Language" content="en" />
    <title>Apache Axis2 &#x2013; JiBX unwrapped document/literal</title>
    <link rel="stylesheet" href="../../css/apache-maven-fluido-1.6.min.css" />
    <link rel="stylesheet" href="../../css/site.css" />
    <link rel="stylesheet" href="../../css/print.css" media="print" />
      <script type="text/javascript" src="../../js/apache-maven-fluido-1.6.min.js"></script>
<meta name="generator" content="HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" /><meta http-equiv="content-type" content="" />      </head>
    <body class="topBarDisabled">
      <div class="container-fluid">
      <div id="banner">
        <div class="pull-left"><a href="http://www.apache.org/" id="bannerLeft"><img src="http://www.apache.org/images/asf_logo_wide.png"  alt="Apache Axis2"/></a></div>
        <div class="pull-right"><a href="../.././" id="bannerRight"><img src="../../images/axis.jpg" /></a></div>
        <div class="clear"><hr/></div>
      </div>

      <div id="breadcrumbs">
        <ul class="breadcrumb">
        <li id="publishDate">Last Published: 2021-08-01<span class="divider">|</span>
</li>
          <li id="projectVersion">Version: 1.8.0<span class="divider">|</span></li>
        <li class=""><a href="http://www.apache.org" class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li>
      <li class=""><a href="../../index.html" title="Axis2/Java">Axis2/Java</a><span class="divider">/</span></li>
    <li class="active ">JiBX unwrapped document/literal</li>
        </ul>
      </div>
      <div class="row-fluid">
        <div id="leftColumn" class="span2">
          <div class="well sidebar-nav">
<ul class="nav nav-list">
          <li class="nav-header">Axis2/Java</li>
    <li><a href="../../index.html" title="Home"><span class="none"></span>Home</a>  </li>
    <li><a href="../../download.html" title="Downloads"><span class="none"></span>Downloads</a>  </li>
    <li><a href="javascript:void(0)" title="Release Notes"><span class="icon-chevron-down"></span>Release Notes</a>
      <ul class="nav nav-list">
    <li><a href="../../release-notes/1.6.1.html" title="1.6.1"><span class="none"></span>1.6.1</a>  </li>
    <li><a href="../../release-notes/1.6.2.html" title="1.6.2"><span class="none"></span>1.6.2</a>  </li>
    <li><a href="../../release-notes/1.6.3.html" title="1.6.3"><span class="none"></span>1.6.3</a>  </li>
    <li><a href="../../release-notes/1.6.4.html" title="1.6.4"><span class="none"></span>1.6.4</a>  </li>
    <li><a href="../../release-notes/1.7.0.html" title="1.7.0"><span class="none"></span>1.7.0</a>  </li>
    <li><a href="../../release-notes/1.8.0.html" title="1.8.0"><span class="none"></span>1.8.0</a>  </li>
      </ul>
  </li>
    <li><a href="../../modules/index.html" title="Modules"><span class="none"></span>Modules</a>  </li>
    <li><a href="../../tools/index.html" title="Tools"><span class="none"></span>Tools</a>  </li>
          <li class="nav-header">Documentation</li>
    <li><a href="../../docs/toc.html" title="Table of Contents"><span class="none"></span>Table of Contents</a>  </li>
    <li><a href="../../docs/installationguide.html" title="Installation Guide"><span class="none"></span>Installation Guide</a>  </li>
    <li><a href="../../docs/quickstartguide.html" title="QuickStart Guide"><span class="none"></span>QuickStart Guide</a>  </li>
    <li><a href="../../docs/userguide.html" title="User Guide"><span class="none"></span>User Guide</a>  </li>
    <li><a href="../../docs/jaxws-guide.html" title="JAXWS Guide"><span class="none"></span>JAXWS Guide</a>  </li>
    <li><a href="../../docs/pojoguide.html" title="POJO Guide"><span class="none"></span>POJO Guide</a>  </li>
    <li><a href="../../docs/spring.html" title="Spring Guide"><span class="none"></span>Spring Guide</a>  </li>
    <li><a href="../../docs/webadminguide.html" title="Web Administrator's Guide"><span class="none"></span>Web Administrator's Guide</a>  </li>
    <li><a href="../../docs/migration.html" title="Migration Guide (from Axis1)"><span class="none"></span>Migration Guide (from Axis1)</a>  </li>
          <li class="nav-header">Resources</li>
    <li><a href="../../faq.html" title="FAQ"><span class="none"></span>FAQ</a>  </li>
    <li><a href="../../articles.html" title="Articles"><span class="none"></span>Articles</a>  </li>
    <li><a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink" title="Wiki"><span class="none"></span>Wiki</a>  </li>
    <li><a href="../../refLib.html" title="Reference Library"><span class="none"></span>Reference Library</a>  </li>
    <li><a href="../../apidocs/index.html" title="Online Java Docs"><span class="none"></span>Online Java Docs</a>  </li>
          <li class="nav-header">Get Involved</li>
    <li><a href="../../overview.html" title="Overview"><span class="none"></span>Overview</a>  </li>
    <li><a href="../../svn.html" title="Checkout the Source"><span class="none"></span>Checkout the Source</a>  </li>
    <li><a href="../../mail-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a>  </li>
    <li><a href="../../release-process.html" title="Release Process"><span class="none"></span>Release Process</a>  </li>
    <li><a href="../../guidelines.html" title="Developer Guidelines"><span class="none"></span>Developer Guidelines</a>  </li>
    <li><a href="../../siteHowTo.html" title="Build the Site"><span class="none"></span>Build the Site</a>  </li>
          <li class="nav-header">Project Information</li>
    <li><a href="../../team-list.html" title="Project Team"><span class="none"></span>Project Team</a>  </li>
    <li><a href="../../issue-tracking.html" title="Issue Tracking"><span class="none"></span>Issue Tracking</a>  </li>
    <li><a href="http://svn.apache.org/viewvc/axis/axis2/java/core/trunk/" class="externalLink" title="Source Code"><span class="none"></span>Source Code</a>  </li>
    <li><a href="../../thanks.html" title="Acknowledgements"><span class="none"></span>Acknowledgements</a>  </li>
          <li class="nav-header">Apache</li>
    <li><a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="License"><span class="none"></span>License</a>  </li>
    <li><a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship"><span class="none"></span>Sponsorship</a>  </li>
    <li><a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks"><span class="none"></span>Thanks</a>  </li>
    <li><a href="http://www.apache.org/security/" class="externalLink" title="Security"><span class="none"></span>Security</a>  </li>
  </ul>
          <hr />
          <div id="poweredBy">
              <div class="clear"></div>
              <div class="clear"></div>
              <div class="clear"></div>
              <div class="clear"></div>
  <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../../images/logos/maven-feather.png" /></a>
              </div>
          </div>
        </div>
        <div id="bodyColumn"  class="span10" >
<html xmlns="http://www.w3.org/1999/xhtml">


<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>

<div>
<pre>
&lt;wsdl:definitions targetNamespace=&quot;http://ws.sosnoski.com/library/wsdl&quot;
    xmlns:tns=&quot;http://ws.sosnoski.com/library/types&quot;
    xmlns:wsdl=&quot;http://schemas.xmlsoap.org/wsdl/&quot;
    xmlns:wsdlsoap=&quot;http://schemas.xmlsoap.org/wsdl/soap/&quot;&gt;
    
  &lt;wsdl:types&gt;
  
    &lt;schema elementFormDefault=&quot;qualified&quot;
        targetNamespace=&quot;http://ws.sosnoski.com/library/types&quot;
        xmlns=&quot;http://www.w3.org/2001/XMLSchema&quot;&gt;
        
      &lt;element name=&quot;getBook&quot;&gt;
        &lt;complexType&gt;
          &lt;sequence&gt;
            &lt;element name=&quot;isbn&quot; type=&quot;string&quot;/&gt;
          &lt;/sequence&gt;
        &lt;/complexType&gt;
      &lt;/element&gt;
      
      &lt;element name=&quot;getBookResponse&quot;&gt;
        &lt;complexType&gt;
          &lt;sequence&gt;
            &lt;element name=&quot;book&quot; minOccurs=&quot;0&quot; type=&quot;tns:BookInformation&quot;/&gt;
          &lt;/sequence&gt;
        &lt;/complexType&gt;
      &lt;/element&gt;
      
      &lt;element name=&quot;addBook&quot;&gt;
        &lt;complexType&gt;
          &lt;sequence&gt;
            &lt;element name=&quot;type&quot; type=&quot;string&quot;/&gt;
            &lt;element name=&quot;isbn&quot; type=&quot;string&quot;/&gt;
            &lt;element name=&quot;author&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;unbounded&quot; type=&quot;string&quot;/&gt;
            &lt;element name=&quot;title&quot; type=&quot;string&quot;/&gt;
          &lt;/sequence&gt;
        &lt;/complexType&gt;
      &lt;/element&gt;
      
      &lt;element name=&quot;addBookResponse&quot;&gt;
        &lt;complexType&gt;
          &lt;sequence&gt;
            &lt;element name=&quot;success&quot; type=&quot;boolean&quot;/&gt;
          &lt;/sequence&gt;
        &lt;/complexType&gt;
      &lt;/element&gt;
      
      &lt;complexType name=&quot;BookInformation&quot;&gt;
        &lt;sequence&gt;
          &lt;element name=&quot;author&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;unbounded&quot; type=&quot;string&quot;/&gt;
          &lt;element name=&quot;title&quot; type=&quot;string&quot;/&gt;
        &lt;/sequence&gt;
        &lt;attribute name=&quot;type&quot; use=&quot;required&quot; type=&quot;string&quot;/&gt;
        &lt;attribute name=&quot;isbn&quot; use=&quot;required&quot; type=&quot;string&quot;/&gt;
      &lt;/complexType&gt;
      
    &lt;/schema&gt;

  &lt;/wsdl:types&gt;

  &lt;wsdl:message name=&quot;getBookRequest&quot;&gt;
    &lt;wsdl:part element=&quot;wns:getBook&quot; name=&quot;parameters&quot;/&gt;
  &lt;/wsdl:message&gt;

  &lt;wsdl:message name=&quot;getBookResponse&quot;&gt;
    &lt;wsdl:part element=&quot;wns:getBookResponse&quot; name=&quot;parameters&quot;/&gt;
  &lt;/wsdl:message&gt;

  &lt;wsdl:message name=&quot;addBookRequest&quot;&gt;
    &lt;wsdl:part element=&quot;wns:addBook&quot; name=&quot;parameters&quot;/&gt;
  &lt;/wsdl:message&gt;
  
  &lt;wsdl:message name=&quot;addBookResponse&quot;&gt;
    &lt;wsdl:part element=&quot;wns:addBookResponse&quot; name=&quot;parameters&quot;/&gt;
  &lt;/wsdl:message&gt;

  &lt;wsdl:portType name=&quot;Library&quot;&gt;

    &lt;wsdl:operation name=&quot;getBook&quot;&gt;
      &lt;wsdl:input message=&quot;wns:getBookRequest&quot; name=&quot;getBookRequest&quot;/&gt;
      &lt;wsdl:output message=&quot;wns:getBookResponse&quot; name=&quot;getBookResponse&quot;/&gt;
    &lt;/wsdl:operation&gt;

    &lt;wsdl:operation name=&quot;addBook&quot;&gt;
      &lt;wsdl:input message=&quot;wns:addBookRequest&quot; name=&quot;addBookRequest&quot;/&gt;
      &lt;wsdl:output message=&quot;wns:addBookResponse&quot; name=&quot;addBookResponse&quot;/&gt;
    &lt;/wsdl:operation&gt;

  &lt;/wsdl:portType&gt;
  ...
&lt;/wsdl:definitions&gt;
</pre></div>

<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>

<div>
<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></div>

<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 style="list-style-type: decimal">

<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>

<div>
<pre>
&lt;binding force-classes=&quot;true&quot; xmlns:tns=&quot;http://ws.sosnoski.com/library/types&quot;&gt;

  &lt;namespace uri=&quot;http://ws.sosnoski.com/library/types&quot; default=&quot;elements&quot;/&gt;
  
  &lt;mapping abstract=&quot;true&quot; class=&quot;com.sosnoski.ws.library.jibx.beans.Book&quot;
      type-name=&quot;tns:BookInformation&quot;&gt;
    &lt;value name=&quot;type&quot; style=&quot;attribute&quot; field=&quot;m_type&quot;/&gt;
    &lt;value name=&quot;isbn&quot; style=&quot;attribute&quot; field=&quot;m_isbn&quot;/&gt;
    &lt;collection field=&quot;m_authors&quot;&gt;
      &lt;value name=&quot;author&quot;/&gt;
    &lt;/collection&gt;
    &lt;value name=&quot;title&quot; field=&quot;m_title&quot;/&gt;
  &lt;/mapping&gt;
  
&lt;/binding&gt;
</pre></div>

<p>And here's the actual
<code>com.sosnoski.ws.library.jibx.beans.Book</code> class:</p>

<div>
<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></div>

<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>

</html>
        </div>
      </div>
    </div>
    <hr/>
    <footer>
      <div class="container-fluid">
        <div class="row-fluid">
            <p>Copyright &copy;2004&#x2013;2021
<a href="https://www.apache.org/">The Apache Software Foundation</a>.
All rights reserved.</p>
        </div>
        </div>
    </footer>
    </body>
</html>