6.20.3 Notes on schema generator

The following subsections give cautionary notes on schema generator.

Do not process the Java sources corresponding to the notes described in item no. 1 to item no. 32, 56, 57, 59 in the schema generator. For item no. 33 to item no. 55, and item no. 58, 60, 61 use the schema generator after considering the notes.

Table 6-46 Notes on JAXB (schema generator)

No.Notes
1The scope for specification of JAXB mapping annotation has been restricted in the JAXB specifications. As described in the following example, an error might not occur when the JAXB mapping annotation is specified at a location that is outside the scope of specification described in the JAXB specifications, so take precautions. In such cases, the operations for executing JAXB are not defined.
Example:
  • The JAXB mapping annotation that cannot be specified in a package is specified in the package.
  • @XmlRootElement and @XmlType are specified in a class that is not a top level class.
  • @XmlEnumValue is specified in a field.
  • @XmlRegistry is specified in the enumeration type.
  • JAXB mapping annotation, which cannot be specified simultaneously as per the specifications, are specified simultaneously.
2[Conditions]
When any of the following combinations of JAXB mapping annotations are specified simultaneously:
  • @XmlAttribute and @XmlValue
  • @XmlAttribute and @XmlMimeType
  • @XmlElement and @XmlValue
Operations of Cosminexus XML Processor
An error is output. No schema is generated.
(Example)
For @XmlAttribute and @XmlValue
mypackage.ChildType#name has mutually exclusive annotations @javax.xml.bind.annotation.XmlAttribute and @javax.xml.bind.annotation.XmlValue
For @XmlAttribute and @XmlMimeType
javax.xml.bind.annotation.XmlMimeType annotation cannot be placed here
3[Conditions]
When any one of the following is specified in a transient field
  • @XmlAttribute
  • @XmlElement
  • @XmlElements
  • @XmlElementWrapper
  • @XmlList
  • @XmlMimeType
  • @XmlValue
  • @XmlAnyElement

Operations of Cosminexus XML Processor
Error occurs.
(Example)
Transient field "child" cannot have any JAXB annotations.
4[Conditions]
When any one of the following is specified in a static field:
  • @XmlElement
  • @XmlElements
  • @XmlElementWrapper
  • @XmlList
  • @XmlMimeType
  • @XmlValue
  • @XmlAnyElement
  • @XmlID
  • @XmlIDREF

Operations of Cosminexus XML Processor
No error occurs.
5[Conditions]
When not even a single @XmlElement is specified in @XmlElements.
Operations of Cosminexus XML Processor
An invalid schema is output.
6[Conditions]
When the @XmlJavaTypeAdapters annotation that does not contain even a single @XmlJavaTypeAdapter is specified.
Operations of Cosminexus XML Processor
A schema is output as if @XmlJavaTypeAdapters is not specified.
7[Conditions]
When @XmlSeeAlso with an empty value element array is specified.
Operations of Cosminexus XML Processor
A schema such as when @XmlSeeAlso is not specified is output.
8[Conditions]
When an empty character string is specified in the name element of any of @XmlElementWrapper, @XmlAttribute, @XmlElement, @XmlRootElement, or @XmlElementDecl.
Operations of Cosminexus XML Processor
  • For @XmlElementWrapper or @XmlElement, the element name is generated from the field name and property name, in the same way as when the name element is not specified.
  • For @XmlAttribute, an invalid attribute definition called <xs:attribute name="" .../> is generated.
  • For @XmlRootElement or @XmlElementDecl, an invalid element definition called <xs:element name="" .../> is generated.
9[Conditions]
When all of the following conditions are applicable:
  1. @XmlElement is added to a field or JavaBean property of collection type with parameters. Alternatively, @XmlElements is added to the JavaBean property of array type or list type with parameters.
  2. The type element of @XmlElement indicated in condition 1. is specified explicitly.
