6.6 General Notes on XSLT and XSLTC

1

In multi-thread programming, the TransformerFactory and TransformerFactoryXSLTC classes are not thread-safe. Therefore, multiple threads must not access the same TransformerFactory instance and TransformerFactoryXSLTC instance at the same time. To avoid conflicts between threads, use one of the following methods:

• Each thread has one TransformerFactory instance and one TransformerFactoryXSLTC instance.

• Each thread exclusively accesses the TransformerFactory and TransformerFactoryXSLTC instances.

2

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

• Each thread has one Transformer instance.

3

In multi-thread programming, the SAXTransformerFactory class, TemplatesHandler and TransformerHandler objects are not thread-safe. Therefore, make sure that each thread exclusively accesses these objects.

4

The XSLT and XSLTC transformers provide the same function, but the messages output when an error occurs might differ.

5

If you specify http://www.w3.org/1999/XSL/Transform for the namespace attribute of the xsl:attribute element, the namespace prefix of the output attribute might differ according to whether XSLT or XSLTC is used. However, the namespace prefix itself has no meaning for a parser with the namespace enabled.

6

When you specify a name other than QName for the name attribute of the xsl:attribute and xsl:processing-instruction element, a warning event occurs in XSLT and an error event occurs in XSLTC.

7

For an error event occurring when there are multiple xsl:decimal-format elements whose attributes except the name attribute have different values, a fatalError event occurs in XSLT, and a warning event occurs in XSLTC.

8

For the name attribute of the xsl:element or xsl:attribute element, do not specify a name with a namespace prefix beginning with xml.

9

When the name attribute of an xsl:element, xsl:attribute, or xsl:processing-instruction element is a variable reference that is an empty character string, a warning event occurs in XSLT and an error event occurs in XSLTC.

10

When there is no name attribute for the xsl:element element, an error event occurs in XSLT and a warning event occurs in XSLTC.

11

If you use the xsl:namespace-alias element, the namespace prefix of the output attribute might differ according to whether XSLT or XSLTC is used. However, the namespace prefix itself has no meaning for a parser with the namespace enabled.

12

For format tokens specified for the format attribute of the xsl:number element, specify either A, a, i, I, 1, or an optional number of zeros (0) followed by 1.

13

When the level attribute of the xsl:number element is any, the behavior might differ according to whether you use XSLT or XSLTC if you specify a pattern that indicates an attribute node for the count attribute. In XSLT, the attribute node is not counted, but in XSLTC, the attribute node is counted.

14

Do not specify an empty character string for the doctype-system attribute of the xsl:output element. Similarly, never specify an empty character string for the doctype-system property by using the setOutputProperty method of the Transformer class.

15

For the method attribute of the xsl:output element, specify either xml, html, or text.

16

When you type an XPath expression whose evaluation result is an empty character string for the name attribute of the xsl:processing-instruction element, a warning event occurs in XSLT and an error event occurs in XSLTC.

17

If you type a variable reference for the select attribute of the xsl:value-of element, a TransformerException occurs.

18

The evaluation result of document(/) might differ according to whether XSLT or XSLTC is used. In XSLT, document(/) is evaluated as a root element of the stylesheet, but in XSLTC, document(/) is evaluated as an empty set of nodes.

19

When you specify a character string for the first argument of the document function, an error level might differ according to whether you use XSLTC or XSLT if you specify the following XML document as the character string:

• XML document that does not exist

• XML document that is not well-formed

20

