For CXF up to 2.0.x
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.
- No annotations are needed to expose classes
- Support for interfaces
- Support for collections including Maps
- Support for a wide variety of datatypes
CXF 2.1 Documentation
There are some significant changes to Aegis in CXF 2.1. See Aegis (2.1).
Details on How It Works
This Page, 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.
Most people who use Aegis use the Simple Front End. 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.
Most people who use Aegis use the 'Simple' front end.
You can also use Aegis with JAX-WS. Here's a Spring configuration example for that.
Here's a Java configuration using the Simple front end.
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
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.
XFire had/has a different convention for generating namespace URI values from Java package names. It added an additional '/' character.
If you need to interoperate with XFire, you need to enable compatibility with this behavior. You enable this compatibility by adding
an additional service configuration class to your service configuration: XFireCompatibilityServiceConfiguration (in 2.0.x, AegisServiceConfiguration).
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 as follows:
This will the change the namespaces that CXF generates by default so that they are the same as XFire would generate.
Class <-> XML Mapping Overview
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"
Fore example, the java class:
In XML this translates to:
In XML Schema this would become a complex type:
Validate your mapping!
You can find an XML Schema for Aegis mapping files here.
This version of the XML schema has comments to explain the bits and pieces.
- Basic types: int, double, float, long, byte, short, String, BigDecimal
- Collections - including Maps
- Dates: java.util.Date, java.util.Calendar, java.sql.Timestamp, java.sql.Date, java.sql.Time
- XML: org.w3c.dom.Docmument, org.jdom.Element, XMLStreamReader, Source
- Complex types which are aggregations of the above
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.)
Setting Default minOccurs and nillable Parameters from Java
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 false, you can change the defaults for Aegis from Java code (amongst other places).
Here is an example: it extracts the binding provider from the service factory, and changes the configuration parameters.
This section is under construction. For more information about how the Aegis databinding works, please check out the Aegis documentation at the XFire site (http://xfire.codehaus.org/User's%2bGuide).