cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache CXF Documentation > Aegis Databinding (2.0.x)
Date Fri, 11 Sep 2009 15:56:00 GMT
<html>
<head>
    <base href="http://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1519/1/1/_/styles/combined.css?spaceKey=CXF20DOC&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background-color: white" bgcolor="white">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
     <h2><a href="http://cwiki.apache.org/confluence/display/CXF20DOC/Aegis+Databinding+%282.0.x%29">Aegis
Databinding (2.0.x)</a></h2>
     <h4>Page <b>edited</b> by             <a href="http://cwiki.apache.org/confluence/display/~christian%2Bschneider">Christian
Schneider</a>
    </h4>
     
          <br/>
     <div class="notificationGreySide">
         <p>For CXF up to 2.0.x</p>
<h1><a name="AegisDatabinding%282.0.x%29-WhyAegis%3F"></a>Why Aegis?</h1>
<p>Aegis is a fast, StAX based, data-binding that makes developing code first services
as simply as possible. It is able to handle most classes and create intelligent schemas for
them. </p>

<p>Features include:</p>
<ul class="alternate" type="square">
	<li>No annotations are needed to expose classes</li>
	<li>Support for interfaces</li>
	<li>Support for collections including Maps</li>
	<li>Support for a wide variety of datatypes</li>
</ul>


<h1><a name="AegisDatabinding%282.0.x%29-CXF2.1Documentation"></a>CXF 2.1
Documentation</h1>

<p>There are some significant changes to Aegis in CXF 2.1. See <a href="/confluence/display/CXF20DOC/Aegis+%282.1%29"
title="Aegis (2.1)">Aegis &#40;2.1&#41;</a>.</p>

<h1><a name="AegisDatabinding%282.0.x%29-DetailsonHowItWorks"></a>Details
on How It Works</h1>

<p><a href="/confluence/display/CXF20DOC/Aegis+Theory+of+Operation" title="Aegis
Theory of Operation">This Page</a>, which is a work in progress, explains some of
the modularity of Aegis. You may find it helpful in understanding Aegis' behavior and in developing
customizations.</p>

<h1><a name="AegisDatabinding%282.0.x%29-UsingAegis"></a>Using Aegis</h1>
<p>Most people who use Aegis use the <a href="/confluence/display/CXF20DOC/Simple+Frontend"
title="Simple Frontend">Simple Front End</a>. If you are using Aegis, you can't move
your code to some other web service framework without modifying all your code to work with
JAXB or some other binding, so there's not much advantage to using the JAX-WS front-end. You
might want to use Aegis with one of the specialized frontends, like JAX-RS. We don't have
examples of that in this documentation.</p>

<h2><a name="AegisDatabinding%282.0.x%29-SpringConfiguration"></a>Spring
Configuration</h2>

<p>Most people who use Aegis use the 'Simple' front end. </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
  <span class="code-tag">&lt;simple:server id=<span class="code-quote">"pojoservice"</span>
serviceClass=<span class="code-quote">"demo.hw.server.HelloWorld"</span> address=<span
class="code-quote">"/hello_world"</span>&gt;</span>
  	<span class="code-tag">&lt;simple:serviceBean&gt;</span>
  		<span class="code-tag">&lt;bean class=<span class="code-quote">"demo.hw.server.HelloWorldImpl"</span>
/&gt;</span>
  	<span class="code-tag">&lt;/simple:serviceBean&gt;</span>
         <span class="code-tag">&lt;simple:dataBinding&gt;</span>
       <span class="code-tag">&lt;bean class=<span class="code-quote">"org.apache.cxf.aegis.databinding.AegisDatabinding"</span>
/&gt;</span>
    <span class="code-tag">&lt;/simple:dataBinding&gt;</span>
&lt;!-- Use this property only for XFire compatibility -- this version for 2.0.x ...
                 <span class="code-tag">&lt;property name=<span class="code-quote">"serviceConfigurations"</span>&gt;</span>
                     <span class="code-tag">&lt;list&gt;</span>
                       <span class="code-tag">&lt;bean class=<span class="code-quote">"org.apache.cxf.jaxws.support.JaxWsServiceConfiguration"</span>/&gt;</span>
                       <span class="code-tag">&lt;bean class=<span class="code-quote">"org.apache.cxf.aegis.databinding.AegisServiceConfiguration"</span>/&gt;</span>
                       <span class="code-tag">&lt;bean class=<span class="code-quote">"org.apache.cxf.service.factory.DefaultServiceConfiguration"</span>/&gt;</span>

                    <span class="code-tag">&lt;/list&gt;</span>
                <span class="code-tag">&lt;/property&gt;</span>
