xdocs/1_1/jibx/jibx-codegen-integration.html - axis-axis2-java-rampart - Git at Google


 <html>

 <head>
   <meta http-equiv="content-type" content="">
   <title>JiBX Integration with Axis2</title>
   <link href="../../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
 </head>

 <body>

 <h1>JiBX Integration With Axis2</h1>

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

 <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 binding definition documents
 you provide. This approach let's 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
 support for JiBX does not currently include code generation from the schema
 for a Web service - you need to provide your own data classes and JiBX
 binding definition, and you also need to make sure that the binding
 definition matches the XML structures defined for your Web service. The JiBX
 project provides some basic tools to help with code generation from schema,
 binding generation from Java classes, and schema generation from the
 combination of Java classes and a binding definition. In the future, improved
 versions of these tools will be integrated directly into the Axis2 framework
 support, but for now you're on your own with this part of the setup.</p>

 <p>You can use JiBX data binding both to expose existing Java code as a
 service, and to build a client for an existing service. This document runs
 through the sequence of steps involved for each of these cases, just to help
 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="wrapped"></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 (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). 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>
   <li>Run the JiBX binding compiler on your Java classes to add the actual
     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>

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

 <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 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>
   <li>Generate Axis2 client linkage code using WSDL2Java with the WSDL and
     your binding definition.</li>
   <li>Run the JiBX binding compiler on your Java classes to add the actual
     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>

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

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

 <p><a href="http://jibx.sourceforge.net/tutorial/binding-tutorial.html">JiBX:
 Bindings Tutorial</a>
 </p>

 </body>

 </html>

	<html>

	<head>
	<meta http-equiv="content-type" content="">
	<title>JiBX Integration with Axis2</title>
	<link href="../../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
	</head>

	<body>

	<h1>JiBX Integration With Axis2</h1>

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

	<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 binding definition documents
	you provide. This approach let's 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
	support for JiBX does not currently include code generation from the schema
	for a Web service - you need to provide your own data classes and JiBX
	binding definition, and you also need to make sure that the binding
	definition matches the XML structures defined for your Web service. The JiBX
	project provides some basic tools to help with code generation from schema,
	binding generation from Java classes, and schema generation from the
	combination of Java classes and a binding definition. In the future, improved
	versions of these tools will be integrated directly into the Axis2 framework
	support, but for now you're on your own with this part of the setup.</p>

	<p>You can use JiBX data binding both to expose existing Java code as a
	service, and to build a client for an existing service. This document runs
	through the sequence of steps involved for each of these cases, just to help
	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="wrapped"></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 (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). 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>
	<li>Run the JiBX binding compiler on your Java classes to add the actual
	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>

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

	<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 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>
	<li>Generate Axis2 client linkage code using WSDL2Java with the WSDL and
	your binding definition.</li>
	<li>Run the JiBX binding compiler on your Java classes to add the actual
	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>

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

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

	<p><a href="http://jibx.sourceforge.net/tutorial/binding-tutorial.html">JiBX:
	Bindings Tutorial</a>
	</p>

	</body>

	</html>