Operations of Cosminexus XML Processor
No constraints are applicable to the type element of @XmlElement. The operations for the JAXB execution when such a Java source is used are not regulated. For details about the constraints, see the subsection 8.9.1.2 and Javadoc of JSR 222 The Java Architecture for XML Binding 2.1.
10[Conditions]
When all of the following conditions are applicable:
  1. @XmlElements is specified in the field or JavaBean property of collection type with parameters.
  2. Multiple @XmlElements are specified in the @XmlElements elements of condition 1.
Operations of Cosminexus XML Processor
No error occurs. However, the processing will not be performed properly even when unmarshal is executed using the schema and java source.
[Corrective action]
If you want to specify multiple element definitions in a property or JavaBean field of collection type with parameters, use @XmlElementRefs and @XmlElementRef, and process them as collection type of JAXBElement.
11[Conditions]
When an invalid value is specified for the type of a field or JavaBean property in which @XmlElement is specified in the defaultValue element of @XmlElement.
Operations of Cosminexus XML Processor
A schema document is generated for an element definition in which an invalid value is specified for the default attribute, and no error occurs. However, when you perform unmarshal with an Unmarshaller in which the generated schema is set up, an error indicating invalid schema (KECX06161-E) occurs. The generated schema will become invalid.
12[Conditions]
When all of the following conditions are applicable:
  • A true is specified in the nillable element of @XmlElement.
  • A value different from the namespace element of the class that includes a field or JavaBean property is specified in the namespace element of @XmlElement.
Operations of Cosminexus XML Processor
An invalid schema document (see an element with the nillable attribute) is output. When you perform unmarshal with an Unmarshaller in which the schema is set up, an error indicating invalid schema (KECX06231-E) occurs.
13[Conditions]
When all of the following conditions are applicable:
  1. A value other than a null character string is specified in the namespace element of @XmlSchema.
  2. @XmlNs is specified in the xmlns element of @XmlSchema.
  3. The value of a prefix element of @XmlNs specified in condition 2. is different from tns, and the value of a namespace element is different from the value of condition 1.
Operations of Cosminexus XML Processor
The IllegalArgumentException exception occurs.
14[Conditions]
When all of the following conditions are applicable:
  1. @XmlAttribute is added to a field or JavaBean property of primitive type.
  2. Either the required element is not specified in @XmlAttribute indicated in condition 1., or false is specified.
Operations of Cosminexus XML Processor
The value of use attribute of a generated attribute definition is always required.
15[Conditions]
When all of the following conditions are applicable:
  1. A class mapped to the simple type list exists.
  2. @XmlList is specified in a List instance that contains the class specified in condition 1. as the type parameter.
Operations of Cosminexus XML Processor
No error occurs, and a schema in which @XmlList is applied will be generated.
16[Conditions]
When all of the following conditions are applicable:
  1. The @XmlRootElement annotation, and @XmlType annotation in which the name element is an empty character string, are added to the class.
  2. The type of the field or JavaBean property of the class specified in condition 1. is the class itself that is specified in condition 1.
Operations of Cosminexus XML Processor
An error indicating infinite recursion occurs.
(Example)
Error: Anonymous types form an infinite cycle: ClassInfo(mypackage.ItemType) -> ClassInfo(mypackage.ItemType)
[Corrective action]
Set up the name of the field or JavaBean specified in condition 2. to the same name as the element class name (however, name must be the converted name based on the rules for converting an XML name to Java name).
(Example)
@XmlRootElement
@XmlType(name="")
public class ItemType { public ItemType itemType;}
17[Conditions]
When all of the following conditions are applicable:
  1. An abstract modifier is specified in a class mapped in complex type.
  2. @XmlValue is added to the field or JavaBean property of the class specified in condition 1.
  3. @XmlAttribute is added to the field or JavaBean property of the class specified in condition 1.