--&gt;
  <span class="code-tag">&lt;/simple:server&gt;</span>
 <span class="code-tag">&lt;/bean&gt;</span>
</pre>
</div></div>

<p>You can also use Aegis with JAX-WS. Here's a Spring configuration example for that.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
 <span class="code-tag">&lt;bean id=<span class="code-quote">"aegisBean"</span>
class=<span class="code-quote">"org.apache.cxf.aegis.databinding.AegisDatabinding"</span>
scope=<span class="code-quote">"prototype"</span>/&gt;</span> 
 &lt;bean id=<span class="code-quote">"jaxws-and-aegis-service-factory"</span>
    class=<span class="code-quote">"org.apache.cxf.jaxws.support.JaxWsServiceFactoryBean"</span>
    scope=<span class="code-quote">"prototype"</span>&gt; 
        <span class="code-tag">&lt;property name=<span class="code-quote">"dataBinding"</span>
ref=<span class="code-quote">"aegisBean"</span>/&gt;</span>
&lt;!-- Use this property only for XFire compatibility -- this version for 2.0.x ...
                 <span class="code-tag">&lt;property name=<span class="code-quote">"serviceConfigurations"</span>&gt;</span>
                     <span class="code-tag">&lt;list&gt;</span>
                       <span class="code-tag">&lt;bean class=<span class="code-quote">"org.apache.cxf.jaxws.support.JaxWsServiceConfiguration"</span>/&gt;</span>
                       <span class="code-tag">&lt;bean class=<span class="code-quote">"org.apache.cxf.aegis.databinding.AegisServiceConfiguration"</span>/&gt;</span>
                       <span class="code-tag">&lt;bean class=<span class="code-quote">"org.apache.cxf.service.factory.DefaultServiceConfiguration"</span>/&gt;</span>

                    <span class="code-tag">&lt;/list&gt;</span>
                <span class="code-tag">&lt;/property&gt;</span>
--&gt;
&lt;!-- Use this property only for XFire compatibility -- this version for 2.1
                 <span class="code-tag">&lt;property name=<span class="code-quote">"serviceConfigurations"</span>&gt;</span>
                     <span class="code-tag">&lt;list&gt;</span>
                       <span class="code-tag">&lt;bean class=<span class="code-quote">"org.apache.cxf.jaxws.support.JaxWsServiceConfiguration"</span>/&gt;</span>
                       <span class="code-tag">&lt;bean class=<span class="code-quote">"org.apache.cxf.aegis.databinding.XFireCompatibilityServiceConfiguration"</span>/&gt;</span>
                       <span class="code-tag">&lt;bean class=<span class="code-quote">"org.apache.cxf.service.factory.DefaultServiceConfiguration"</span>/&gt;</span>

                    <span class="code-tag">&lt;/list&gt;</span>
                <span class="code-tag">&lt;/property&gt;</span>
--&gt;
 <span class="code-tag">&lt;/bean&gt;</span>

 <span class="code-tag">&lt;jaxws:endpoint id=<span class="code-quote">"my_service_endpoint"</span>
implementor=<span class="code-quote">"#my-service"</span> address=<span class="code-quote">"/MyIndex"</span>&gt;</span>
  <span class="code-tag">&lt;jaxws:serviceFactory&gt;</span>
   <span class="code-tag">&lt;ref bean='jaxws-and-aegis-service-factory' /&gt;</span>
  <span class="code-tag">&lt;/jaxws:serviceFactory&gt;</span>
 <span class="code-tag">&lt;/jaxws:endpoint&gt;</span>
 </pre>
</div></div>

<h2><a name="AegisDatabinding%282.0.x%29-Javaconfiguration"></a>Java configuration</h2>

<p>Here's a Java configuration using the Simple front end. </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">import</span> org.apache.cxf.aegis.databinding.AegisDatabinding;
<span class="code-keyword">import</span> org.apache.cxf.frontend.ServerFactoryBean;

