SCHEMAGEN - JAVADOC - ENUM

[ghost]

In the version of the maven plugin 2.2 of jaxb2-maven-plugin with the goal "schemagen" and "createJavaDocAnnotations" attribute set to true, the XSD schema generated doesn't have the xs:documentation tag for Java Enums that have been documented with javadoc at class level.

[lennartj]

This requires some investigation, but we will include it in the next release.

[lennartj]

The reason Java Enums are not currently processed is that the SchemaGenerator renders them as XSD SimpleTypes instead of ComplexTypes. An example below

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" targetNamespace="http://gnat.west.se/foods" xmlns:tns="http://gnat.west.se/foods" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="foodPreferences" type="tns:foodPreferences"/>

  <xs:complexType name="foodPreferences">
    <xs:sequence>
      <xs:element name="preferences" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="preference" type="tns:foodPreference" minOccurs="0" maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>

  <xs:simpleType name="foodPreference">
    <xs:restriction base="xs:string">
      <xs:enumeration value="NONE"/>
      <xs:enumeration value="VEGAN"/>
      <xs:enumeration value="LACTO_VEGETARIAN"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

The topmost type derives from a Java Class, whereas the bottommost type is generated from a Java Enum. Hence, a new XsdNodeProcessor which operates on SimpleTypes and "enumeration" elements is required. This is, however, not a daunting task.

[lennartj]

Two other aspects of Java Enums must be taken into consideration here:

1. Java enums can use either String (value) or Integer (ordinal) representation.
2. Each enum value can be changed/converted by using the @XmlEnumValue annotation:

@XmlEnum(String.class)
public enum DocumentOperation {
    @XmlEnumValue("create") CREATE,
    @XmlEnumValue("modify") MODIFY,
    @XmlEnumValue("delete") DELETE
};

The new XsdEnumerationAnnotationProcessor must cater for (at least) these 3 use cases.