Operations of Cosminexus XML Processor
The abstract attribute cannot be added to the generated xs:complexType element.
18[Conditions]
When @XmlEnum is specified in the enumeration type and the class that is not mapped in the simple type (example: java.lang.Object) is specified in the value element.
Operations of Cosminexus XML Processor
No error is output. The operations during the execution of JAXB when such a Java source is used are not regulated.
19[Conditions]
When @XmlEnumValue is specified in the enumeration constant, and inappropriate words and phrases are specified for the @XmlEnum.value() type, in the value element.
Operations of Cosminexus XML Processor
No error is output. The operations during the execution of JAXB when such a Java source is used are not regulated.
20[Conditions]
When all of the following conditions are applicable:
  • A value other than \u0000 is specified in the defaultValue element of @XmlElement.
  • A value different from the namespace element of the class included in the field or JavaBean property is specified in the namespace element of @XmlElement.
Operations of Cosminexus XML Processor
An invalid schema document (see an element with the default attribute) is output. When you perform unmarshal with an Unmarshaller in which the schema is set up, an error indicating invalid schema (KECX06231-E) occurs.
21[Conditions]
When @XmlElement or @XmlElements is specified in the field or JavaBean property of java.util.HashMap type.
Operations of Cosminexus XML Processor
An invalid schema document (when the maxOccurs attribute of the element definition becomes 1 instead of unbounded) is output.
[Corrective action]
Action can be taken by adding and specifying @XmlJavaTypeAdapter as shown in the subsection 8.2.5 of JSR 222 The Java Architecture for XML Binding 2.1, when @XmlElement is specified for the property or field of HashMap type.
22[Conditions]
When all of the following conditions are applicable:
  1. The @XmlRootElement annotation, and the @XmlType annotation in which the name element is an empty character string, are added to the class.
  2. A class exists in such a way so that the type of the field or JavaBean property is the class itself that is specified in condition 1.
  3. The element name mapped to the field or JavaBean property specified in condition 2. is different from the element name mapped to condition 1.
(Example)
public class Root {
// If the field name of condition 2. and 3. is childType, an element reference will be generated.
protected ChildType child;
}
// Class specified in condition 1.
@XmlRootElement
@XmlType(name = "")
public class ChildType {
public String fname;
}
Operations of Cosminexus XML Processor
An element definition (name attribute) will be generated.
23[Conditions]
When all of the following conditions are applicable:
  1. The @XmlRootElement annotation, and the @XmlType annotation in which the name element is an empty character string, are added to the class.
  2. A class with the type of the field or JavaBean property, same as in the class specified in condition 1 exists.
  3. An element name mapped to the field or JavaBean property specified in condition 2. is same as the element name mapped to condition 1.
  4. A value other than \u0000 is specified in the defaultValue element of @XmlElement specified in the field or JavaBean property of condition 2.
(Example)
public class Root {
@XmlElement(defaultValue="default") // Condition 4.
protected ChildType childType; // Condition 2., 3.
}
// Class specified in condition 1.
@XmlRootElement
@XmlType(name = "")
public class ChildType {
public String fname;
}
Operations of Cosminexus XML Processor
An element definition (name attribute) containing the default attribute is generated.
24[Conditions]
When a JavaBean property is invalid because either of the setter method or getter method does not exist.

Operations of Cosminexus XML Processor
The schema is generated in such a way so that there is a correct JavaBean with both the setter and the getter method. An error does not occur.
The operations during the execution of JAXB when such a Java source is used are not regulated.
25[Conditions]
When specifications exists in an element of the JAXB mapping annotation, in such a way so that an invalid schema document is generated.
(Example)
@XmlRootElementpublic
class ItemType {
@XmlElement(name="A")
public String item1;
@XmlElement(name="A")
public String item2;
}

The same element name ("A") is specified in different fields of @XmlElement(name="A").
Operations of Cosminexus XML Processor
No error check is performed, and an invalid schema document is generated.
26[Conditions]
When the character string "http://www.w3.org/2001/XMLSchema" that indicates a name space URI specific to the XML Schema specifications is specified in the namespace element of the JAXB mapping annotation.
Operations of Cosminexus XML Processor
No schema document containing such name space URI in the targetNamespace attribute is generated. There is no purpose or meaning in specifying the name space URI.
27[Conditions]
When @XmlElements and @XmlMixed are specified simultaneously.