ServerFactoryBean sf = <span class="code-keyword">new</span> ServerFactoryBean();
sf.setServiceClass(serviceClass);
sf.setAddress(<span class="code-quote">"http:<span class="code-comment">//myhost/service"</span>);
</span>sf.getServiceFactory().setDataBinding(<span class="code-keyword">new</span>
AegisDatabinding());
sf.create();
</pre>
</div></div>

<p>Similarly, here is a client side using the simple front end. Note the use of the
WSDL. Without the WSDL, the simple front end will try to learn<br/>
parameters names from Java reflection. As always, Java interfaces don't carry parameter names,
and this results in names like 'arg0', 'arg1', etc, which don't match the service.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">import</span> org.apache.cxf.aegis.databinding.AegisDatabinding;
<span class="code-keyword">import</span> org.apache.cxf.frontend.ClientProxyFactoryBean;

ClientProxyFactoryBean factory = <span class="code-keyword">new</span> ClientProxyFactoryBean();
factory.setServiceClass(serviceInterfaceClassObject);
factory.setAddress(<span class="code-quote">"http:<span class="code-comment">//myhost/service"</span>);
</span>factory.setWsdlLocation(<span class="code-quote">"http:<span class="code-comment">//myhost/service?wsdl"</span>);
</span>factory.getServiceFactory().setDataBinding(<span class="code-keyword">new</span>
AegisDatabinding());
MyService client = (MyService) factory.create();
</pre>
</div></div>

<h2><a name="AegisDatabinding%282.0.x%29-XFireCompatibility"></a>XFire Compatibility</h2>

<p>XFire had/has a different convention for generating namespace URI values from Java
package names. It added an additional '/' character.<br/>
If you need to interoperate with XFire, you need to enable compatibility with this behavior.
You enable this compatibility by adding <br/>
an additional service configuration class to your service configuration: XFireCompatibilityServiceConfiguration
(in 2.0.x, AegisServiceConfiguration). <br/>
The spring example above shows the necessary configuration in a comment. For the client side
in Java, you need to add the service configuration to the service factory<br/>
as follows:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">import</span> org.apache.cxf.aegis.databinding.AegisServiceConfiguration;
<span class="code-comment">// <span class="code-keyword">for</span> 2.0.x
</span>sf.getServiceFactory().getServiceConfigurations().add(0, <span class="code-keyword">new</span>
AegisServiceConfiguration());
<span class="code-comment">// <span class="code-keyword">for</span> 2.1
</span>sf.getServiceFactory().getServiceConfigurations().add(0, <span class="code-keyword">new</span>
XFireCompatibilityServiceConfiguration());

</pre>
</div></div>
<p>This will the change the namespaces that CXF generates by default so that they are
the same as XFire would generate.</p>


<h1><a name="AegisDatabinding%282.0.x%29-Class%3C%3EXMLMappingOverview"></a>Class
&lt;-&gt; XML Mapping Overview</h1>

<p>Aegis has a flexible mapping system so you can control how your beans are controlled.
 By default your POJOs are serialized based on their name and namespaces. If you have a class
in the "org.codehaus.xfire" package named "Employee" it would be serialized in namespace "http://xfire.codehaus.org"
with the local name "Employee"</p>

<p>Fore example, the java class:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> class Employee
{
  <span class="code-keyword">private</span> <span class="code-object">String</span>
name;
  <span class="code-keyword">private</span> <span class="code-object">String</span>
title;

  <span class="code-keyword">public</span> <span class="code-object">String</span>
getName() { <span class="code-keyword">return</span> name; }
  <span class="code-keyword">public</span> void setName(<span class="code-object">String</span>
name) { <span class="code-keyword">this</span>.name = name; }

  <span class="code-keyword">public</span> <span class="code-object">String</span>
getTitle() { <span class="code-keyword">return</span> title; }
  <span class="code-keyword">public</span> void setTitle(<span class="code-object">String</span>
title) { <span class="code-keyword">this</span>.title = title; }
}
</pre>
</div></div>
<p>In XML this translates to:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;Employee xmlns=<span class="code-quote">"http://xfire.codehaus.org"</span>&gt;</span>
  <span class="code-tag">&lt;name&gt;</span>Santa Claus<span class="code-tag">&lt;/name&gt;</span>
  <span class="code-tag">&lt;title&gt;</span>Chief Present Officer (CPO)<span