If you include a currency sign (#x00A4) in the format pattern string of the format-number function, an error might not occur.

21

For the argument of the system-property function, specify either xsl:version, xsl:vendor, or xsl:vendor-url.

22

In the transformation using an embedding stylesheet, if there are multiple stylesheet elements corresponding to the ID specified by the pseudo attribute href of the processing instruction xml-stylesheet, the applied template might differ according to whether XSLT or XSLTC is used. In XSLT, the last template to appear is applied, but in XSLTC, the first template to appear is applied.

23

With the transformer function, when an unsupported encoding is specified for the output property, the error message (KECX02322-W) is not reported to the error listener but is output to the standard output stream even if the error listener is registered with the transformer in the application. Note that, in case of XSLTC, the error message (KECX07076-W) is reported to the error listener as well as the above error message being output to the standard output stream. For details on the messages, see 11. KECX (Messages Output by Cosminexus XML Processor) in the manual uCosminexus Application Server Messages.

24

When the transformation result is output in HTML format, the linefeed output between elements might differ according to whether XSLT or XSLTC is used. However, as the linefeed between elements has no meaning in the HTML document, there is no problem.

25

When all of the following conditions are met, an IllegalArgumentException instead of IllegalStateException occurs if the setNode(Node node) method of the DOMResult object is executed:

• nextSibling of the DOMResult object is not null.

• nextSibling is not the child of the argument node.

In this case, in the catch clause that handles exceptions of the setNode method, you must catch not only IllegalStateException but also IllegalArgumentException exceptions.

26

At the locations evaluated as QName in the stylesheet (such as name attribute of the xsl:element element, and first argument of the key function), the process continues execution without any error even when characters that are not allowed to be used as names (such as Unicode supplementary characters, and double-byte numeric characters) according to the XML1.0 standards are used. In such cases, even though xml is specified as the output method in the transformer, and 1.0 is specified as the output version, the output document is not compliant to XML1.0 standards.

27

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.

28

Specify the new Document object created by the newDocument method of the DocumentBuilder class ,when setting the Document object in the constructor argument of DOMResult indicated below:

• DOMResult (Node node)

• DOMResult (Node node and String systemId)

29

When an XSLT style sheet using the id functionality is applied to an XML document that includes an ID type attribute with a duplicated value, the result of the id functionality might be invalid.

30

The speed of executing the transformation processing for a transformer decreases greatly,if the following conditions are satisfied:

• The input XML document contains a large amount of entity references.

• The output destination of the transformer is DOMResult.

31

When all the following conditions are satisfied, a fatalError event occurs during the invocation of the newTemplates method or the newTransformer method of the TransformerFactory class. Return value of the method becomes null.

1. Instead of XSLTC, XSLT is used as the transformer.

2. XMLStreamReader or XMLEventReader is created by invoking the createXMLStreamReader method or the createXMLEventReader method of the XMLInputFactory class without specifying a system identifier in arguments of the methods.

3. XMLStreamReader or XMLEventReader created in step 2 above is specified in the constructor argument of StAXSource.

4. StAXSource created in step 3 above is specified in the argument of the newTemplates method or the newTransformer method of the TransformerFactory class.

Take action using any of the following methods:

• Use XSLTC instead of XSLT.

• Specify a system identifier in the argument of the createXMLStreamReader method or the createXMLEventReader method.

• Use a source other than StAXSource.

32

When all the following conditions are specified, the encoding pseudo attribute is not output to the XML declaration of output results of the transformer. Furthermore, if the conditions described in step 1 and step 2 overlap, the standalone pseudo attribute is not output.

1. StAXResult is specified in the output of the transformer.

2. xml is specified in the output method of the XSLT style sheet or the settings of the output property of the transformer.

3. In StAXResult described in step 1 above, either XMLStreamWriter, or XMLEventWriter for which an output encoding other than UTF-8 is indicated, is specified.

33

When all the following conditions are specified, an XML declaration is not output in the output result of the transformer:

• StAXResult is specified in the output of the transformer.

• xml is specified in the output method of the XSLT style sheet or the settings of the output property of the transformer.

• A node matching the template of the XSLT style sheet does not exist in the input XML document.

34

When all the following conditions are satisfied, regardless of the output results of the transformer, xml is assumed as an output method.

• StAXResult is specified in the output of the transformer.

• No output method is specified in the XSLT style sheet or the settings of the output property of the transformer.

35

When StAXResult is used in the output of the transformer, the following properties specified in the XSLT style sheet or the output property of the transformer are disabled:

• omit-xml-declaration

• doctype-system

• doctype-public

• cdata-section-elements

36

When StAXResult is used in the output of the transformer, an error is not thrown even if an inappropriate value is specified in the following properties that are specified in the XSLT style sheet or the output property of the transformer, and therefore the specification is disabled:

• version

• encoding

37

When all the following conditions are specified, the content of the xsl:text element, in which yes is specified in the disable-output-escaping attribute within the output result of the transformer, is not escaped and is output:

• StAXResult is specified in the output of the transformer.

• yes is specified in the disable-output-escaping attribute of the xls:text element in the XSLT style sheet.

Furthermore, the following processing instruction is added before and after the output character string:

Example:

<?javax.xml.transform.disable-output-escaping ?>&lt;<?javax.xml.transform.enable-output-escaping ?>

38

When all the following conditions are specified, characters are output before the XML declaration of the output result of the transformer:

• StAXResult is specified in the output of the transformer.

• xml is specified in the output method of the XSLT style sheet or the settings of the output property of the transformer.

• Characters are output before the root element (prologue part) of the output tree.