[Operation of Cosminexus XML Processor]
The following error is output:
java.lang.IndexOutOfBoundsException: Index: 1, Size: 1
28[Conditions]
When all the following conditions are satisfied:
  • The data type of a file and property that specify @XmlElementRef is JAXBElement.
  • @XmlElementRef.name() and @XmlElementRef.namespace() are same as the following JAXB mapping annotations that are the element factory classes as per the @XmlElementDecl annotation within the class that is annotated with @XmlRegistry:
    - @XmlElementDecl.name()
    - @XmlElementDecl.namespace()
  • Specify ##default in @XmlElementRef.namespace().
Operations of Cosminexus XML Processor
An error occurs, and the schema is not be generated.
29[Conditions]
When specifying the @XmlSchemaType annotation without the type element into a package.

Operations of Cosminexus XML Processor
An error does not occur. In the case of using such Java source, the operations for executing JAXB are not defined.
30[Conditions]
When annotated with multiple @XmlID in a class.

Operations of Cosminexus XML Processor
An error does not occur, and a schema is generated.
31[Conditions]
When any of the following conditions are satisfied:
  • The property with the attached @XmlID annotation is not included in the property of the collection type java.lang.Object type.
  • The property with the attached @XmlID annotation is not included in the java.lang.Object type property.
  • The field with the attached @XmlID annotation is not included in the property of the collection type java.lang.Object type.
  • The field with the attached @XmlID annotation is not included in the java.lang.Object type property.
Operations of Cosminexus XML Processor
An error does not occur, and the schema is generated.
32[Conditions]
When coding the following that is in contradiction to the "There is only one JavaBean property annotated by @XmlAnyElement in a class and its super class" restriction:
  • There are multiple fields and properties where @XmlAnyElement is specified in the class.
  • The field and property where @XmlAnyElement is specified respectively in certain class and its sub-class exists.
Operations of Cosminexus XML Processor
No error is output. The operations during the execution of JAXB when such a Java source is used are not regulated.
33[Conditions]
When @XmlAttachmentRef is added to the field or JavaBean property.
Operations of Cosminexus XML Processor
The value of the minOccurs attribute of the generated element definition will become 0.
34[Conditions]
When the following java types are mapped in the schema document:
char, Boolean, Character, Byte, Short, Integer, Long, Float, Double, byte[]
Operations of Cosminexus XML Processor
Mapping will be performed in the xs:unsignedShort, xs:boolean, xs:unsignedShort, xs:byte, xs:short, xs:int, xs:long, xs:float, xs:double, xs:base64Binary types respectively.
35[Conditions]
When the @XmlJavaTypeAdapter annotation that does not contain the type element in the package statement, is specified.
Operations of Cosminexus XML Processor
No error occurs, and a schema in which the specification of @XmlJavaTypeAdapter is enabled will be generated.
36[Conditions]
When @XmlAttribute is added to the static final field, or public static field.
Operations of Cosminexus XML Processor
The fixed attribute cannot be added to the generated xs:attribute element.
37[Conditions]
When the @XmlElement annotation, in which the value of the required element is false, is specified in the field or JavaBean property of primitive type multi-dimensional array.
Operations of Cosminexus XML Processor
The value of the minOccurs attribute will become 0.
38[Conditions]
When any one of @XmlList, @XmlJavaTypeAdapter, @XmlAttachmentRef, or @XmlMimeType is added to the parameters of the method.
Operations of Cosminexus XML Processor
The specification of these JAXB mapping annotations will be ignored.
39[Conditions]
When the @XmlSchema annotation that does not contain the location element in the package, is specified.
Operations of Cosminexus XML Processor
The default value of the location element is interpreted as ##generate.
40[Conditions]
When the @XmlType annotation is added to the enumeration type.
Operations of Cosminexus XML Processor
The final attribute cannot be added to the generated xs:simpleType.
41[Conditions]
When all of the following conditions are applicable:
  1. The name space URI is specified in the namespace element of @XmlSchema.
  2. @XmlNs is specified in the xmlns element of @XmlSchema, and the name space URI is specified in the namespaceURI element.
  3. The name space URI specified in condition 1. and 2. is the same character string.
