What is Aegis?

Aegis is a databinding. That is, it is a subsystem that can map Java objects to XML documents described by XML schema, and vica-versa. Aegis is designed to give useful mappings with a minimum of programmer effort, while allowing detailed control and customization.

...

Aegis has some advantages over JAXB for some applications. Some users find that it produces a more natural XML mapping for less configuration. For example, Aegis has a default setting for 'nillable', allowing you to declare it for your entire service in one place instead of having to annotate every single element. The biggest advantage of Aegis, however, is a convenient way to customize the mapping without adding (@)annotations to your Java code. This allows you to avoid class loading dependencies between your data classes and your web service binding.

Getting Started: Basic Use of Aegis

You can configure any web service to use the Aegis data binding. A service configured with Aegis will yield a valid WSDL description, and you can use that to configure any client that you like. You can talk to an Aegis service with JAXB, or .NET, or a scripted language, or ... Aegis itself.

...

AegisDatabinding is the class that integrates Aegis into CXF as a databinding.

Aegis Operations - The Simple Case

How does Aegis work? Aegis maintains, for each service, a set of mappings from Java types (Class<?> objects) to XML Schema types. It uses that mapping to read and write XML. Let's look at a simple service, where all the Java types involved are either Java built-in types, other types with predefined mappings to XML Schema, or simple bean-pattern classes that have properties that (recursively) are simple.

...

Will it be in the mapping? Yes, because Aegis precreates mappings for the types in the service's parts. Aegis cannot dynamically create or choose a Java class based on XML schema, so the type creators cannot start from XML.

Using Java Classes That Aren't Visible to the Service Interface

Many web service programmers want to use types that are not directly visible by reflection of the service interface. Here are some popular examples of types that programmers want to use for property or parameter types:

...

• beanImplementationMap is a mapping from Class<?> to class names. Use this to specify proxy classes for interfaces (or abstract classes).

Global Type Creation Options

There are a few global options to the default type mapping process. You can control these by creating a org.apache.cxf.aegis.type.TypeCreationOptions and passing it into your AegisContext object.

...

TypeCreationOptions tOpts = new TypeCreationOptions();
tOpts.setDefaultMinOccurs(1);
tOpts.setDefaultNillable(false);
AegisDatabinding aDB = new AegisDatabinding();
aDB.getAegisContext().setTypeCreationOptions(tOpts);
sFactory.getServiceFactory().setDataBinding(aDB);

Detailed Control of Bean Type Mapping

This page has descended, gradually, from depending on Aegis' defaults toward exercising more detailed control over the process. The next level of detail is to customize the default type creators' behavior via XML mapping files and annotations.

XML Mapping Files

XML mapping files are a major distinguishing feature of Aegis. They allow you to specify details of the mapping process without either (a) modifying your Java source for your types or (b) maintaining a central file of some kind containing mapping instructions.

...

This is a copy of the XML Schema for mapping XML files that is annotated with comments.

Bean mapping

Here is a very simple mapping. It takes a property named 'horse', renames it to 'feathers', and makes it an attribute instead of an element.

<mappings>
  <mapping name="">
    <property name="horse" mappedName="Feathers" style="attribute"/>
  </mapping>
</mappings>

Names and Namespaces

You can also specify the full QName of the bean itself. The following mapping causes a class to have the QName {urn:north-pole:operations}Employee.

...

<np:Employee xmlns:np="urn:north-pole:operations">
  <np:Name>Santa Claus</np:Name>
  <np:Title>Chief Present Officer (CPO)</np:Title>
</np:Employee>

Ignoring properties

If you don't want to serialize a certain property it is easy to ignore it:

<mappings>
  <mapping>
    <property name="propertyName" ignore="true"/>
  </mapping>
</mappings>

MinOccurs and Nillable

The default Aegis mapping is to assume that, since any Java object can be null, that the corresponding schema elements should have minOccurs of 0 and nillable of true. There are properties on the mappings for to control this.

<mappings>
  <mapping>
    <property name='everpresentProperty' minOccurs='1' nillable='false'/>
 </mapping>
<mappings>

Alternative Type Binding

Later on, we will explain how to replace the default mappings that Aegis provides for basic types. However, tehre are some cases where you may want to simply specify one of the provided type mappings for one of your properties. You can do that from the XML mapping file without creating any Java customization.

...

<mappings xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<mapping>
		<property name="birthDate" 
			type="org.apache.cxf.aegis.type.basic.DateType" 
			typeName="xsd:date"
			/>
	</mapping>
</mappings>

Collections

If you use a 'raw' collection type, Aegis will map it as a collection of xsd:any particles. If you want the WSDL to show it as a collection of some specific type, the easiest thing to do is to use Java generics instead of raw types. If, for some reason, you can't do that, you can use the componentType and keyType attributes of a property to specify the Java classes.

Multiple mappings for Different Services

What if you want to specify different mapping behavior for different services on the same types? The 'mapping' element of the file accepts a 'uri' attribute. Each AegisContext has a 'mappingNamespaceURI' attribute. If a mapping in a .aegis.xml file has a uri attribute, it must match the current service's uri.

Services and Parameters

For a service, mapping files specify attributes of operations and parameters.

...

<mappings>
	<mapping>
		<method name="getUnannotatedStrings">
			<return-type name="UnannotatedStringCollection" componentType="java.lang.String"/>
		</method>
        <method name="getValues">
         <parameter index="0" componentType="java.lang.String"/>
        </method>
	</mapping>
</mappings>

Annotations

Like JAXB, Aegis supports some Java annotations to control the mapping process. These attributes are modelled after JAXB. Aegis defines them in the package org.apache.cxf.aegis.type.java5. They are:

...

Note, however, that Aegis goes not handle package-info.java classes, and so XmlSchema must be applied to a class.

Creating Your Own Type Mappings

If you want complete control on the mapping between Java and XML, you must create your own type mappings. To do this, you should make a class that extends org.apache.cxf.aegis.type.Type, and then you must register it in a type mapping for your service.

...

If you want complete control over the process, you can create your own TypeMapping. The class DefaultTypeMapping is the standard type map. You can use these, or you can create your own implementation of TypeMapping. Set up your type mapping as you like, and install it in your context before the service is initialized.

Customizing Type Creation

What if you want to change how Aegis builds new type mappings and types from Java classes? You can create your own TypeCreator, and either put it in the front of the list of type creators or replace the entire standard list.

...