class="code-tag">&lt;/title&gt;</span>
<span class="code-tag">&lt;/Employee&gt;</span>
</pre>
</div></div>
<p>In XML Schema this would become a complex type:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;xsd:complexType name=<span class="code-quote">"Employee"</span>&gt;</span>
  <span class="code-tag">&lt;xsd:sequence&gt;</span>
    <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"name"</span>
type=<span class="code-quote">"xsd:string"</span> minOccurs=<span class="code-quote">"0"</span>
maxOccurs="1/&gt;</span>
    <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"title"</span>
type=<span class="code-quote">"xsd:string"</span> minOccurs=<span class="code-quote">"0"</span>
maxOccurs="1/&gt;</span>
  <span class="code-tag">&lt;/xsd:sequence&gt;</span>
<span class="code-tag">&lt;/xsd:complexType&gt;</span>
</pre>
</div></div>

<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/information.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>Validate
your mapping!</b><br /><p>You can find an XML Schema for Aegis mapping files
<a href="/confluence/download/attachments/49562/aegis.xsd?version=1">here</a>.<br/>
 <a href="/confluence/display/CXF20DOC/Annotated+Aegis+File+Schema" title="Annotated Aegis
File Schema">This</a> version of the XML schema has comments to explain the bits
and pieces.</p></td></tr></table></div>

<h2><a name="AegisDatabinding%282.0.x%29-SupportedTypes"></a>Supported Types</h2>

<ul>
	<li>Basic types: int, double, float, long, byte[], short, String, BigDecimal</li>
	<li>Arrays</li>
	<li>Collections - including Maps</li>
	<li>Dates: java.util.Date, java.util.Calendar, java.sql.Timestamp, java.sql.Date, java.sql.Time</li>
	<li>XML: org.w3c.dom.Docmument, org.jdom.Element, XMLStreamReader, Source</li>
	<li>Complex types which are aggregations of the above</li>
</ul>


<p>If you have constructors defined in your Java beans, make sure a default constructor
(i.e. no arguments) is also declared. (Aegis needs a no-argument contstructor to instantiate
client Java classes.)</p>

<h1><a name="AegisDatabinding%282.0.x%29-SettingDefaultminOccursandnillableParametersfromJava"></a>Setting
Default minOccurs and nillable Parameters from Java</h1>

<p>If you have many properties, and you want most, or all of them, to have a minOccurs
other than 0 or a nillable other than <b>false</b>, you can change the defaults
for Aegis from Java code (amongst other places).<br/>
Here is an example: it extracts the binding provider from the service factory, and changes
the configuration parameters.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
ServerFactoryBean sf = <span class="code-keyword">new</span> ServerFactoryBean();
sf.setServiceClass(serviceClass);
sf.setAddress(<span class="code-quote">"http:<span class="code-comment">//myhost/service"</span>);
</span>AegisDatabinding db = <span class="code-keyword">new</span> AegisDatabinding();
sf.getServiceFactory().setDataBinding(db);

DefaultTypeMappingRegistry tmr = (DefaultTypeMappingRegistry)db.getTypeMappingRegistry();
<span class="code-comment">// here we disuade XFire from its rather annoying tendency
to assume that, just because
</span><span class="code-comment">// anything in Java can be <span class="code-keyword">null</span>,
that we want to advertise all that nullity all over.
</span>Configuration configuration = tmr.getConfiguration();
configuration.setDefaultMinOccurs(1);
configuration.setDefaultNillable(<span class="code-keyword">false</span>);

sf.create();
</pre>
</div></div>

<h1><a name="AegisDatabinding%282.0.x%29-MoreInformation...."></a>More Information....</h1>

<p>This section is under construction. For more information about how the Aegis databinding
works, please check out the <a href="http://xfire.codehaus.org/User&#39;s%2bGuide"
rel="nofollow">Aegis documentation at the XFire site</a>.</p>
     </div>
     <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;">
            <a href="http://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
       </div>

       <a href="http://cwiki.apache.org/confluence/display/CXF20DOC/Aegis+Databinding+%282.0.x%29">View
Online</a>
       |
       <a href="http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=49562&revisedVersion=25&originalVersion=24">View
Change</a>
              |
       <a href="http://cwiki.apache.org/confluence/display/CXF20DOC/Aegis+Databinding+%282.0.x%29?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message