Operations of Cosminexus XML Processor
The name space declarations specified in condition 1. and condition 2. are generated separately. There will be no problem even if the generated schema is used.
42The apt tool and javac tool is executed when executing the csmschemagen command and when invoking JAXB API. Therefore, when an error occurs, besides the information indicating the error positions, the stack trace of these tools is output.
(Example)
ItemType.java:8: The symbol cannot be found.
Symbol: Class dummy@XmlEnum(dummy.class)
A problem is detected during the annotation process.
For details, see the following stack trace:
java.lang.RuntimeException: java.lang.reflect.InvocationTargetException
at com.cosminexus.jaxb.tools.jxc.apt.InlineAnnotationReaderImpl.getClassValue(InlineAnnotationReaderImpl.java:150)
at com.cosminexus.jaxb.tools.jxc.apt.InlineAnnotationReaderImpl.getClassValue(InlineAnnotationReaderImpl.java:64)
at com.cosminexus.jaxb.xml.bind.v2.model.impl.EnumLeafInfoImpl.<init>(EnumLeafInfoImpl.java:110)
at com.cosminexus.jaxb.xml.bind.v2.model.impl.ModelBuilder.createEnumLeafInfo(ModelBuilder.java:335)
at com.cosminexus.jaxb.xml.bind.v2.model.impl.ModelBuilder.getClassInfo(ModelBuilder.java:224)
at com.cosminexus.jaxb.xml.bind.v2.model.impl.ModelBuilder.getClassInfo(ModelBuilder.java:209)
at com.cosminexus.jaxb.xml.bind.v2.model.impl.ModelBuilder.getTypeInfo(ModelBuilder.java:315)
at com.cosminexus.jaxb.xml.bind.v2.model.impl.ModelBuilder.getTypeInfo(ModelBuilder.java:330)
at com.cosminexus.jaxb.tools.xjc.api.impl.j2s.JavaCompilerImpl.bind(JavaCompilerImpl.java:90)
at com.cosminexus.jaxb.tools.jxc.apt.SchemaGenerator$1.process(SchemaGenerator.java:115)
at com.sun.mirror.apt.AnnotationProcessors$CompositeAnnotationProcessor.process(AnnotationProcessors.java:60)
at com.sun.tools.apt.comp.Apt.main(Apt.java:454)
(Omitted)
... 27 moreItemType.java:8: The symbol cannot be found.
Symbol: Class dummy
@XmlEnum(dummy.class)
^Error One
43[Conditions]
When a class name or enumeration type name beginning with continuous upper-case characters exists.
Operations of Cosminexus XML Processor
The name obtained by converting the first continuous upper-case characters of the class name or enumeration type name to the lower-case characters is mapped to the XML name.
44[Conditions]
When true is specified in the nillable element of @XmlElementWrapper.
Operations of Cosminexus XML Processor
minOccurs="0" is specified in the element definition of the generated schema.
45[Conditions]
When any of the following conditions is applicable:
  • @XmlElement is added to the field or JavaBean property.
  • @XmlElementWrapper is added to the field or JavaBean property.
  • @XmlRootElement is added to the class or enumeration type.
