6.4 Notes on StAX
The following table lists the notes on StAX.
No. |
Notes |
---|---|
1 |
The StAX 1.0 specifications include methods for which operations are not clearly defined. The operations of such methods depend on the implementation. Check the arguments beforehand so that there are no undefined operations. Examples of undefined operations are as follows:
|
2 |
Some methods of the XMLStreamReader interface have a different description in Javadoc and APIs. Cosminexus XML Processor operates as per the API description. The methods that have different descriptions and differences are as follows:
|
3 |
Condition When you specify an XML document with different systemId and stream arguments for the createXMLStreamReader(String systemId, InputStream stream) method of XMLInputFactory Standard specifications No operations are defined. Operations of Cosminexus XML Processor The argument stream is enabled. However, if the argument stream is null, the argument systemId is enabled. |
4 |
Condition When you specify an XML document with different systemId and reader arguments for the createXMLStreamReader(String systemId, Reader reader) method of XMLInputFactory Standard specifications No operations are defined. Operations of Cosminexus XML Processor The argument reader is enabled. However, if the argument reader is null, the argument systemId is enabled. |
5 |
Condition When you execute the getEventType() method of the javax.xml.stream.XMLStreamReader interface for the attribute and namespace declarations in the XML document Standard specifications Javadoc for XMLStreamReader contains description related to attribute and namespace parsing, but does not clearly define whether parsing-based events will occur. Operations of Cosminexus XML Processor The ATTRIBUTE event type and NAMESPACE event type are not returned. Process the attribute and namespace when the START_ELEMENT event type is returned. |
6 |
Condition When you specify a value exceeding the number of attributes or namespace declarations, in the index argument of the following methods, among the methods of the XMLStreamReader interface:
Standard specifications No operations are defined. Operations of Cosminexus XML Processor The return value for the isAttributeSpecified(int index) method is false. The return value for the other methods is null. |
7 |
Condition When you execute the getTextCharacters(int sourceStart, char[] target, int targetStart, int length) method of the XMLStreamReader interface for the COMMENT event type Standard specifications The descriptions in Javadoc and XMLStreamReader differ as follows:
Operations of Cosminexus XML Processor The text related to the COMMENT event is acquired. |
8 |
Condition When all the following conditions are satisfied:
Standard specifications No operations are defined. Operations of Cosminexus XML Processor One of the bound prefixes becomes the return value. |
9 |
Condition When all the following conditions are satisfied:
Standard specifications No operations are defined. Operations of Cosminexus XML Processor Reset the bind destination prefix for the URI specified in setPrefix. |
10 |
Condition When all the following conditions are satisfied:
Standard specifications The standard specifications do not define whether to return the encoding for the XML document or for the XML declaration. Operations of Cosminexus XML Processor The encoding for the XML document (UTF-16BE or UTF-16LE) is returned instead of the encoding specified in the XML declaration. |
11 |
Condition When you specify a namespace URI in the arguments of the createStartElement method and the createEndElement method, or the createAttribute method of the XMLEventFactory class Standard specifications The standard specifications do not define whether to write the namespace URI specified in the argument as the namespace declaration in the output XML document. Operations of Cosminexus XML Processor The namespace URI specified in the argument is not written as the namespace declaration in the output XML document. Use the createNamespace method to explicitly create the namespace declaration. |
12 |
Condition When you parse an external entity by using the XMLStreamReader interface Standard specifications The standard specifications do not define whether to deploy the external entity. Operations of Cosminexus XML Processor The EntityReference event is not generated. An event (such as CHARACTERS or START_ELEMENT) is generated for the entity that deploys the entity reference. |
13 |
You cannot specify "" in the prefix argument of the createAttribute(String prefix, String namespaceURI, String localName, String value) method for the XMLEventFactory class. |
14 |
Do not specify a string other than a space in the content argument of the createIgnorableSpace(String content) method for the XMLEventFactory class. |
15 |
The default value of the javax.xml.stream.isSupportingExternalEntities property in the XMLInputFactory class is true. |
16 |
To specify null in the following properties of the XMLInputFactory class, use the setEventAllocator method, the setXMLReporter method, or the setXMLResolver method. Do not use the setProperty method.
|
17 |
The specification of the following properties of the XMLInputFactory class is not affected even if you specify false as the value of the javax.xml.stream.supportDTD property:
|
18 |
Condition If the input XML contains the following elements and attributes in the add(XMLEventReader reader) method of the XMLEventWriter class, the format of output XML and input XML is different:
Operations of Cosminexus XML Processor
|
19 |
The getNamespaceContext() method returns null for the StartElement event generated by using the createStartElement method of the XMLEventFactory class. |
20 |
You cannot use the ISO-10646-UCS-4 encoding. |
21 |
You cannot use XML version 1.1 documents. |
22 |
You cannot specify supplementary characters in the following parts of StAX:
|
23 |
The Characters event might be reported separately. The StAX parser can also divide a single string data into multiple strings (chunk) and report data to an application as multiple Characters events. Therefore, you need to be aware that the Characters event occurs continuously on the application side. |
24 |
Condition When you execute the getName() method of the XMLStreamReader interface for event types other than START_ELEMENT/ END_ELEMENT Operations of Cosminexus XML Processor The IllegalArgumentException exception occurs. The IllegalStateException exception does not occur. |
25 |
Condition When you execute the getPrefix() or getAttributePrefix(int index) methods of the XMLStreamReader interface for the elements without prefixes Operations of Cosminexus XML Processor The return value is ""(XMLConstants.DEFAULT_NS_PREFIX). |
26 |
Condition When you use the getAttributeValue(String namespaceURI,String localName) method of the XMLStreamReader interface to specify null in the namespaceURI argument and the local name of the attribute in the localName argument for the attributes with namespaces Operations of Cosminexus XML Processor The return value is null. The attribute value is not acquired. |
27 |
Condition When you execute the getEncoding() method or the getVersion() method of the XMLStreamReader interface for the END_DOCUMENT or the ENTITY_REFERENCE event types Operations of Cosminexus XML Processor For the END_DOCUMENT event type, the NullPointerException exception occurs. For the ENTITY_REFERENCE event type, the return value is null. |
28 |
Condition When you execute the isAttributeSpecified(int index) method of the XMLStreamReader interface Operations of Cosminexus XML Processor The return values differ as follows:
|
29 |
Condition When you execute the hasName() method of the XMLStreamReader interface for the ENTITY_REFERENCE event type Operations of Cosminexus XML Processor The return value is true. |
30 |
Condition When you execute the getText() method of the XMLStreamReader interface for the DTD event type Operations of Cosminexus XML Processor "String value of the DOCTYPE declaration" is returned. Same is the case when the DTD internal subset exists. "String value of DTD internal subset" is not returned. |
31 |
Condition When you execute the getElementText() method of the XMLStreamReader interface for the contents of an element containing an internal entity reference. Operations of Cosminexus XML Processor The return value is a string with the replacement text of the internal entity reference concatenated twice. |
32 |
Condition When one of the following conditions is satisfied:
Operations of Cosminexus XML Processor The return value is java.util.List without an element. |
33 |
Condition When all the following conditions are satisfied:
Operations of Cosminexus XML Processor The acquired DTD declaration text is invalid. |
34 |
Condition When an invalid string is specified in the attribute value of the pseudo attribute in the XML declaration Operations of Cosminexus XML Processor The com.cosminexus.stax.xml.stream.internal.xni.XNIException exception occurs. Also, a detailed string might not be output within {} (curly brackets) in the message.
|
35 |
Condition When you execute one of the following methods:
Operations of Cosminexus XML Processor The Location information is obtained as an approximate value for identifying the location where the exception occurred. |
36 |
Condition When all the following conditions are satisfied:
Standard specifications A parsing error occurs. Operations of Cosminexus XML Processor Parsing terminates normally. |
37 |
Condition When you specify true in the standalone parameter of the createStartDocument(String encoding, String version, boolean standalone) method of the XMLEventFactory class Standard specifications An XML document is generated with the standalone status true. Operations of Cosminexus XML Processor The standalone declaration is not generated. |
38 |
Condition When all the following conditions are satisfied:
Standard specifications Returns the default value 1.0. Operations of Cosminexus XML Processor Returns null. |
39 |
Condition When you execute the nextEvent() method of the XMLEventReader class for the following parts in the XML document:
Operations of Cosminexus XML Processor
|
40 |
Condition When you execute the getEventType() method of the XMLStreamReader interface for the following parts in the XML document:
Operations of Cosminexus XML Processor Both blank string and CDATA section become the CHARACTERS event type, therefore, process both as CHARACTERS event types. |
41 |
Condition When all the following conditions are satisfied:
Operations of Cosminexus XML Processor Only the attribute is output. The namespace declaration (xmlns:prefix="namespaceURI") is not output. |
42 |
You cannot use the writeAsEncodedUnicode(Writer writer) method for the following interfaces included in the javax.xml.stream.events package:
|
43 |
You cannot use the allocate(XMLStreamReader reader, XMLEventConsumer consumer) method of the XMLEventAllocator interface included in the javax.xml.stream.util package. |
44 |
In multi-thread programming, the XMLInputFactory class is not thread-safe. Therefore, make sure that multiple threads do not access the same XMLInputFactory instance concurrently. Use either of the following methods to avoid competition between threads:
|
45 |
In multi-thread programming, the XMLOutputFactory class is not thread-safe. Therefore, make sure that multiple threads do not access the same XMLOutputFactory instance concurrently. Use either of the following methods to avoid competition between threads:
|
46 |
In multi-thread programming, the XMLEventFactory class is not thread-safe. Therefore, make sure that multiple threads do not access the same XMLEventFactory instance concurrently. Use one of the following methods to avoid competition between threads:
|
47 |
In multi-thread programming, the XMLStreamReader interface is not thread-safe. Therefore, make sure that multiple threads do not use the same XMLStreamReader instance concurrently. To avoid competition between threads, each thread must have one XMLStreamReader instance. |
48 |
In multi-thread programming, the XMLStreamWriter interface is not thread-safe. Therefore, make sure that multiple threads do not use the same XMLStreamWriter instance concurrently. To avoid competition between threads, each thread must have one XMLStreamWriter instance. |
49 |
In multi-thread programming, the XMLEventReader class is not thread-safe. Therefore, make sure that multiple threads do not use the same XMLEventReader instance concurrently. To avoid competition between threads, each thread must have one XMLEventReader instance. |
50 |
In multi-thread programming, the XMLEventWriter class is not thread-safe. Therefore, make sure that multiple threads do not use the same XMLEventWriter instance concurrently. To avoid competition between threads, each thread must have one XMLEventWriter instance. |
51 |
The namespace argument of the resolveEntity method for the javax.xml.stream.XMLResolver interface is always null. |
52 |
Among the return values of the resolveEntity method for the javax.xml.stream.XMLResolver interface, the XMLStreamReader type and the XMLEventReader type objects are not supported. Standard specifications These resources have one of the following return value types:
|
53 |
The return value of the getLocation() method for the following events is null:
|
54 |
Among the XMLOutputFactory classes, you cannot specify StAXResult for which the system identifier is not specified in the result argument of the following methods:
|
55 |
Condition When all the following conditions are satisfied:
Standard specifications The prefix is not written. Operations of Cosminexus XML Processor The prefix is written. |
56 |
Condition When all the following conditions are satisfied:
Standard specifications The prefix is generated randomly.
Operations of Cosminexus XML Processor A random prefix is not generated.
|
57 |
Condition When all the following conditions are satisfied:
Standard specifications The namespace declaration is generated. Operations of Cosminexus XML Processor The namespace declaration is not generated. |
58 |
Condition When all the following conditions are satisfied:
Standard specifications The XMLStreamException exception occurs. Operations of Cosminexus XML Processor There is no error. The value is written as follows:
|
59 |
Condition When all the following conditions are satisfied:
Standard specifications The prefix is not written. Operations of Cosminexus XML Processor The following prefixes are written:
|
60 |
Condition When all the following conditions are satisfied:
Standard specifications The prefix is not written. Operations of Cosminexus XML Processor The XMLStreamException exception occurs. |
61 |
Condition When all the following conditions are satisfied:
Standard specifications If prefix == "" || null, the value is processed as the default namespace. The prefix is not generated or written. If namespaceURI is not bound, the xmlns declaration is generated or written. Operations of Cosminexus XML Processor The prefix is generated randomly. The value is not processed as the default namespace. |
62 |
Condition When you specify an XML document for which ISO-10646-UCS-2 is specified in the encoding argument and the encoding pseudo attribute ISO-10646-UCS-2 is specified in the stream argument of the following methods of the XMLInputFactory class:
Operations of Cosminexus XML Processor The com.cosminexus.stax.xml.stream.internal.xni.XNIException exception occurs. Workaround Process by using the createXMLEventReader or createXMLStreamReader methods in which encoding is not specified. |
63 |
Condition When all the following conditions are satisfied:
Standard specifications
Operations of Cosminexus XML Processor The namespace context does not have information on xml and xmlns prefix. |
64 |
When an XML document is read with XMLEventReader, irrespective of the presence or absence of the standalone attribute, the return value of the standaloneSet() method of the StartDocument event is true. Standard specifications The return value is true only if the standalone attribute is set up in the encoding declaration of the XML document. |
65 |
The getEntities() and getNotations() methods of the DTD event always return null. Workaround You can access the information by using the javax.xml.stream.entities and javax.xml.stream.notations properties. For details, see Javadoc for XMLStreamReader. |
66 |
Condition When you specify a type for which the system identifier is not specified for the createXMLEventReader(Source source) or createXMLStreamReader(Source source) methods of the XMLInputFactory class. The applicable types are as follows:
Operations of Cosminexus XML Processor The XMLStreamException exception occurs. |
67 |
The return value of the getProcessedDTD() method of the DTD event is always null. |
68 |
The return value of the getNamespaces() method of the Endelement event is always a blank Iterator. Operations of Cosminexus XML Processor An out-of-range namespace Iterator is returned. |
69 |
Condition When all the following conditions are satisfied:
Standard specifications The XMLStreamException exception is thrown from the XMLStreamReader interface or XMLEventReader interface. Operations of Cosminexus XML Processor
|
70 |
If the output encoding is not specified in the createXMLEventWriter(OutputStream stream) and createXMLStreamWriter(OutputStream stream) methods of the XMLOutputFactory class, XMLEventWriter, and XMLStreamWriter are output by using the default system character code. |
71 |
The execution results of the createStartDocument() method of the XMLEventFactory class are same as when UTF-8 is specified in the encoding argument of the createStartDocument(String encoding, ...) method. |
72 |
Condition When all the following conditions are satisfied:
Operations of Cosminexus XML Processor An invalid XML document with an output encoding other than UTF-8 and UTF-16, and without the encoding pseudo attribute is output. Workaround Specify UTF-8 in the encoding specification of the createXMLEventWriter method and the createXMLStreamWriter method for the XMLOutputFactory class. |
73 |
Condition When all the following conditions are satisfied:
Operations of Cosminexus XML Processor When StAXResult created with the above conditions is specified as an argument in either of the following methods, and an XML document including a namespace declaration is processed, an XMLStreamException exception occurs:
Workaround Specify Boolean.TRUE in the javax.xml.stream.isRepairingNamespaces property of XMLOutputFactory. |