This Page is a Work In Progress

Summary (Why use Aegis?)

The purpose of Aegis is to allow you to control how your classes and methods are serialized in the web service environment without requiring intrusive modifications to your source code. If you are willing to modify your source code to include annotations, you should probably use JAXB. JAXB code can move to other web service toolkits. Aegis is a private feature of CXF. Aegis allows you to specify same sorts of things that JAXB allows you to specify. The difference is where and how you specify them. In Aegis, for a class (or interface) named 'SomeObjectOfMine', you place a file names SomeObjectOfMine.aegis.xml (called a mapping file) in the classpath in the same project. Aegis reads the XML file for instructions.

CXF includes a total of three databindings: Aegis, JAXB, and Source. As soon as the present author figures our what Source is for, he will add some commentary comparing it to Aegis.

Basic Process

Think of Aegis as processing your classes and methods in three levels:

• Pure introspection
• JAXB-ish annotations
• Mapping files 

Aegis' pure introspection behavior is much like that of JAXB. Given a class or a method, it will derive a sensible mapping to WSDL and XML Schema. It will map packages to namespaces, classes to types, properties to elements, and methods to operations.

You can modify this behavior by adding some annotations that are modeled on the JAXB annotations, but which are defined in org.apache.cxf.aegis.java5. The present author wonders why these exist as opposed to Aegis simply respecting the corresponding JAXB annotations, but there you have them. The supported annotations are:

• XmlAttribute
• XmlElement
• XmlParamType
• XmlReturnType
• XmlType

If you are willing to use these, perhaps you should be using JAXB altogether. However, they do come in handy if you have some code where you absolutely can't modify the source, some code that you can, and you want to mix it together in a single web service. You can use these as more convenient ways of marking the files you can modify, and mapping files for the items that you can't modify.

Finally, mapping files allow you to apply detailed control for properties, classes, and methods via an XML specification.

There is also a procedure for adding custom mappings beyond the capabilties of these basic methods. There are several 'custom' mapping supplied, for items ranging from Gregorian Calendar dates to MTOM attachments.