Operations of Cosminexus XML Processor
The final attribute and block attribute cannot be added to the xs:element element. Also, the finalDefault attribute and block attribute cannot be added to the xs:schema element.
46[Conditions]
When the @XmlValue annotation is added to the field or JavaBean property.
Operations of Cosminexus XML Processor
The final attribute cannot be added to the generated xs:simpleType element or xs:complexType element.
47[Conditions]
When executing the csmschemagen command in a directory whose absolute path includes a hash mark (#).
(Example)
cd C:\jaxb\abc#xyz\test
csmschemagen mypackage\TEST.java
Operations of Cosminexus XML Processor
The value of the schemaLocation attribute of the xs:import element of the generated schema document will become invalid.
[Corrective action]
Execute the csmschemagen command in a directory whose absolute path does not include a hash mark (#).
48[Conditions]
When a directory other than the current directory is specified in the argument of the -d option of the csmschemagen command.
Operations of Cosminexus XML Processor
The path of the current directory will be displayed in the information message output by the command, instead of the path of the output destination of schema document.
(Example)
csmschemagen -d D:\schema mypackage\TEST.java
Note: Writing D:\JAXB\work\schema1.xsd
49[Conditions]
When an output destination directory is not specified in an argument of the -d option in the csmschemagen command.
Example:
csmschemagen -d mypackage\TEST.java

Operations of Cosminexus XML Processor
The schema is not output. Moreover, an error might not be output.
50[Conditions]
In the property and fields, if the values to be mapped with different formats are specified in type of @XmlElement and name of @XmlSchemaType.

Operations of Cosminexus XML Processor
A schema document of the element definition with the data type specified in name of @XmlSchemaType is generated.
51[Conditions]
When all the following conditions are satisfied:
  • In the field or the JavaBean property, @XmlElement of the namespace element that is different from the name space of the class is specified.
  • @XmlID or @XmlIDREF is specified in the field or the JavaBean property.
Operations of Cosminexus XML Processor
The specified @XmlID or @XmlIDREF is not be applied in the generated global element definitions.
52[Conditions]
When other than "" is specified in the substitutionHeadName element of @XmlElementDecl.

Operations of Cosminexus XML Processor
The substitutionGroup attribute of the xs:element element is not output.
53[Conditions]
When a value other than \u0000 is specified in the defaultValue element of @XmlElementDecl.

Operations of Cosminexus XML Processor
The default attribute of the xs:element element is not be output.
54[Conditions]
When all the following conditions are satisfied:
  • Specify @XmlAccessorOrder(XmlAccessOrder.ALPHABETICAL) in a package and a class.
  • In one class, there are multiple fields and properties in which @XmlAttribute annotation are not specified in the alphabetical order.
Operations of Cosminexus XML Processor
A schema, with the attributes sorted in the alphabetical order, is generated.
55[Conditions]
When specifying @XmlAccessorType and @XmlAccessorOrder in an internal class which is not of the top level class.

Operations of Cosminexus XML Processor
An error does not occur, and the annotation of the specification becomes valid.
56Condition
When all the following conditions are satisfied:
  • The following elements include characters that do not exist in the JIS X 0208 (1990) to Unicode Kanji code table:
    @XmlEnumValue element
    defaultValue element of @XmlElement/ @XmlElementDecl
    name element of JAXB mapping annotation
  • The value of the LANG environment variable on the AIX platform is Ja_JP or Ja_JP.IBM-943.

Operations of Cosminexus XML Processor
An unexpected exception, such as the java.lang.StringIndexOutOfBoundsException exception, might occur.
57Condition
When you specify a Java source with an encoding different from the system encoding

Operations of Cosminexus XML Processor
An error occurs and an invalid schema is generated.
58Condition
When all the following conditions are satisfied:
  1. @XmlElementRef is added to multiple field values or JavaBean properties.
  2. The required element is not specified for @XmlElementRef from 1., or true is specified in the required element.

Operations of Cosminexus XML Processor
The value of the minOccurs attribute is 0.
59Condition
When either of the following conditions is satisfied:
  • An encoding different from the system encoding (package-info.java) is specified.
  • The Java source that is specified in the argument and package-info.java that is not specified in the argument exist in the same directory and the encoding differs from the system encoding.

Operations of Cosminexus XML Processor
Errors might be incorrectly output several times and an error might also be output for package-info.java that is not specified in the argument.
60Condition
When all the following conditions are satisfied:
  • An invalid encoding is specified in the -encoding option.
  • Options other than the -encoding option are not specified.

Operations of Cosminexus XML Processor
Error is not output and the schema is not generated.
61Condition
When all the following conditions are satisfied:
  • The -encoding option is not specified.
  • A Java source encoded by other than the default encoding is specified.

Operations of Cosminexus XML Processor
The csmschemagen command might terminate abnormally.

Workaround
Specify the encoding for the Java source in the -encoding option.