6.2 Notes on the DOM Parser

1

In multi-thread programming, the DocumentBuilderFactory class is not thread-safe. Therefore, multiple threads must not access the same DocumentBuilderFactory instance at the same time. To avoid conflicts between threads, use one of the following methods:

• Each thread has one DocumentBuilderFactory instance.

• Each thread exclusively accesses the DocumentBuilderFactory instance.

2

In multi-thread programming, the DocumentBuilder class is not thread-safe. Therefore, multiple threads must not use the same DocumentBuilder instance at the same time. To avoid conflicts between threads, use the following method:

• Each thread has one DocumentBuilder instance.

3

In multi-thread programming, the DOM tree is not thread-safe. Therefore, multiple threads must not access the same DOM tree generated by the parse method at the same time. Not only update methods, but also reference methods must not access such trees at the same time. To avoid conflicts between threads, use the following method:

• Each thread exclusively accesses the DOM tree.

4

In multi-thread programming, the objects defined by org.w3c.dom, org.w3c.dom.bootstrap, and org.w3c.dom.ls packages are not thread-safe. Therefore, multiple threads must not access these objects at the same time. Not only update methods, but also reference methods must not access such trees at the same time. To avoid conflicts between threads, use the following method:

• Each thread exclusively accesses these objects.

5

If you generate an Attr node by using the createAttribute or createAttributeNS method of the Document interface, set a value in the setValue method of the Attr interface. If you get NodeList in the getChildNodes method of the Node interface while the value is not set, the NodeList's behavior is not guaranteed.

6

If you add an element to the Document node that already has an Element node by using the insertBefore or the appendChild method of the Node interface, the result is the same as when you use the replaceChild method of the Node interface.

7

When an error occurs in the parse methods that take InputStream or InputSource as an argument of the DocumentBuilder class, null might be returned if you apply the getSystemId method to the SAXParseException passed to the error handler. If you want to return the system identifier of the error source, use the parse method as follows:

• In the parse(InputStream is, String systemId) method, specify the system identifier for the systemId argument.

• In the parse(InputSource is) method, specify the InputSource that has the system identifier set for the is argument.

8

If you analyze an XML document saved in UTF-16 with BOM (Byte Order Mark) by using the parse(InputSource is) method, specify UTF-16 for the argument if you apply the setEncoding method to the InputSource.

9

If an element name with 477 or more characters is included in the character string that defines an internal entity, the java.lang.IndexOutOfBoundsException exception might occur.