Annotations used to configure XMLBeans Start-With-Java compilation

This page describes the set of javadoc-style annotations which are currently supported in XMLBeans java2schema. Note that the names of these attribute are almost certain to change in the near future. Note that 'property' tags can appear on either the getter or the setter.

{{{ Tag Where Type Meaning

• @xsdgen:complexType.typeName Class NCName Name of schema type to generate @xsdgen:complexType.targetNamespace Class URL Target namespace for the generated type @xsdgen:complexType.rootElement Class NCName Specifies that this type binds to a root element with the given name @xsdgen:element.exclude Property void If present, the property is ignored @xsdgen:element.astype Property class Binds the property to an element as if it were actually of the given java type @xsdgen:element.name Property NCName Name of the schema element to generate for this property @xsdgen:element.nillable Property boolean Whether the schema element should be nillable @xsdgen:attribute.name Property NCName Binds the property to an element of the given name }}}

Examples of the above annotations follow below

Class annotations

Class annotations are applied to a class definition.

By default a class is translated into a complexType definition in a schema in a default targetNamespace. [Question: how is the default targetNamespace selected?] For example:

{{{ package com.mycompany.mypackage;

• interface MyTest {

  • ..
  } }}}

This translates to:

{{{ <xs:schema targetNamespace="see question above">

• <xs:complexType name="MyTest">

  • ..

  </xs:complexType>

• </xs:schema> }}}

Specific annotations may modify this.

complexType.typeName

When complexType.typeName is set, the specified localname is used for the complex type instead of the classname.

Example:

{{{ /** @xsdgen:complexType typeName="my-special-name" */

• interface MyTest {

  • ..
  }

  <xs:complexType name="my-special-name">

  • ..

  </xs:complexType> }}}

complexType.targetNamespace

When complexType.targetNamespace is set, the specified namespaceURI is used for the complex type instead of the classname.

Example:

{{{ /** @xsdgen:complexType targetNamespace="http://my.uri/" */

• interface MyTest {

  • ..
  }

  <xs:schema targetNamespace="http://my.uri/" ...>

  • <xs:complexType name="MyTest">

    • ..

    </xs:complexType>

  </xs:schema> }}}

complexType.rootElement

When complexType.rootElement is set, a global element definition with the specified local name is added to the schema (and given the type corresponding to the corresponding schema type).

Example:

{{{ /** @xsdgen:complexType rootElement="my-element" */

• interface MyTest {

  • ..
  }

  <xs:element name="my-element" type="tns:MyTest"> <xs:complexType name="MyTest">

  • ..

  </xs:complexType> }}}

Property annotations

Property annotations are applied to the either the "getter" or "setter" methods of a property getter/setter pair.

By default, properties are bound to a sequence of elements whose schema types are given based on the binding of the type of the Java property. For example:

{{{ interface MyTest

• {
  • String getTicker(); void setTicker(String ticker); int getQuantity() void setQuantity(int quantity);
  } }}}

This translates to:

{{{ <xs:complexType name="MyTest">

• <xs:sequence>

  • <xs:element name="Ticker" type="xs:string"/> <xs:element name="Quantity" type="xs:int"/>

  </xs:sequence>

• </xs:complexType> }}}

Specific annotations may modify this.

element.exclude

 exclude 

When exclude is present, the given property is not included in XML binding.

Example:

{{{ interface MyTest

• {

  • /** @xsdgen:element exclude */ String getTicker(); void setTicker(String ticker); int getQuantity() void setQuantity(int quantity);

  }

  <xs:complexType name="MyTest">

  • <xs:sequence>

    • <xs:element name="Quantity" type="xs:int"/>

    </xs:sequence>

  </xs:complexType> }}}

element.asType

 asType="fully.qualified.javaclass.Name" 

When asType is specified (default is unspecified), the given property is treated as if it had been declared (both in the getter and setter) as the specified class instead of the actual signature. It is an error if the specified class does not inherit from the declared type of the property.

