6.20.4 Notes on runtime

1

When performing multi-thread programming, the objects provided in the packages with a name beginning with javax.xml.bind are not thread safe (as an exception, the javax.xml.bind.JAXBContext class is thread safe). Therefore, multiple threads must not access these objects at the same time. To avoid conflicts between threads, use the following method:

• Each thread exclusively accesses these objects.

2

During unmarshal and marshal, processing similar to the schema generator might be executed within the product. Therefore, you must also see the notes on the schema generator.

3

Do not execute unmarshal or marshal in the verification mode for the schema document using xs:ENTITY type or xs:ENTITIES type. If you execute unmarshal or marshal, an error indicating 'Entity is not declared' occurs.

(Example)

KECX06252-E UndeclaredEntity: Entity 'id1' is not declared.

4

[Conditions]

When all of the following conditions are applicable:

• The unmarshal(org.w3c.dom.Node node) method of Unmarshaller is executed.

• A Node object other than org.w3c.dom.Document or org.w3c.dom.Element is specified in the node parameter.

Operations of Cosminexus XML Processor

An exception IllegalArgumentException occurs.

(Example)

java.lang.IllegalArgumentException: Unexpected node type: [#text: String]

5

[Conditions]

When all of the following conditions are applicable:

• An aligned event callback method (beforeUnmarshal/afterUnmarshal) that throws the exception is defined in the class.

• Marshal is executed in such a way so that the instance document invoked by the above event callback method is output.

Operations of Cosminexus XML Processor

The marshal process will terminate, but an exception IllegalStateException will be thrown.

6

[Conditions]

When all of the following conditions are applicable:

1. @XmlJavaTypeAdapter is specified at the package level.

2. @XmlJavaTypeAdapter is specified for the class or enumeration type.

3. The instance document contains a data type definition in which the @XmlJavaTypeAdapter annotation specified in condition 1. and 2. is enabled.

4. Unmarshal or marshal is executed based on the conditions 1. to 3.

Operations of Cosminexus XML Processor

The @XmlJavaTypeAdapter annotation specified in the package level of the class is prioritized than the @XmlJavaTypeAdapter annotation for the class or enumeration type. As the operations differ from the standard specifications, do not perform process for such a java source.

7

[Conditions]

When the Java contents tree is changed within the handleEvent method.

Operations of Cosminexus XML Processor

An exception MarshalException is thrown.

8

[Conditions]

When all of the following conditions are applicable:

1. Marshal is executed.

2. An argument jaxbElement of the marshal method is JAXBElement object.

3. Either localPart or prefix of the QName object specified in the name parameter of the JAXBElement constructor specified in condition 2. is not NCName.

Operations of Cosminexus XML Processor

The marshal method will terminate normally, but an XML document that is not in a proper format is generated.

9

[Conditions]

When all of the following conditions are applicable:

1. The value element of @XmlEnum is javax.xml.namespace.QName.class.

2. The value element of @XmlEnumValue is a literal character string indicating QName.

3. A Java class that includes the condition 1. and 2. is specified and executed in the argument of the JAXBContext.newInstance() method.

Operations of Cosminexus XML Processor

An exception JAXBException occurs. Do not perform processing for such a java source.

10

[Conditions]

When all of the following conditions are applicable:

• The getURL method of the ValidationEventLocator interface is executed.

• The URL of the object for which marshal and unmarshal is to be performed includes characters that cannot be specified in RFC2396 (also includes the cases when the URL is generated automatically from the directory name or file name).

Operations of Cosminexus XML Processor

The return value of the getURL method includes characters that cannot be specified in RFC2396 as it is.

11

[Conditions]

When all of the following conditions are applicable:

1. @XmlAttribute is specified in the static field whose type is primitive type.

2. Marshal is performed for the Java source specified in condition 1.

Operations of Cosminexus XML Processor

An invalid exception occurs in marshal. Such a java source is out of scope for processing.

(Example)

Exception in thread "main" java.lang.IncompatibleClassChangeError

12

[Conditions]

When null is specified in an argument of the setter method of a Java value class.

Operations of Cosminexus XML Processor

The NullPointerException exception occurs.

[Corrective action]

Modify the code of the setter method invocation part as follows:

(Before modification)

items.setId(null);

(After modification)

items.setId(new String[] {});

13

[Conditions]

When all of the following conditions are applicable:

1. The xsi:type attribute is specified in an element of the instance document.

2. The type specified in condition 1. is not the JAXB map type.

3. Unmarshal is executed in condition 1. and 2.

Operations of Cosminexus XML Processor

Unmarshal terminates normally.

The element will be unmarshalled without substitution of the type by xsi:type.

14

When an error occurs due to the execution of marshal in the verification mode, an invalid XML (XML that is not in a proper format) might be output for the contents up to the occurrence of the error.

15

When marshal is executed by specifying the jaxb.formatted.output property, the linefeed code of the output XML document will be 0x0A.

16

When marshal is executed, the standalone="yes" pseudo attribute will be output to the XML declaration of the output XML document.

17

[Conditions]

When a Node object other than Element, Document, or DocumentFragment is specified in the argument node of the marshal(Object jaxbElement, Node node) method of Marshaller interface.

Operations of Cosminexus XML Processor

An exception DOMException will be thrown.

(Example)

org.w3c.dom.DOMException: HIERARCHY_REQUEST_ERR: KECX01304-E An attempt was made to insert a node where it is not permitted.

18

[Conditions]

When all of the following conditions are applicable:

1. An element of xs:list type for which the default value is specified is declared in the schema document.

2. Condition 1. is applied to the schema compiler, and the XML document is unmarshalled using the generated Java value class.

3. The instances of the Java value class specified in condition 2. are acquired by the get method.

Operations of Cosminexus XML Processor

The default values defined in the schema document are not included in the acquired instances.

19

[Conditions]

When all of the following conditions are applicable:

1. @XmlAttachmentRef is added to any one of the field, JavaBean property, or parameter.

2. The Java source specified in condition 1. is input to the schema generator.

3. Validation is performed in the schema document generated in condition 2.

Operations of Cosminexus XML Processor

The value of the type attribute in the element definition or attribute definition of the generated schema will be {http://ws-i.org/profiles/basic/1.1/xsd}swaRef.

The definition of the name space {http://ws-i.org/profiles/basic/1.1/xsd} is generated as xs:import:

<xs:import namespace="http://ws-i.org/profiles/basic/1.1/xsd" schemaLocation="http://ws-i.org/profiles/basic/1.1/swaref.xsd"/>

Therefore, when validation is performed in the generated schema document, the XML parser references http://ws-i.org/profiles/basic/1.1/swaref.xsd using the http protocol. By setting up the correct org.w3c.dom.ls.LSResourceResolver instance using the appropriate javax.xml.validation.Validator#setResourceResolver method, swaref.xsd can be referenced at any place of existence.

20

[Conditions]

When all of the following conditions are applicable:

1. The jaxb:typesafeEnumClass custom binding is specified.

2. The schema document specified in condition 1. is input into the schema compiler.

3. The fromValue method of the enumeration type is generated in condition 2., and is invoked by specifying value other than the enumeration constant in its argument.

Operations of Cosminexus XML Processor

An exception IllegalArgumentException occurs.

21

[Conditions]

When all of the following conditions are applicable:

• package-info.java exists.

• After executing JAXBContext.newInstance(Class... classesToBeBound), the schema is generated, and the methods of unmarshal and marshal are executed.

Operations of Cosminexus XML Processor

The package-info.java will not be processed if not compiled beforehand.

22

[Conditions]

When all the following conditions are satisfied:

• Add @XmlAnyElement(lax = true) to either the Object type field or the JavaBean property.

• An element is not in conformity with the schema element definition, but the type name specified in the xsi:type attribute of that element will unmarshal the instance document that is defined in the schema.

Operations of Cosminexus XML Processor

The DOM node will be generated without generating a JAXB object (Java class object corresponding to the schema element definition).

23

[Conditions]

When null is specified in the argument of the setEventHandler method in any of the following classes:

• Unmarshaller class

• Marshaller class

• Binder<Node> class

Operations of Cosminexus XML Processor

The event handler acquired using the getEventHandler method is the default event handler (DefaultValidationEventHandler) of JAXB1.0, and differs from the event handler acquired without executing the setEventHandler method. In such cases, the operations are not guaranteed.

24

[Conditions]

When all the following conditions are satisfied:

• Using the setProperty method of the Binder<Node> class, set up a value other than the default value in the jaxb.encoding property.

• Execute the marshal method of the Binder<Node> class.

Operations of Cosminexus XML Processor

The specified properties are not valid.

25

Condition

When all the following conditions are satisfied:

• The jaxb.formatted.output property is not set in the setProperty method of the Binder<Node> class, or false is set up.

• The marshal method of the Binder<Node> class is executed.

Operations of Cosminexus XML Processor

Regardless of the property settings, XML data with processed linefeeds and indents is output.

26

[Conditions]

When the following is specified in unmarshal (XmlNode xmlNode and Class<T> declaredType) of the javax.xml.bind.Binder<XmlNode> class:

• Specify xmlNode that is not in conformity with a class specified in declaredType.

Operations of Cosminexus XML Processor

Exceptions do not occur. In such cases, operations for executing JAXB are not defined, so the operations are not guaranteed.

27

[Conditions]

When the following is specified in updateXML (Object jaxbObject and XmlNode xmlNode) of the javax.xml.bind.Binder<XmlNode> class:

• In the jaxbObject argument, specify a JAXB object that is not associated to unmarshal and marshal.

• Specify the DOM node that was deleted after associating with the xmlNode argument.

Operations of Cosminexus XML Processor

In such cases, operations for executing JAXB are not defined, so the operations are not guaranteed.

28

[Conditions]

When the updateXML method of the javax.xml.bind.Binder<XmlNode> class is executed.

Operations of Cosminexus XML Processor

A new XML tree is created without updating the already existing XML tree that is associated to the JAXB object. Therefore, if the following information is included in the existing XML tree, this information will not be maintained after the method is executed:

• Comment

• PI

• XML elements or attributes that are not bound with JAXB

Also, a return value of updateXML (Object jaxbObject and XmlNode xmlNode) is not the node as that of the xmlNode argument. Therefore, when executing the updateXML method repetitively, do not specify the same value in the xmlNode argument.

29

[Conditions]

When executing the updateXML method of the javax.xml.bind.Binder<XmlNode> class.

Operations of Cosminexus XML Processor

Association of the JAXB object tree and an XML node having the implemented javax.xml.bind.Binder<XmlNode> class is invalid.

Therefore, after executing the method, the execution result of specifying the return value in the getJAXBNode (XmlNode xmlNode) argument is null. Also, when executing the method repetitively, the NullPointerException exception occurs.

Workaround

Perform the following changes, and in addition to invoking of the updateXML method, also invoke the updateJAXB method of the javax.xml.bind.Binder<XmlNode> class.

Before change:

binder.updateXML(rootbinder);

After change:

Node node = binder.updateXML(rootbinder);

rootbinder = (Root)binder.updateJAXB(node);

30

[Conditions]

When any of the following condition is satisfied:

• During the unmarshalling, an error occurs when a character string of the XML data is converted into a value of the target Java data type.

• During the marshalling, an error occurs when the data of the Java contents tree is converted into the text expression of the Java contents tree.

Operations of Cosminexus XML Processor

Events (parseConversionEvent for unmarshalling or printConversionEvent for marshalling) are not generated.

31

[Conditions]

When all the following conditions are satisfied:

1. Specify the xsi:type attribute in an XML document.

2. In the attribute value of step 1, specify a namespace prefix that is not used in the element and attribute names.

3. Unmarshal the XML document of step 1.

4. Marshal the object that is unmarshal in step 3 in the verification mode.

Example:

<foo xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<a/>

<b xsi:type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema">abc</b>

<c xsi:type="xsd:int" xmlns:xsd="http://www.w3.org/2001/XMLSchema">123</c>

</foo>

Operations of Cosminexus XML Processor

The following error is reported:

KECX06253-E UndeclaredPrefix: Cannot resolve 'xsd:string' as a QName: the prefix 'xsd' is not declared.

Also, if executing the marshalling without the verification mode, an XML document, in which the required name space is not declared, will be output.

32

[Conditions]

When all the following conditions are satisfied:

1. The field A is declared as the java.util.Calendar class.

2. Annotation is performed done for the field of step 1 using @XmlSchemaType(name="date").

3. Marshal a class with the fields that satisfy step in 1 and 2.

Operations of Cosminexus XML Processor

The contents of the elements within the XML document that corresponds to the field A is output in the xs:dateTime type and not in the xs:date type.

Therefore, if you use the schema the schema that is generated with the generateSchema method of the JAXBContext class to perform the schema verification, a verification error will occur.

Workaround

To output in the xs:date format while marshalling, use the javax.xml.datatype.XMLGregorianCalendar class and not the java.util.Calendar class.

33

[Conditions]

When executing the getOffset method of the ValidationEventLocator interface.

Operations of Cosminexus XML Processor

The return value of the getOffset method is always -1.