Example:

{{{ interface MyTestContainer

• {

  • /** @xsdgen:element asType="com.mycompany.MyTestImplClass" */ MyTest getMyTest(); void setMyTest(MyTest myTest);

  } }}}

element.nillable

 nillable="true" 

When nillable specified (default is unspecified), the given property is treated as if it had been declared (both in the getter and setter) as the specified class instead of the actual signature. It is an error if the specified class does not inherit from the declared type of the property.

Example:

{{{ interface MyTest

• {

  • /** @xsdgen:attribute name="my-ticker-attribute" */ String getTicker(); void setTicker(String ticker); int getQuantity() void setQuantity(int quantity);

  }

  <xs:complexType name="MyTest">

  • <xs:sequence>

    • <xs:element name="Ticker" type="xs:string" nillable="true"/> <xs:element name="Quantity" type="xs:int"/>

    </xs:sequence>

  </xs:complexType> }}}

attribute.name

 name="my-attribute" 

When the attribute name is specified, the given property is serialized as an attribute rather than an element. It is illegal for attributes to have types that correspond to complex types or flat arrays.

Example:

{{{ interface MyTest

• {

  • /** @xsdgen:attribute name="my-ticker-attribute" */ String getTicker(); void setTicker(String ticker); int getQuantity() void setQuantity(int quantity);

  }

  <xs:complexType name="MyTest">

  • <xs:sequence>

    • <xs:element name="Quantity" type="xs:int"/>

    </xs:sequence> <xs:attribute name="my-ticker-attribute" type="xs:string"/>

  </xs:complexType> }}}

element.name

 name="my-element" 

When element.name is set (default is to use the JAXB name-mangling algorithm based on the Java property name), then the given local-name is used for the QName of the element or attribute.

Example:

{{{ interface MyTest

• {

  • /** @xsdgen:element name="symbol" */ String getTicker(); void setTicker(String ticker); int getQuantity() void setQuantity(int quantity);

  }

  <xs:complexType name="MyTest">

  • <xs:sequence>

    • <xs:element name="symbol" type="xs:string"/> <xs:element name="Quantity" type="xs:int"/>

    </xs:sequence>

  </xs:complexType> }}}

(Note: namespace URI is not provided as an option, because the natural mapping for properties is to local elements and attributes, and it is impossible in schema to have a local element or attribute outside the target or local namespaces.)

Array Style

Not yet supported

 array-style="wrapped" or "inline" 

When array-style is "wrapped" (the default), the array is presented as the contents of a single element, and the Java array is mapped to a schema type (or SOAP array type). When array-style is "inline", the array is presented as a repeated element (minOccurs=0, maxOccurs=unbounded), and no schema type is mapped to the given Java array.

Note that when the entire binding is being done in SOAP style, "wrapped" means to use SOAP array binding.

Example:

{{{ interface MyTest

• {

  • /** @xmlbeans:property array-style="wrapped" */ String[] getTicker(); void setTicker(String[] ticker); int getQuantity() void setQuantity(int quantity);

  }

  <xs:complexType name="MyTest">

  • <xs:sequence>

    • <xs:element name="Ticker" type="tns:ArrayOfString"> <xs:element name="Quantity" type="xs:int"/>

    </xs:sequence>

  </xs:complexType>

  <xs:complexType name="ArrayOfString">

  • <xs:complexContent>

    • <xs:restriction base="soapenc:Array">

      • <xs:sequence>

        • <xs:element name="item" minOccurs="0" maxOccurs="unbounded" type="xs:string" />

        </xs:sequence> <attribute ref="soapenc:arrayType" wsdl:arrayType="xs:string[]"/>

      </xs:restriction>

    </xs:complexContent>

  </xs:complexType> }}}

The example above uses the wsd:arrayType and the soapenc:Array conventions for SOAP array descriptions. The solution for non-soap wrapped arrays is similar, but the type does not inherit from soapenc:Array and there is no arrayType attribute.