uCosminexus Application Server

XML Processor User Guide

3020-3-Y22-10(E)

Contents

Notices

Summary of amendments

Preface

1. An Overview of Cosminexus XML Processor

1.1 Product Features of Cosminexus XML Processor

1.1.1 Enables Creation of Cross-platform Programs

1.1.2 Enables Easy Parsing of XML Documents Using Java Programs

1.1.3 Enables Easy Transformation of XML Documents Using Java Programs

1.1.4 Improves the ease in development of XML-based applications

1.2 Positioning of Cosminexus XML Processor

1.3 Range of Features Supported by Cosminexus XML Processor

1.3.1 Available functions such as the XML Parser and XSLT Transformer

1.3.2 Character encodings that can be processed

1.3.3 Shift_JIS Switch Function

1.3.4 XSLTC Transformer Function

1.3.5 Schema cache functionality

1.3.6 High-speed parse support function

1.3.7 Apache-specific functions

2. JAXP and JAXB Functionality

2.1 About JAXP

2.2 JAXP-defined Packages and Their Functionality

2.2.1 javax.xml.parsers Package

2.2.2 javax.xml.stream Package

2.2.3 javax.xml.stream.events Package

2.2.4 javax.xml.stream.util Package

2.2.5 javax.xml.transform Package

2.2.6 javax.xml.transform.dom Package

2.2.7 javax.xml.transform.sax Package

2.2.8 javax.xml.transform.stax Package

2.2.9 javax.xml.transform.stream Package

2.2.10 javax.xml.validation Package

2.2.11 javax.xml.xpath Package

2.2.12 javax.xml.namespace Package

2.2.13 javax.xml.datatype Package

2.2.14 javax.xml Package

2.2.15 org.w3c.dom Package

2.2.16 org.w3c.dom.bootstrap Package

2.2.17 org.w3c.dom.ls Package

2.2.18 org.w3c.dom.events Package

2.2.19 org.xml.sax Package

2.2.20 org.xml.sax.ext Package

2.2.21 org.xml.sax.helpers Package

2.3 About JAXB

2.4 JAXB-defined Packages and Their Functionality

2.5 JAXB commands

2.5.1 csmxjc command (Binding from the XML Schema to Java)

2.5.2 csmschemagen command (Mapping from Java to the XML Schema)

3. Extended Functions of Cosminexus XML Processor

3.1 Shift_JIS Switch Function

3.2 XSLTC Transformer Function

3.2.1 An Overview of XSLTC Transformer

3.2.2 XSLTC Transformer-based System Development and Operation

3.2.3 Class Used by the XSLTC Transformer

3.2.4 How to use the XSLTC Transformer

3.3 Schema cache functionality

3.3.1 Overview of the schema cache functionality

3.3.2 Processing of the schema cache functionality

3.3.3 Setting up the schema cache

3.3.4 Using the schema cache

3.3.5 Deleting and resetting the schema cache

3.3.6 About using the most appropriate schema cache

3.4 High-speed parse support function

3.4.1 Overview of the high-speed parse support function

3.4.2 Flow of operations for high-speed parse

3.4.3 Creating the Pre-Parse XML document

3.4.4 Generating the preparsed object

3.4.5 Setting up the preparsed object

3.4.6 Parsing the XML document

3.4.7 Classes used in preparing the high-speed parse support function

3.4.8 Coding example for using the high-speed parse support function

3.4.9 Tuning the Pre-Parse XML document

3.4.10 Details of the tuning summary file

3.4.11 Details of the tuning details file

3.5 Apache-specific functions

3.5.1 Features that can be set up

3.5.2 Properties that can be set up

3.5.3 Namespace URIs that can be set up

3.6 Correspondence Between Error Messages in XML Schema and W3C Specifications

3.7 Parser Switching functionality

3.7.1 Overview of the Parser Switching functionality

3.7.2 Usage of the Parser Switching functionality

3.7.3 Performance of the Parser Switching functionality

3.7.4 Notes on the Parser Switching functionality

3.8 Compatibility option functionality

3.8.1 Overview of the compatibility option functionality

3.8.2 How to set up the compatibility option functionality

4. How to Use Features and Properties

4.1 How to Use the SAX2 Features and Properties

4.2 How to use StAX properties

4.3 How to use XSLT features

4.4 How to Use the XML Schema Properties

4.4.1 How to Set the XML Schema Properties for the DOM Parser

4.4.2 How to Set the XML Schema Properties SAX Parser

4.4.3 How to Set the Schema Document in the XML Document

4.5 How to use the properties of the Shift_JIS switch function

4.5.1 How to Use the Shift_JIS Switch Function for the DOM Parser

4.5.2 How to Use the Shift_JIS Switch Function for the SAX Parser

4.5.3 How to Use the Shift_JIS Switch Function for the XSLT Transformer

4.6 How to use the properties of the high-speed parse support function

4.6.1 How to set up the preparsed object in DocumentBuilder

4.6.2 How to set up the preparsed object in SAXParser

4.6.3 How to set up the preparsed object in XMLReader

4.7 How to use the properties of JAXB

5. How to Create a Program

5.1 General Procedure for Creating a Program

5.2 Package Names Used by Cosminexus XML Processor

5.3 Troubleshooting Program Execution

5.4 Sample Program that Uses the DOM Parser

5.4.1 Processing Performed by the Sample Program

5.4.2 General Procedure for Creating the Sample Program

5.4.3 Sample program (SampleDOM.java)

5.4.4 Execution Result of the Sample Program (SampleDOM.java)

5.5 Sample Program that Uses the SAX Parser

5.5.1 Processing Performed by the Sample Program

5.5.2 General Procedure for Creating the Sample Program

5.5.3 XML Document to Use (SampleSAX.xml)

5.5.4 Sample Program (SampleSAX.java)

5.5.5 Execution Result of the Sample Program (SampleSAX.java)

5.6 Sample Program that Uses the XML Schema

5.6.1 Processing Performed by the Sample Program

5.6.2 XML Document to Use (purchaseOrder.xml and purchaseOrder-fail.xml)

5.6.3 Schema Documents to Use (purchaseOrder.xsd, personalData.xsd)

5.6.4 Sample Program When Using the DOM parser

5.6.5 Sample Program When Using the SAX Parser

5.7 Sample Program that Uses the XSLT Transformer

5.7.1 Processing Performed by the Sample Program

5.7.2 General Procedure for Creating the Sample Program

5.7.3 XML Document to Use (SampleXSLT.xml)

5.7.4 XSL File to Use (SampleXSLT.xsl)

5.7.5 Sample Program (SampleXSLT.java)

5.7.6 Execution Result of the Sample Program (SampleXSLT.java)

5.8 Sample Program that Uses the XSLTC Transformer

6. Notes on Using Cosminexus XML Processor

6.1 Notes common to JAXP1.4 functions

6.1.1 Range supported in the javax.xml.transform.stax.StAXSource class and the javax.xml.transform.stax.StAXResult class

6.1.2 Other notes

6.2 Notes on the DOM Parser

6.3 Notes on the SAX Parser

6.4 Notes on StAX

6.5 Notes on the Schema Validation

6.6 General Notes on XSLT and XSLTC

6.7 Notes on XSLT

6.7.1 Cases Where XSLT Does Not Report Errors

6.7.2 Other Notes

6.8 Notes on XSLTC

6.8.1 Notes on the Stylesheet Size

6.8.2 Notes on Transformation Performance

6.8.3 Notes on XSLT Elements

6.8.4 Notes on the XPath Expression

6.8.5 Cases where XSLTC Does Not Report Errors

6.8.6 Other Notes

6.9 Notes on the javax.xml.datatype Package

6.10 Notes on the javax.xml.validation Package

6.11 Notes on the javax.xml.xpath Package

6.12 Notes on the org.w3c.dom Package

6.13 Notes on the org.w3c.dom.bootstrap Package

6.14 Notes on the org.w3c.dom.ls Package

6.15 Notes on the org.xml.sax.ext Package

6.16 Notes on XInclude

6.17 Notes on implementation-dependent specifications

6.18 Precautions related to the schema cache functionality

6.18.1 Precautions related to performance

6.18.2 Precautions related to error output

6.18.3 Precautions related to schema definition files

6.18.4 Precautions related to reset up and deletion of a cache

6.19 Notes on the high-speed parse support function

6.19.1 Notes on setting up the preparsed object

6.19.2 Notes on the XML parser using the preparsed object

6.19.3 Notes on XML1.1

6.19.4 Notes on XInclude (high-speed parse support function)

6.19.5 Notes on how to specify an absolute path

6.19.6 Notes on the Pre-Parse XML document

6.19.7 Notes on tuning information

6.19.8 Notes on parse performance

6.20 Notes on JAXB

6.20.1 Common notes

6.20.2 Notes on schema compiler

6.20.3 Notes on schema generator

6.20.4 Notes on runtime

6.21 General XML Processor related notes

Appendixes

A. Differences Between Versions

A.1 Differences in Behaviors Between DOM and SAX Parser Versions

A.2 Differences in Behaviors Between DOM Parser Versions

A.3 Differences in Behaviors Between SAX Parser Versions

A.4 Differences in Behaviors of Schema Validation Between Versions

A.5 Differences in Behaviors of XSLT Between Versions

A.6 Differences in the JAXB operation

A.7 Differences in the operation of the javax.xml.datatype package

A.8 Differences in the operation of the high-speed parse functionality

A.9 Differences in the operation of StAX

A.10 Differences in the operations of the Apache-specific functionality

B. Support Range of JAXB Specifications

B.1 Support range of the JAXB functions

B.2 Support range for JAXB characters

B.3 Support range of functions assumed as vendor-specific according to JAXB specifications

C. Efficiently using XML Processor

C.1 Basic functionality of XML Processor

C.2 Application functionality of XML Processor

C.3 Know-how for efficiently using XML Processor

D. Glossary

Index

[Trademarks]

All Rights Reserved. Copyright (C) 2013, Hitachi, Ltd.

Notices

Relevant program products

See the manual uCosminexus Application Server Overview.

Export restrictions

If you export this product, please check all restrictions (for example, Japan's Foreign Exchange and Foreign Trade Law, and USA export control laws and regulations), and carry out all required procedures.
If you require more information or clarification, please contact your Hitachi sales representative.

Trademarks

AIX is a trademark of International Business Machines Corporation in the United States, other countries, or both.
Microsoft is either a registered trademark or trademark of Microsoft Corporation in the United States and/or other countries.
Oracle and Java are registered trademarks of Oracle Corporation and/or its affiliates.
SOAP is an XML-based protocol for sending messages and making remote procedure calls in a distributed environment.
UNIX is a registered trademark of The Open Group in the United States and other countries.
W3C is a trademark (registered in numerous countries) of the World Wide Web Consortium.
Windows, Windows Server, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
Other product and company names mentioned in this document may be trademarks or registered trademarks of their respective owners.
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).
Throughout this document Hitachi has attempted to distinguish trademarks from descriptive terms by writing the name with the capitalization used by the manufacturer, or by writing the name with initial capital letters. Hitachi cannot attest to the accuracy of this information. Use of a trademark in this document should not be regarded as affecting the validity of the trademark.

Microsoft product name abbreviations

This manual uses the following abbreviations for Microsoft product names:

Abbreviation | Full name or meaning
Windows | Windows Server 2008 | Windows Server 2008 x86 | Microsoft(R) Windows Server(R) 2008 Standard 32-bit
Microsoft(R) Windows Server(R) 2008 Enterprise 32-bit
Windows Server 2008 x64 | Microsoft(R) Windows Server(R) 2008 Standard
Microsoft(R) Windows Server(R) 2008 Enterprise
Windows Server 2008 R2 | Microsoft(R) Windows Server(R) 2008 R2 Standard
Microsoft(R) Windows Server(R) 2008 R2 Enterprise
Microsoft(R) Windows Server(R) 2008 R2 Datacenter
Windows Server 2012 | Windows Server 2012 Standard | Microsoft(R) Windows Server(R) 2012 Standard
Windows Server 2012 Datacenter | Microsoft(R) Windows Server(R) 2012 Datacenter
Windows XP | Microsoft(R) Windows(R) XP Professional Operating System
Windows Vista | Windows Vista Business | Microsoft(R) Windows Vista(R) Business (32bit)
Windows Vista Enterprise | Microsoft(R) Windows Vista(R) Enterprise (32bit)
Windows Vista Ultimate | Microsoft(R) Windows Vista(R) Ultimate (32bit)
Windows 7 | Windows 7 x86 | Microsoft(R) Windows(R) 7 Professional (32bit)
Microsoft(R) Windows(R) 7 Enterprise (32bit)
Microsoft(R) Windows(R) 7 Ultimate (32bit)
Windows 7 x64 | Microsoft(R) Windows(R) 7 Professional (64bit)
Microsoft(R) Windows(R) 7 Enterprise (64bit)
Microsoft(R) Windows(R) 7 Ultimate (64bit)
Windows 8 | Windows 8 x86 | Windows(R) 8 Pro (32bit)
Windows(R) 8 Enterprise (32bit)
Windows 8 x64 | Windows(R) 8 Pro (64bit)
Windows(R) 8 Enterprise (64bit)

Restrictions

Information in this document is subject to change without notice and does not represent a commitment on the part of Hitachi. The software described in this manual is furnished according to a license agreement with Hitachi. The license agreement contains all of the terms and conditions governing your use of the software and documentation, including all warranty rights, limitations of liability, and disclaimers of warranty.
Material contained in this document may describe Hitachi products not available or features not available in your country.
No part of this material may be reproduced in any form or by any means without permission in writing from the publisher.
Printed in Japan.

Issued

Aug. 2013: 3020-3-Y22-10(E)

Copyright

All Rights Reserved. Copyright (C) 2013, Hitachi, Ltd.

Summary of amendments

The following table lists changes in the manual 3020-3-Y22-10(E) for uCosminexus Application Server 09-50, uCosminexus Application Server(64) 09-50, uCosminexus Client 09-50, uCosminexus Developer 09-50, uCosminexus Service Architect 09-50, uCosminexus Service Platform 09-50, uCosminexus Service Platform(64) 09-50 and the product changes related to the manual:

Changes
Location

The following OSs are added to the applicable OSs:

Microsoft(R) Windows Server(R) 2008 R2 Datacenter

Windows Server 2012

Windows 8

--

The functionality (Parser Switching functionality) was added so that you can switch the priority order of the XML implementation by XML Processor and the framework or user-specified XML implementation.
3.7

As the Compatibility Option functionality, functionality (functionality for validated parsing compatibility) was added so that you can switch the validated parsing-related 06-00 operations and 07-00 or later operations.
3.8

For methods that generate JAXP 1.4 factories, the restrictions on methods specifying factory names were removed.
6.1

A note related to the SAX parser was added.
6.3

A general XML Processor-related note was added.
6.21

A description was added for the differences in the XSLT operations.
Appendix A.5

A description was added for the operational differences of the Apache-specific functionality.
Appendix A.10

A description was added for the basic and application functionality of XML Processor and the know-how for efficiently using the functionality.
Appendix C

The coding of notes was moved from Release Notes.
1.3.1(1), 1.3.1(2)

In addition to the above changes, minor editorial corrections have been made.

Preface

For details on the prerequisites before reading this manual, see the manual uCosminexus Application Server Overview.

Non-supported functionality

Some functionality described in this manual is not supported. Non-supported functionality includes:

Audit log functionality

Compatibility functionality

Cosminexus Component Transaction Monitor

Cosminexus DABroker Library

Cosminexus Reliable Messaging

Cosminexus TPBroker and VisiBroker

Cosminexus Web Service - Security

Cosminexus XML Security - Core functionality

JP1 linkage functionality

Management portal functionality

Migration functionality

SOAP applications complying with specifications other than JAX-WS 2.1

uCosminexus OpenTP1 linkage functionality

Virtualized system functionality

XML Processor high-speed parse support functionality

Non-supported compatibility functionality

"Compatibility functionality" in the above list refers to the following functionality:

Basic mode

Check of JSP source compliance (cjjsp2java) with JSP1.1 and JSP1.2 specifications

Database connection using Cosminexus DABroker Library

EJB client application log subdirectory exclusive mode

J2EE application test functionality

Memory session failover functionality

Servlet engine mode

Simple Web server functionality

Switching multiple existing execution environments

Using EJB 2.1 and Servlet 2.4 annotation

1. An Overview of Cosminexus XML Processor

This chapter provides information you need to know before starting to use Cosminexus XML Processor, including the product's features, positioning, and supported features.

The range of supported features describes the available XML parser functions, XSLT transformer functions, JAXB data binding functions, and character codes that can be processed, and also introduces the extended functions of Cosminexus XML Processor.

Organization of this chapter

1.1 Product Features of Cosminexus XML Processor

1.2 Positioning of Cosminexus XML Processor

1.3 Range of Features Supported by Cosminexus XML Processor

1.1 Product Features of Cosminexus XML Processor

Cosminexus XML Processor is middleware that supports JAXP and JAXB, standard XML APIs for the Java language, and provides XML parser and XSLT transformer functions. Cosminexus XML Processor also provides the StAX streaming parser functionality and JAXB data binding functionality. The following subsections describe the product features of Cosminexus XML Processor.

Organization of this section

1.1.1 Enables Creation of Cross-platform Programs

1.1.2 Enables Easy Parsing of XML Documents Using Java Programs

1.1.3 Enables Easy Transformation of XML Documents Using Java Programs

1.1.4 Improves the ease in development of XML-based applications

1.1.1 Enables Creation of Cross-platform Programs

Cosminexus XML Processor supports JAXP and JAXB.

JAXP (Java API for XML Processing) is a standard XML API for the Java language defined in JSR 206 of JCP (Java Community Process). JAXP includes APIs that generate XML parsers (DOM and SAX parsers) and XSLT transformers.

JAXB (The Java Architecture for XML Binding) is a standard XML API defined in JSR 222 of Java Community Process. JAXB includes the schema compiler for converting from the XML Schema to Java, schema generator for converting from Java to the XML Schema, and APIs for exchanging data between XML documents and Java classes.

The standard XML APIs supported by Cosminexus XML Processor do not depend on implementation or coding of XML parsers, XSLT transformers, and JAXB data bindings. Therefore, Cosminexus XML Processor enables you to create cross-platform programs even if you are unaware of the implementation of the XML parser, XSLT transformer, and JAXB data binding used when you create a program that processes or performs operations on XML documents.

1.1.2 Enables Easy Parsing of XML Documents Using Java Programs

By providing a JAXP implementation, Cosminexus XML Processor enables Java programs to use XML parsers.

An XML parser is a library that parses XML documents and provides the parsed data to user programs in a manageable data structure. When you parse an XML document, tags and attributes in the document can also be validated for compliance with an XML Schema or DTD.

The following figure shows the process flow for parsing an XML document by using JAXP:

Figure 1-1 Flow of parsing XML documents in JAXP

By using JAXP, the Java program can generate an XML parser (SAX, StAX, or DOM parsers) for parsing XML documents.

1.1.3 Enables Easy Transformation of XML Documents Using Java Programs

By providing a JAXP implementation, Cosminexus XML Processor enables Java programs to use XSLT transformers.

XSLT is the specification for transforming one XML document structure into another. The product of an XSLT implementation is called an XSLT transformer. An XSLT transformer reads, processes, and outputs XML documents. An XSLT transformer outputs not only XML documents but also HTML documents and texts.

The following figure shows the process flow for transforming an XML document by using JAXP. By using JAXP, a Java program can perform operations on the XML document transformation of the XSLT transformer.

Figure 1-2 Flow of converting XML documents in JAXP

1.1.4 Improves the ease in development of XML-based applications

Cosminexus XML Processor provides the implementation of JAXB. When a schema document is input to the schema compiler, a Java class for accessing the XML document that is defined in the schema document is generated. If you use the created Java class, you can easily develop XML-based applications. The following figure shows the flow of processing XML using JAXB:

Figure 1-3 Flow of processing XML using JAXB (new development)

If the Java class is input to the schema generator, a schema document equivalent to the data structure of the Java class is generated. Therefore, you can easily build XML-based applications by leveraging the Java class that is an existing resource. The following figure shows the flow of building an XML-based application in an existing Java class by using JAXB:

Figure 1-4 Flow of processing XML using JAXB (leveraging an existing Java class)

1.2 Positioning of Cosminexus XML Processor

This section describes the positioning of Cosminexus XML Processor in the Cosminexus Version 9 environment.

Cosminexus XML Processor is used in any phase that requires parsing, such as analyses, operation, creation, and XSLT transformation of XML documents by using Cosminexus Version 9. Combined with other Cosminexus Version 9 products, Cosminexus XML Processor can configure an environment that enables the integration of XML-based applications currently in demand, such as a SOAP communication infrastructure.

The following figure shows the positioning of Cosminexus XML Processor in the Cosminexus execution environment:

Figure 1-5 Positioning of Cosminexus XML Processor in the Cosminexus execution environment

1.3 Range of Features Supported by Cosminexus XML Processor

This section describes the features supported by Cosminexus XML Processor.

Organization of this section

1.3.1 Available functions such as the XML Parser and XSLT Transformer

1.3.2 Character encodings that can be processed

1.3.3 Shift_JIS Switch Function

1.3.4 XSLTC Transformer Function

1.3.5 Schema cache functionality

1.3.6 High-speed parse support function

1.3.7 Apache-specific functions

1.3.1 Available functions such as the XML Parser and XSLT Transformer

Cosminexus XML Processor supports JAXP1.4 and JAXB2.2 specifications. You can use the XML parser and XSLT transformer functions available through JAXP within the specifications defined in JAXP as shown below.

Note

The JAXP versions have slightly different specifications. Similarly, note that JAXB 2.2 has slightly different specifications than its predecessor, JAXB 2.1.

For details about the support range of JAXB, see Appendix B Support Range of JAXB Specifications.

Organization of this subsection

(1) Specifications defined in JAXP

(2) Specifications defined in JAXB

(1) Specifications defined in JAXP

JSR 206 Java API for XML Processing (JAXP) 1.4
For details on how to use the APIs, see the following page:
http://docs.oracle.com/javase/6/docs/api/

Extensible Markup Language (XML)

Extensible Markup Language (XML) 1.1
http://www.w3.org/TR/xml11

XML 1.1 First Edition Specification Errata
http://www.w3.org/XML/xml-V11-1e-errata

Extensible Markup Language (XML) 1.0 (Third Edition)
http://www.w3.org/TR/2004/REC-xml-20040204/

Extensible Markup Language (XML) 1.0 (Third Edition) Errata
http://www.w3.org/XML/xml-V10-3e-errata

Namespaces in XML

Namespaces in XML 1.1
http://www.w3.org/TR/xml-names11/

Namespaces in XML 1.1 Errata
http://www.w3.org/XML/2004/xml-names11-errata

Namespaces in XML 1.0
http://www.w3.org/TR/REC-xml-names

Namespaces in XML 1.0 Errata
http://www.w3.org/XML/xml-names-19990114-errata

XML Schema

XML Schema Part 1: Structures Second Edition
http://www.w3.org/TR/xmlschema-1/

XML Schema Part 1: Structures Second Edition Errata
http://www.w3.org/2004/03/xmlschema-errata#Errata1

XML Schema Part 2: Datatypes Second Edition
http://www.w3.org/TR/xmlschema-2/

XML Schema Part 2: Datatypes Second Edition Errata
http://www.w3.org/2004/03/xmlschema-errata#Errata2

XSL Transformations (XSLT)

XSL Transformations (XSLT) Version 1.0
http://www.w3.org/TR/xslt

XSL Transformations (XSLT) Version 1.0 Errata
http://www.w3.org/1999/11/REC-xslt-19991116-errata

XML Path Language (XPath)

XML Path Language (XPath) Version 1.0
http://www.w3.org/TR/xpath

XML Path Language (XPath) Version 1.0 Errata
http://www.w3.org/1999/11/REC-xpath-19991116-errata

XML Inclusions (XInclude)

XML Inclusions (XInclude) Version 1.0
http://www.w3.org/TR/xinclude/

Document Object Model (DOM) Level 3

Document Object Model (DOM) Level 3 Core
http://www.w3.org/TR/DOM-Level-3-Core

Document Object Model (DOM) Level 3 Load and Save
http://www.w3.org/TR/DOM-Level-3-LS

Simple API for XML (SAX)

Simple API for XML (SAX) 2.0.2 (sax2r3)
http://sax.sourceforge.net/

Simple API for XML (SAX) 2.0.2 (sax2r3) Extensions
http://sax.sourceforge.net/?selected=ext

Streaming API for XML(StAX)

Streaming API for XML (StAX) Version 1.0
http://jcp.org/en/jsr/detail?id=173

(2) Specifications defined in JAXB

JSR 222 The JavaArchitecture for XML Binding 2.2
For details on how to use the APIs, see the following page:
http://jcp.org/aboutJava/communityprocess/mrel/jsr222/index2.html

1.3.2 Character encodings that can be processed

The character encoding for an XML document is specified in the encoding attribute (XXX in encoding="XXX") of the XML declaration in an XML document. The character encoding can also be specified as the encoding of the InputSource object that is used as the input source for the XML document.

Cosminexus XML Processor can process the following character encodings among those registered by IANA. For the definition of a character encoding, see the document regarding the IANA character sets.

UTF-8

UTF-16

UTF-16BE

UTF-16LE

Shift_JIS#1

Windows-31J

ISO-2022-JP

EUC-JP

US-ASCII

ISO-10646-UCS-2

ISO-10646-UCS-4#2

ISO-8859-1

#1

For details about switching character encoding (SJIS or MS932) applied when using Shift_JIS, see 1.3.3 Shift_JIS Switch Function.

#2

Only the formats with the byte order of big-endian or little-endian and with no Byte-Order-Marks added are supported.

Note

If any other character encoding is used, operation is not guaranteed.

1.3.3 Shift_JIS Switch Function

The Shift_JIS switch function changes the character encoding applied by Cosminexus XML Processor when the encoding attribute in the XML document is specified as Shift_JIS. Character encoding can be switched for each instance of the XML parser or XSLT transformer.

Character encoding specified for encoding of the XML document can be switched to SJIS (x-sjis-jdk1.1.7) or MS932 (x-sjis-cp932) according to the specification in the Shift_JIS switch function provided by Cosminexus XML Processor. For details about the correspondence between the XML encoding specification and the applied character encoding, see Table 3-1 in 3.1 Shift_JIS Switch Function.

For details about how to use the Shift_JIS switch function, see 3.1 Shift_JIS Switch Function.

1.3.4 XSLTC Transformer Function

The XSLTC transformer offers the same functionality as the XSLT transformer provided by Cosminexus XML Processor, with improved performance for XML document transformation. Cosminexus XML Processor enables you to develop applications that use both XSLT and XSLTC transformers.

For details about how to use the XSLTC transformer function, see 3.2.4 How to use the XSLTC Transformer.

1.3.5 Schema cache functionality

The schema cache functionality caches results (grammar objects) of parsing schema documents that are defined with an XML Schema, in the memory or on the disk beforehand. You can use the schema cache functionality to substitute a processing that converts schema documents to grammar objects with referencing the cache, for improving performance of validation.

You must code the schema documents to be cached using the setup file (schema definition file).

For details about how to use the schema cache functionality, see the section 3.3 Schema cache functionality.

1.3.6 High-speed parse support function

The high-speed parse support function improves the execution speed of the parsing process by studying the features of the XML document to be parsed through pre-parsing, and thereafter using the study results when parsing the XML document.

For details about how to use the high-speed parse support function, see 3.4 High-speed parse support function.

1.3.7 Apache-specific functions

In version 08-70 and later versions of Cosminexus XML Processor, you can use Apache-specific features, properties, and Namespace URI in addition to the JAXP standards. These specific functions can be used with XML parsers and XSLT or XSLTC transformers. However, operations are not guaranteed because these functions are not covered by the JAXP standards. Therefore, you need to take measures such as adequately checking operations beforehand.

For details on the Apache-specific functions, see 3.5 Apache-specific functions.

2. JAXP and JAXB Functionality

This chapter gives an overview of JAXP and JAXB. You will need to understand this overview if you wish to use JAXP and JAXB when creating programs.

Organization of this chapter

2.1 About JAXP

2.2 JAXP-defined Packages and Their Functionality

2.3 About JAXB

2.4 JAXB-defined Packages and Their Functionality

2.5 JAXB commands

2.1 About JAXP

JAXP (Java API for XML Processing) is a standard XML API for the Java language defined in JSR 206 of the Java Community Process.

The following table describes the JAXP functions that Cosminexus XML Processor supports.

Table 2-1 JAXP functions that Cosminexus XML Processor supports

Function | Overview
DOM | Analyze an XML document to generate a DOM tree. Also, manipulates the generated DOM tree.
SAX | Analyze an XML document to generate an SAX event. Also, handles the generated event.
StAX | Parses an XML document to generate a StAX event and also processes the generated event. Does not require a handler, and therefore can perform procedural processing of XML documents.
XSLT | Receives an XML document as input, transforms the document based on a stylesheet, and then outputs another XML document, an HTML document, or text.
XPath | Evaluates an XPath expression.
Validation | Validates an XML document based on the schema document.
Datatype | Processes the date and time format data defined in W3C XML Schema 1.0.

JAXP includes APIs that can generate DOM parsers, SAX parsers, StAX parsers, XSLT transformers, XPath objects, Validation objects, and Datatype objects. These APIs do not depend on the JAXP implementation. This frees you from needing to be aware of the implementation of the XML processor used when you create a program that handles and operates XML documents. Therefore, Cosminexus XML Processor enables you to create cross-platform programs.

2.2 JAXP-defined Packages and Their Functionality

JAXP defines packages for using the functions listed in Table 2-1 of 2.1 About JAXP. The following table gives an overview of APIs that are included in the packages defined in JAXP:

Table 2-2 An overview of APIs included in the packages defined in JAXP

Package | An overview of APIs included in the packages
javax.xml.parsers | APIs for performing parsing with a DOM parser and SAX parser.
javax.xml.stream | APIs for StAX parsing.
javax.xml.stream.events
javax.xml.stream.util
javax.xml.transform | APIs for XSLT transformers
javax.xml.transform.dom | APIs that use DOM for inputting to and outputting from XSLT transformers
javax.xml.transform.sax | APIs that use SAX for inputting to and outputting from XSLT transformers
javax.xml.transform.stax | APIs that use StAX for performing input and output from the XSLT transformers
javax.xml.transform.stream | APIs that use streams for inputting to and outputting from XSLT transformers.
javax.xml.validation | APIs for validating XML documents
javax.xml.xpath | APIs for evaluating XPath expressions
javax.xml.namespace | API for processing XML namespaces
javax.xml.datatype | APIs for processing the date and time format data defined in W3C XML Schema 1.0
javax.xml | Character-string constants related to XML
org.w3c.dom | APIs for manipulating DOM trees
org.w3c.dom.bootstrap | APIs for obtaining a DOM implementation
org.w3c.dom.ls | APIs for loading and saving XML documents
org.w3c.dom.events | APIs for handling DOM events
org.xml.sax | API for basic SAX processing
org.xml.sax.ext | APIs for extended SAX processing
org.xml.sax.helpers | Sets of helper classes for SAX processing

The following subsections give an overview of each package.

Organization of this section

2.2.1 javax.xml.parsers Package

2.2.2 javax.xml.stream Package

2.2.3 javax.xml.stream.events Package

2.2.4 javax.xml.stream.util Package

2.2.5 javax.xml.transform Package

2.2.6 javax.xml.transform.dom Package

2.2.7 javax.xml.transform.sax Package

2.2.8 javax.xml.transform.stax Package

2.2.9 javax.xml.transform.stream Package

2.2.10 javax.xml.validation Package

2.2.11 javax.xml.xpath Package

2.2.12 javax.xml.namespace Package

2.2.13 javax.xml.datatype Package

2.2.14 javax.xml Package

2.2.15 org.w3c.dom Package

2.2.16 org.w3c.dom.bootstrap Package

2.2.17 org.w3c.dom.ls Package

2.2.18 org.w3c.dom.events Package

2.2.19 org.xml.sax Package

2.2.20 org.xml.sax.ext Package

2.2.21 org.xml.sax.helpers Package

2.2.1 javax.xml.parsers Package

The javax.xml.parsers package provides APIs for parsing with a DOM parser and SAX parser.

Figures 2-1 and 2-2 show the flow of processing for applications that perform a DOM parse analysis and a SAX parse analysis respectively.

Figure 2-1 Flow of processing for applications that perform a DOM parse

Figure 2-2 Flow of processing for applications that perform a SAX parse

It is also possible to generate a SAX parser with the XMLReaderFactory class.

For details on the javax.xml.parsers package, see Chapter 7. Package javax.xml.parsers in the documentation for JSR 206 Java API for XML Processing (JAXP) 1.4.

For details on the coding samples that perform a DOM parse, see 5.4 Sample Program that Uses the DOM Parser. For details on the coding samples that perform a SAX parse, see 5.5 Sample Program that Uses the SAX Parser.

2.2.2 javax.xml.stream Package

The javax.xml.stream package provides APIs for StAX parsing.

For details on the javax.xml.stream package, see Javadoc in the JSR 206 Java API for XML Processing (JAXP) 1.4.

2.2.3 javax.xml.stream.events Package

The javax.xml.stream.events package provides APIs for processing the StAX events.

For details on the javax.xml.stream.events package, see Javadoc in the JSR 206 Java API for XML Processing (JAXP) 1.4.

2.2.4 javax.xml.stream.util Package

The javax.xml.stream.util package provides utility APIs for StAX processing.

For details on the javax.xml.stream.util package, see the Javadoc in the JSR 206 Java API for XML Processing (JAXP) 1.4.

2.2.5 javax.xml.transform Package

The javax.xml.transform package provides APIs for XSLT transformers.

The following figure shows the flow of processing for applications that perform XSLT-based transformation.

Figure 2-3 Flow of processing for applications that perform XSLT-based transformation

For details on the javax.xml.transform package, see Javadoc in the JSR 206 Java API for XML Processing (JAXP) 1.4.

For details on the coding samples for XSLT-based transformation, see 5.7 Sample Program that Uses the XSLT Transformer.

2.2.6 javax.xml.transform.dom Package

The javax.xml.transform.dom package provides APIs that use DOM for inputting to and outputting from XSLT transformers.

For details on the javax.xml.transform.dom package, see Javadoc in the JSR 206 Java API for XML Processing (JAXP) 1.4.

2.2.7 javax.xml.transform.sax Package

The javax.xml.transform.sax package provides APIs that use SAX for inputting to and outputting from XSLT transformers.

For details on the javax.xml.transform.sax package, see Javadoc in the JSR 206 Java API for XML Processing (JAXP) 1.4.

2.2.8 javax.xml.transform.stax Package

The javax.xml.transform.stax package provides APIs for using StAX for input and output of XSLT transformers.

For details on the javax.xml.transform.stax package, see Javadoc in the JSR 206 Java API for XML Processing (JAXP) 1.4.

2.2.9 javax.xml.transform.stream Package

The javax.xml.transform.stream package provides APIs that use stream for inputting to and outputting from XSLT transformers.

For details on the javax.xml.transform.stream package, see Javadoc in the JSR 206 Java API for XML Processing (JAXP) 1.4.

2.2.10 javax.xml.validation Package

The javax.xml.validation package provides APIs for validating XML documents.

The following figure shows the flow of processing for applications that validate XML documents by using a class included in the javax.xml.validation package.

Figure 2-4 Flow of processing for applications that validate XML documents by using a class included in the javax.xml.validation package

In addition, with a DOM parser, analysis and validation can be performed simultaneously. With a SAX parser, analysis and validation can also be performed simultaneously.

For details on the javax.xml.validation package, see Javadoc in the JSR 206 Java API for XML Processing (JAXP) 1.4.

2.2.11 javax.xml.xpath Package

The javax.xml.xpath package provides APIs for evaluating XPath expressions.

The following figure shows the flow of processing for applications that evaluate XPath expressions.

Figure 2-5 Flow of processing for applications that evaluate XPath expressions

It is also possible to evaluate XPath expressions by using an InputSource object as an input.

For details on the javax.xml.xpath package, see Javadoc in the JSR 206 Java API for XML Processing (JAXP) 1.4.

2.2.12 javax.xml.namespace Package

The javax.xml.namespace package provides APIs for processing XML namespaces. This package is only used as arguments or return values for APIs included in the javax.xml.xpath and javax.xml.datatype packages.

For details on the javax.xml.namespace package, see Javadoc in the JSR 206 Java API for XML Processing (JAXP) 1.4.

2.2.13 javax.xml.datatype Package

The javax.xml.datatype package provides APIs for processing date and time format data that is defined in W3C XML Schema 1.0.

The following figure shows the flow of processing for applications that process date and time format data.

Figure 2-6 Flow of processing for applications that process date and time format data

For details on the javax.xml.datatype package, see Javadoc in the JSR 206 Java API for XML Processing (JAXP) 1.4.

2.2.14 javax.xml Package

The javax.xml package defines the character-string constants related to XML.

For details on the javax.xml package, see Javadoc in the JSR 206 Java API for XML Processing (JAXP) 1.4.

2.2.15 org.w3c.dom Package

The org.w3c.dom package provides APIs for manipulating DOM trees.

The following figure shows the flow of processing for applications that manipulate DOM trees.

Figure 2-7 Flow of processing for applications that manipulate DOM trees

For details on the org.w3c.dom package, see the following sections in the documentation W3C Document Object Model (DOM) Level 3 Core Specification:

1.4 Fundamental Interfaces: Core Module

1.5 Extended Interfaces: XML Module

G: Java Language Binding G.2 Other Core interfaces

For details on a coding sample for manipulating DOM trees, see 5.4 Sample Program that Uses the DOM Parser.

2.2.16 org.w3c.dom.bootstrap Package

The org.w3c.dom.bootstrap package provides APIs for obtaining a DOM implementation.

For details on the org.w3c.dom.bootstrap package, see the following sections in the documentation W3C Document Object Model (DOM) Level 3 Core Specification:

1.3.7 Bootstrapping

G: Java Language Binding G.1 Java Binding Extension

2.2.17 org.w3c.dom.ls Package

The org.w3c.dom.ls package provides APIs for loading and saving XML documents.

The following figure shows the flow of processing for applications that load and save XML documents.

Figure 2-8 Flow of processing for applications that load and save XML documents

For details on the org.w3c.dom.ls package, see the following sections in the documentation W3C Document Object Model (DOM) Level 3 Load and Save Specification:

1.3 Fundamental Interfaces

B: Java Language Binding

2.2.18 org.w3c.dom.events Package

The org.w3c.dom.events package is used by asynchronous LSParser objects that implement the org.w3c.dom.ls.LSParser interface. This package is not used because Cosminexus XML Processor does not support asynchronous LSParser objects.

For details on the org.w3c.dom.events package, see the following sections in the documentation W3C Document Object Model (DOM) Level 3 Events Specification:

1.6 Basic interfaces

1.7 Event module definitions

D: Java Language Binding

2.2.19 org.xml.sax Package

The org.xml.sax package provides APIs for basic SAX processing.

The following figure shows the flow of processing for applications that handle SAX events.

Figure 2-9 Flow of processing for applications that handle SAX events

For details on the org.xml.sax package, see the Javadoc of Simple API for XML (SAX) 2.0.2 (sax2r3).

For a coding sample for handling SAX events, see 5.5 Sample Program that Uses the SAX Parser.

2.2.20 org.xml.sax.ext Package

The org.xml.sax.ext package provides APIs for extended SAX processing.

For details on the org.xml.sax.ext package, see the Javadoc of Simple API for XML (SAX) 2.0.2 (sax2r3) Extensions.

2.2.21 org.xml.sax.helpers Package

The org.xml.sax.helpers package provides a set of helper classes for SAX processing.

For details on the org.xml.sax.helpers package, see the Javadoc documentation for Simple API for XML (SAX) 2.0.2 (sax2r3) Extensions.

2.3 About JAXB

JAXB (The Java Architecture for XML Binding) is a standard XML API for the Java language defined in JSR 222 of Java Community Process.

For details on the JAXB functions provided by Cosminexus XML Processor, see Appendix B Support Range of JAXB Specifications.

JAXB contains APIs for generating Marshaller and Unmarshaller. These APIs do not depend on the implementation of JAXB. JAXB also contains a schema compiler and schema generator. The Java class and schema document generated by the schema compiler and schema generator are not dependent on the implementation of JAXB. Thus, you need not be aware of the implementation of the XML processor used, when creating a program for processing or operating an XML document. Therefore, cross-platform programs can be created.

2.4 JAXB-defined Packages and Their Functionality

JAXB provides the packages for using the functions. The following table gives an overview of APIs that are included in the packages defined in JAXB.

Table 2-3 Overview of APIs included in the packages defined in JAXB

Package | An overview of APIs included in the packages
javax.xml.bind | APIs for runtime binding frameworks, such as Marshal and Unmarshal.
javax.xml.bind.annotation | APIs for customizing the mapping from a Java class to a schema document.
javax.xml.bind.annotation.adapters | APIs for the adapter class used when any Java class is used in JAXB.
javax.xml.bind.attachment | APIs for performing Marshal and Unmarshal of the MIME-format binary data.
javax.xml.bind.util | APIs for the utilities of JAXB.

For details on the packages, see the Javadoc of JSR 222 The Java Architecture for XML Binding 2.2.

2.5 JAXB commands

Concrete usage methods of the schema compiler and schema generator are not provided in JSR 222. With Cosminexus XML Processor, you can use the schema compiler and schema generator by using the commands described in this section.

Symbols used for describing the command syntax
In this manual, the following symbols are used for coding the format of commands:

Symbol | Convention
[] | Items enclosed within this symbol may be omitted.
<> | Items enclosed within this symbol specify variable values such as a service location and file.

Characters that can be specified in the file name or directory name of the command, path delimiting characters, and how to specify a path
The rules for specifying the file name or the directory name of a command are as follows:

The characters that can be specified in the file name or directory name of a command are alphanumeric characters and the following symbols:
@ & = + $ , - _ . ! ~ ' ( )

The characters that you can use as path delimiting characters are as follows:
\ (In Windows)
/ (In UNIX)

Path can be specified either as an absolute path or as a relative path.

Commands provided with XML Processor
The following table describes the commands provided with Cosminexus XML Processor as the command line interfaces of the schema compiler and schema generator.

Table 2-4 List of commands

File name of command | Function
Windows | UNIX
csmxjc.bat | csmxjc | Schema compiler for binding from the XML Schema to Java.
csmschemagen.bat | csmschemagen | Schema generator for mapping from Java to the XML Schema.

Organization of this section

2.5.1 csmxjc command (Binding from the XML Schema to Java)

2.5.2 csmschemagen command (Mapping from Java to the XML Schema)

2.5.1 csmxjc command (Binding from the XML Schema to Java)

Organization of this subsection

(1) Format

(2) Function

(3) Options

(4) Input schema document

(5) Output Java source

(6) Return value

(1) Format

csmxjc [option [option argument] ] ... Input schema document

You can omit the option. Always specify the option before the schema document.

(2) Function

Schema compiler for binding from the XML Schema to Java.

(3) Options

-b external-binding-file

Specifies one external binding file. For details on how to specify names of the external binding files, see the subsection Characters that can be specified in the file name or directory name of the command, path delimiting characters, and how to specify a path.

If this option is omitted, a java class will be generated without using external binding files.

-d output-destination-directory

Specifies the output destination directory of the Java source. For details on how to specify the directory name, see Characters that can be specified in the file name or directory name of the command, path delimiting characters, and how to specify a path.

If omitted, the current directory will become the output destination directory.

-mark-generated

Adds the @javax.annotation.Generated annotation in the generated Java source.

If omitted, the @javax.annotation.Generated annotation is not added in the Java source.

The format of the @javax.annotation.Generated annotation added in the Java source is as follows. Different values are entered in the part indicated in italics, when the Java source is generated.

@Generated(value = "com.cosminexus.jaxb.tools.xjc.Driver", date = "yyyy-MM-ddTHH:mm:ssRFC822 timezone")

The following table describes the elements of the @javax.annotation.Generated annotation and the values set up in XML Processor:

Table 2-5 Elements of the @javax.annotation.Generated annotation and values set up in XML Processor

Element name | Explanation | Value
value | Completely modified class name of the schema compiler | com.cosminexus.jaxb.tools.xjc.Driver
date | Date and time when the Java source was generated from the schema | yyyy-MM-ddTHH:mm:ssRFC822 timezone#

#

For details on the output format, see the Date and time pattern of the java.text.SimpleDateFormat class.

(4) Input schema document

You can specify one file name for the input schema document. For details on the characters that can be specified in the file name, path delimiting characters, and how to specify a path, see Characters that can be specified in the file name or directory name of the command, path delimiting characters, and how to specify a path.

(5) Output Java source

Format of the output Java source

The following figure gives an overview of the format of Java source output by the schema compiler.

Figure 2-10 Overview of the format of Java source output by the schema compiler

The details of format of the output Java source are as follows:

Header
Header indicating that the file was generated by Cosminexus XML Processor. The following header is inserted:

//
// This file was generated by Cosminexus XML Processor 09-50
// Any modifications to this file will be lost upon recompilation of the source schema.
//

package statement and import statement code
The package statement and import statement required in the source is generated. The contents of the generated package statement or import statement depend on the schema document entered in the schema compiler.

javadoc
The contents of javadoc are generated automatically for the class generated from the input schema document. The contents of javadoc are dependent on the schema document entered in the schema compiler.

Java class
The class generated from the input schema document is generated. The contents of the Java class depend on the schema document entered in the schema compiler.

Package and output destination of the output Java source

The package name and output destination of the output Java source is as follows:

The package name of the output Java source is determined as per the following priority order. The output destination of the Java source is determined by assuming the current directory or the directory specified in the -d option as the standard directory, and applying the following rules in an order:

When the package name is specified by custom binding
The package name specified in custom binding (jaxb:package element) becomes the package name of the output Java source. Convert the package name to the directory name, and create the directory name under the standard directory. Output the Java source in the created directory.

When the targetNamespace attribute is specified in the input schema document
From the target namespace described in the input schema document, generate the package name of the output Java source based on the JAXB specifications. Convert the generated package name to the directory name, and create the directory name under the standard directory. Output the Java source in the created directory.

When the package name is not specified by custom binding in the input schema document, and when the targetNamespace attribute is also not specified
The package name of Java source will be generated. Create a directory called generated under the standard directory, and output the Java source in the created directory.

If a Java source with the same name exists in the output destination directory, then that Java source will be overwritten.

(6) Return value

0:

Normal termination.

Value other than 0:

Abnormal termination.

2.5.2 csmschemagen command (Mapping from Java to the XML Schema)

Organization of this subsection

(1) Format

(2) Function

(3) Options

(4) Input Java source

(5) Output schema document

(6) Intermediate file

(7) Return value

(8) Notes

(1) Format

csmschemagen [option [option argument] ] [package-info.java file name] Java source file name

You can omit the option and package-info.java file. Always specify the option and package-info.java before the Java source file name.

(2) Function

Schema generator for mapping from Java to the XML Schema.

(3) Options

-d output-destination-directory

Specifies the output destination directory of the output schema document and intermediate file. For details on how to specify the output destination directory name, see Characters that can be specified in the file name or directory name of the command, path delimiting characters, and how to specify a path.

If omitted, the current directory will become the output destination directory.

-encoding character-encoding

Specifies the character encoding of the Java source to be input.

For character encoding that can be specified in Cosminexus XML Processor, see 1.3.2 Character encodings that can be processed.

If omitted, depending on the OS in use, the operations will differ as follows:

In Windows

The default character encoding for the OS is applied.

In UNIX

The character encoding specified in the environment variable LANG is applied. Even if the environment variable LANG is not specified, the default character encoding for the OS is applied.

(4) Input Java source

You can specify one Java source file. For details on the characters that can be specified in the file name, path delimiting characters, and how to specify a path, see Characters that can be specified in the file name or directory name of the command, path delimiting characters, and how to specify a path.

(5) Output schema document

Output as file name scheman.xsd (n is a numeric character) in the current directory or directory specified in the -d option. If a file with the same name exists in the output destination directory, then that file will be overwritten.

(6) Intermediate file

The csmschemagen command is used to compile the Java source file, and generate the .class file that is the intermediate file.

If the Java source file contains the package statement, create a subdirectory under the output destination directory, and then output the .class file. The subdirectory name is determined based on the package name specified in the package statement.

If the Java source file does not contain the package statement, output the .class file immediately under the output destination directory.

The output destination directory of the .class file can be changed with the -d option.

(7) Return value

0:

Normal termination.

Value other than 0:

Abnormal termination.

(8) Notes

Even if the Java source file input in the csmschemagen command is invalid in terms of the syntax, the schema document will be output. Do not use the schema document that is output because the schema document might be invalid in terms of the syntax.

3. Extended Functions of Cosminexus XML Processor

This chapter describes the extended functions of Cosminexus XML Processor.

For a description of messages output in Cosminexus XML Processor, see 11. KECX (Messages Output by Cosminexus XML Processor) in the manual uCosminexus Application Server Messages.

Organization of this chapter

3.1 Shift_JIS Switch Function

3.2 XSLTC Transformer Function

3.3 Schema cache functionality

3.4 High-speed parse support function

3.5 Apache-specific functions

3.6 Correspondence Between Error Messages in XML Schema and W3C Specifications

3.7 Parser Switching functionality

3.8 Compatibility option functionality

3.1 Shift_JIS Switch Function

The Shift_JIS switch function changes the character encoding applied by Cosminexus XML Processor to SJIS (x-sjis-jdk1.1.7) or MS932 (x-sjis-cp932) when the encoding attribute in the XML document specifies Shift_JIS. The following table lists the correspondence between the encoding specifications for an XML document and the applicable character encodings.

Table 3-1 Correspondence between the encoding specifications for an XML document and the applicable character encodings

Specified XML document encoding | Shift_JIS switch function setting | Applicable character encoding
Shift_JIS | Not specified | SJIS (default)
SJIS | SJIS
MS932 | MS932
Windows-31J | -- | MS932

Legend:

--: Cannot be specified

The Shift_JIS switch function is specified by setting a certain property to the instance of the XML parser or XSLT transformer. For details about how to set properties, see 4.5 How to use the properties of the Shift_JIS switch function.

The encoding specification using the Shift_JIS switch function is applied to the following items. The encoding cannot be applied to other items.

encoding attribute of an input XML document

Encoding specified for the InputSource object

The output character stream when Shift_JIS is specified with the encoding attribute of the xsl:output element in the stylesheet or the setOutputProperty and setOutputProperties methods of the javax.xml.transform.Transformer class.

Care is required in the following cases:

When the InputSource object is specified as the InputSource for DOM and SAX parsers:
The Shift_JIS switch function is disabled if encoding other than Shift_JIS is specified for the InputSource object. In addition, when Reader is specified for the InputSource object, the Shift_JIS switch function is also disabled and the encoding being used by the Reader is applied.

When the StreamSource object is specified as the input source for the XSLT or XSLTC transformer:
When Reader is specified for the StreamSource object, the Shift_JIS switch function is disabled and the encoding being used by the Reader is applied.

When the DOMSource object is specified as the input source for the XSLT or XSLTC transformer:
The XML document has already undergone character code conversion when the DOMSource was generated. The Shift_JIS switch function is therefore disabled.
To enable the Shift_JIS switch function, you need to specify the Shift_JIS switch function in advance so the parser is used for generating the DOM node for the DOMSource.

When the SAXSource object is specified as the input source for the XSLT or XSLTC transformer:
If the InputSource object is specified for the SAXSource object, caution must be exercised for case 1 above. If the XMLReader object is specified for the SAXSource object, the Shift_JIS switch function specified in XMLReader is valid.

The JAXB does not support the Shift_JIS switch functionality when the Node, Source, or Result that is created either by the DOM parser or SAX parser where the Shift_JIS switch functionality is specified, is passed as an argument of the APIs of JAXB.

StAX does not support the Shift_JIS switch functionality. Therefore, for input and output of XSLT or the XSLTC transformer, if anyone of the following is used, the operation will not be guaranteed:

StAXSource

StAXResult

3.2 XSLTC Transformer Function

This section describes the XSLTC transformer function.

Organization of this section

3.2.1 An Overview of XSLTC Transformer

3.2.2 XSLTC Transformer-based System Development and Operation

3.2.3 Class Used by the XSLTC Transformer

3.2.4 How to use the XSLTC Transformer

3.2.1 An Overview of XSLTC Transformer

The XSLTC transformer offers the same functionality as the XSLT transformer provided by Cosminexus XML Processor, with improved performance for XML document transformation.

The XSLTC transformer consists of the compiler that parses each XSLT stylesheet and the runtime processor that performs transformation. The compiler parses an XSLT stylesheet and generates the Java bytecode, called a translet, into memory for faster transformation. The runtime processor achieves high-speed transformation by executing the translet.

Note that the XSLTC transformer operates differently from the XSLT transformer in the following ways:

For the XSLTC transformer, the error check function is more simplified than that of the XSLT transformer.

Operations might differ between the XSLT transformer and the XSLTC transformer in the parts that are not defined in the XSLT1.0 specification.

You can expect higher transformation performance by using the XSLTC transformer instead of the XSLT transformer in the following cases:

Organization of this subsection

(1) Transforming multiple XML documents by using the same XSLT stylesheet

(1) Transforming multiple XML documents by using the same XSLT stylesheet

When you transform multiple XML documents by using the same XSLT stylesheet, you can expect higher transformation performance from approach 2 (below) than approach 1, both for the XSLT and XSLTC transformers:

Generate the Templates and Transformer objects from the stylesheet every time and use the objects for each subsequent transformation.

Generate the Templates and Transformer objects from the stylesheet once only and reuse the objects for each subsequent transformation.

When using approach 2 for the XSLTC transformer, the time-consuming translet creation is needed only once. The translet is then repeatedly used to execute subsequent transformations at a faster speed. For this reason, higher performance is expected when using approach 2 for the XSLT transformer.

3.2.2 XSLTC Transformer-based System Development and Operation

The error check for the XSLTC transformer is not as strict as that for the XSLT transformer. When you develop and operate a system that uses the XSLTC transformer, perform the operation checks with the XSLT transformer as follows:

Make sure that error checking for the stylesheets is performed by using the XSLT transformer. This check can locate errors that cannot be detected by the XSLTC transformer, enabling you to find differences in error checks that might occur when interoperating with other systems.

Hitachi recommends that you verify the result of the transformation by using the XSLTC transformer is same as that by using the XSLT transformer. This validation enables you to understand whether the transformer-specific operation affects the result of the transformation and to find the differences in error checks that might occur when interoperating with other systems.

See the following cautionary notes on XSLT and XSLTC transformers:

6.6 General Notes on XSLT and XSLTC

6.7 Notes on XSLT

6.8 Notes on XSLTC

3.2.3 Class Used by the XSLTC Transformer

The TransformerFactoryXSLTC class is used in the XSLTC transformer.

This section describes the classes used by XSLTC transformer.

Organization of this subsection

(1) TransformerFactoryXSLTC class

(1) TransformerFactoryXSLTC class

(a) Description

This class creates the TransformerFactory instance for the XSLTC transformer.

(b) Package and class names

com.cosminexus.jaxp.xsltc.TransformerFactoryXSLTC

(c) Format

public class TransformerFactoryXSLTC

(d) List of methods

Method name | Function
newInstance | Creates new instances of TransformerFactory

(e) Method details

newInstance method

Description

This method creates a new TransformerFactory instance for the XSLTC transformer.

Format

public static TransformerFactory newInstance()

Parameters

None

Return value

This method returns the new instance of TransformerFactory.

Exception

None

3.2.4 How to use the XSLTC Transformer

When you use the XSLTC transformer, the TransformerFactory instance is generated in a different manner than the XSLT transformer. The TransformerFactory instance in the XSLTC transformer is generated by the following:

Other usage is the same as the XSLT transformer.

The follow shows an example of the coding:

3.3 Schema cache functionality

This subsection describes the schema cache functionality.

Organization of this section

3.3.1 Overview of the schema cache functionality

3.3.2 Processing of the schema cache functionality

3.3.3 Setting up the schema cache

3.3.4 Using the schema cache

3.3.5 Deleting and resetting the schema cache

3.3.6 About using the most appropriate schema cache

3.3.1 Overview of the schema cache functionality

The schema cache functionality caches, in an object state, the syntax definitions that an XML parser acquires when parsing schema documents, and enables the re-use of the cached syntax definitions during schema validation to improve the speed of validation parsing.

With the schema cache functionality, you can create a cache in the memory and on a disk. Also, you can use a program in which APIs of JAXP1.2 are used to improve the execution speed of validation parsing without modifying the source.

This subsection describes the prerequisites and scope for using the schema cache functionality.

Organization of this subsection

(1) Prerequisite conditions

(2) Scope

(1) Prerequisite conditions

The schema cache functionality is enabled only when a user program that runs on a J2EE server uses the javax.xml.parsers.DocumentBuilder class (DOM parse) to parse XML documents.

The following are the restrictions when using the schema cache functionality:

When you use Application Server in the servlet engine mode, the operation of the schema cache functionality is not guaranteed.

The schema cache functionality is not applicable to the schema validation using the javax.xml.validation package.

When passing the File object to an argument of the parse method, some part of the name of the schema document file that is maintained within the parse will not be in conformity with the name of the file that is created while setting up a cache. Therefore, you cannot use the schema cache functionality.

(2) Scope

The following schema documents will be cached:

Schema documents specified in the schema definition file

Schema documents are referenced directly or indirectly from the schema documents that are defined in the schema definition file, with the following elements:

import element

include element

redefine element

Note that when starting multiple J2EE servers on one machine, the schema cache functionality operates independently on every J2EE server.

3.3.2 Processing of the schema cache functionality

The schema cache functionality includes the following for operating a schema cache:

Setting up a schema cache

Using the schema cache

Deleting and resetting up the schema cache

The following figure shows the processing of the schema cache functionality.

Figure 3-1 Processing of the schema cache functionality

Conventional schema validation parses a schema document during validation and creates grammar objects even when the same schema is used for each validation; however, if you use the schema cache functionality, already existing grammar objects are reused to reduce the overhead of schema document parsing.

The following figure shows an example where one schema document is used to validate multiple instance documents. The example shows the differences in the process when using the schema cache functionality with a cache and when using the conventional process scheme validation without a cache:

Figure 3-2 Difference in the process of schema validation using the schema cache functionality and the process of past schema validation

3.3.3 Setting up the schema cache

To use the schema cache functionality, you must decide a schema document for cache in advance and set up a schema cache. Therefore, set up the following property file appropriately:

Schema definition file

User-defined file (usrconf.properties) of the J2EE server

The above mentioned file corresponds to the Java property file. Therefore, for basic syntax rules, follow the rules used in the Java property file. Note that for details about the syntax rules of the property files, see Javadoc of the java.util.Properties class.

This subsection described the property files.

Organization of this subsection

(1) Schema definition file

(2) J2EE server user-defined file

(1) Schema definition file

You can define the following items in a schema definition file:

Schema document to cache

Cache format

Location on a disk in which the schema cache is saved

You can specify any file name and save location for the schema definition file.

The following schema documents will be cached:

Schema documents directly specified in the schema definition file

Schema documents that are referenced directly or indirectly from the schema documents that are defined directly in the schema definition file, with the following elements:

import element

include element

redefine element

The following table lists the properties that you can code in a schema definition file. If you specify any other property, that property will be ignored.

Table 3-2 Properties that can be coded in a schema definition file

No.
Property name
Specified value

1
schema_path
Specifies an absolute path that indicates a directory where the schema document exists.

2
diskcache_path
Specifies an absolute path that indicates a directory where the disk cache is saved.

3
schema_xxx
(xxx is any character string that has more than one character)
Specifies a relative path that indicates a file of the schema document to be cached and the disk cache specifier. You can omit the disk cache specifier.
For the disk cache specifier, code D at the end of the relative path of the schema document. The schema document cache specified by the disk cache specifier is created on the disk.
If there is no coding of the disk cache specifier, a cache is created in the memory.
A space or a tab that is connected to the file name and the disk cache will be ignored.

Use a slash (/) as a delimiter in a path specified for each property, in Windows and UNIX. Using a slash (/) at the end of an absolute path for the directory name is optional.

If the same property name is specified more than once, the last specified value of the property will be valid.

The following are the examples of schema definition files:

In Windows

shema_path=C:/usr/app/xmlparser/schemafiles
diskcache_path=C:/usr/app/xmlparser
schema_01=schema/type1.xsd
schema_02=schema/type2.xsd,D

In UNIX

shema_path=/usr/app/xmlparser/schemafiles
diskcache_path=/usr/app/xmlparser
schema_01=schema/type1.xsd
schema_02=schema/type2.xsd,D

When schema_01=schema/type1.xsd is specified, the disk cache specifier has not been coded, so cache of the schema document will be performed in the memory.

When schema_02=schema/type2.xsd,D is specified, the disk cache specifier has been coded, and therefore, the schema document is cached on the disk.

The following are the operations for specifying the schema definition files:

You must specify the schema_path property and the diskcache_path property.
If any one of the above two properties is not specified, a warning message (KECX09503-W) indicating that the required property is not specified will output to an error file, and schema validation is executed without using the schema cache.

Even if the same directory is specified in the diskcache_path property on multiple J2EE servers, the disk cache is managed independently on each server.
A directory having the name same as that of the J2EE server is created in the directory specified in the diskcache_path property, and a cache file is created in the directory. When the disk cache is deleted, the cache file for each created subdirectory will be deleted.

When the specified of the diskcache_path property is not an absolute path, the warning message (KECX09507-W) is output to an error file, and schema validation is executed without using the schema cache.

When you cannot access to a directory that is specified in the diskcache_path property, the warning message (KECX09505-W) indicating that the directory for saving the disk cache cannot be accessed will output to an error file, and schema validation is executed without using the schema cache.

When the specified value of the schema_path property is not an absolute path, the warning message (KECX09508-W) is output to the error file, and schema validation is executed without using the schema cache.

When the specified value of the schema_xxx property is not a relative path, the warning message (KECX09509-W) is output to an error file, and the specification of the schema_xxx property will be ignored.

When an attempt to write grammar objects in a file fails while creating a disk cache, the warning message (KECX09511-W) is output to an error file. A parser validates the schema using the schema document and not the cache for which an attempt to write the grammar objects has failed.

When the same schema document is specified with multiple schema_xxx properties, only one cache corresponding to the schema document is created. In such cases, if the disk cache specifier is specified to any of the properties among all the properties, a cache will be created on the disk. If the disk cache specifier is not specified to any of the properties, the cache will be created in the memory.

For details about the precautions related to the schema definition files, see the subsection 6.18.3 Precautions related to schema definition files.

(2) J2EE server user-defined file

The user-defined file (usrconf.properties) of the J2EE server defines a class, to be initialized when the J2EE server starts, and a system property to be set up.

For details about the user-defined files of J2EE servers, see 2. Files Used on J2EE Servers in the uCosminexus Application Server Definition Reference Guide.

The following table lists the properties coded in the user-defined file of the J2EE server, when the schema cache functionality is used.

Table 3-3 Properties coded in the user-defined file of the J2EE server

No.
Property name
Specified value

1
ejbserver.application.InitTermProcessClasses
Specifies the initialization and termination class of the J2EE extended container.
Specify com.cosminexus.jaxp.impl.parsers.util.XMLGrammarCaching that is required to set up a schema cache, using the schema cache functionality.

2
com.cosminexus.jaxp.grammar_caching.preload
Specifies whether to use the schema cache functionality or not. You can specify either ON or OFF. The default value is OFF.
If you specify ON, the schema cache functionality can be used. The XML parser executes the schema validation using the schema cache.
If you specify OFF, the schema cache functionality cannot be used. The XML parser executes the schema validation without using the schema cache.
Note that this property controls all the schema cache functionality. You must specify ON to use the schema cache functionality for J2EE server. If you specify OFF, the schema cache functionality will not be enabled after the J2EE server starts.

3
com.cosminexus.jaxp.grammar_caching.config
Specifies an absolute path of the schema definition file.

You can use the schema cache functionality only when corresponding to all the following conditions:

Specifies the ejbserver.application.InitTermProcessClasses property.

Specifies ON in the com.cosminexus.jaxp.grammar_caching.preload property.

Specifies the com.cosminexus.jaxp.grammar_caching.config property.

The following is an example of the user-defined files for J2EE servers:

# Specifies the class to be initialized when Cosminexus starts
ejbserver.application.InitTermProcessClasses=com.cosminexus.jaxp.impl.parsers.util.XMLGrammarCaching
# Enables the cache functionality
com.cosminexus.jaxp.grammar_caching.preload=ON
# Absolute path of schema definition file defined in the schema document to be maintained in the cache
com.cosminexus.jaxp.grammar_caching.config=C:/usr/app/xmlparser/config.properties

The following are the operations for specifying the user-defined files for J2EE servers:

When the following value is specified in the com.cosminexus.jaxp.grammar_caching.preload property, OFF must be specified:

A value other than ON or OFF is specified

A property is not specified

When you cannot access the schema definition file specified in the com.cosminexus.jaxp.grammar_caching.config property, even if ON is specified in the com.cosminexus.jaxp.grammar_caching.preload property, you cannot use the schema cache functionality (warning message KECX09504-W)

3.3.4 Using the schema cache

When using the XML parser to execute the schema validation, the operations of the user for using the schema cache functionality are not required. The XML parser decides whether to use the schema cache functionality or not, and when using the schema cache functionality, the schema validation is executed automatically using the schema cache. When the schema cache is not used or when the cache is not found, schema validation is executed after creating grammar objects same as is done in the past XML parser.

Note that when a failure occurs while reading the grammar objects from the disk cache file, a warning message (KECX09512-W) is output. The XML parser does not use a cache that could not be read, so the schema validation is executed using the schema document.

With the schema cache functionality, you can use the following commands to control a cache or to check status:

Table 3-4 Schema cache functionality commands

No. | File name of the command | Functionality
Windows | UNIX
1 | cacheoff.bat | cacheoff | Disables the schema cache functionality, and deletes the cache.
2 | cacheon.bat | cacheon | Enables the schema cache functionality, and reset up the cache.
3 | cachestate.bat | cachestate | Displays status of the schema cache functionality.

All the command files are saved in the bin directory below JAXP_DIR#. To use the commands, you must set up the bin directory below JAXP_DIR# with the PATH environment variable.

#

This is the jaxp directory in the directory where Cosminexus is installed.

For details about the commands, see the subsection 3.3.5 Deleting and resetting the schema cache.

3.3.5 Deleting and resetting the schema cache

For deleting or changing schema documents to be cached, you must use commands to delete or reset up the cache. You can use the commands to apply the changes of the schema document in the cache without stopping the J2EE server.

For details about the precautions to be taken when deleting and resetting up the cache, see the subsection 6.18.4 Precautions related to reset up and deletion of a cache.

This subsection describes the commands to be executed while deleting and resetting up the cache:

Organization of this subsection

(1) cacheoff command (deleting cache with XML parser)

(2) cacheon command (cache resetting with XML parser)

(3) cachestate command (display the cache functionality status)

(4) Relation of the synchronous processing of each command and parsing

(1) cacheoff command (deleting cache with XML parser)

(a) Format

cacheoff J2EE server name

(b) Operation while executing the cacheoff command

The following are the operations when using the cacheoff command. Note that if the schema cache functionality is disabled, no operation will be performed even when using the cacheoff command.

When you execute the cacheoff command, the XML parser releases all the cache from the memory, and deletes the directories having the same name as the J2EE server in the directory specified in diskcache_path of the schema definition file, and all the disk cache created below the directory.

The schema cache functionality is disabled after the cacheoff command is executed, and the XML parser executes the schema validation without using the cache.

The cacheoff command instructs the deletion of the cache in the XML parser, but does not directly delete the cache. The cache is deleted, when the DOM parse is passed for the first time, after the cacheoff command is executed.

When using the cacheoff command, the directory "directory or server name specified in diskcache_path" is displayed, and the user is requested to confirm the deletion. Even when the cache is not created on the disk, and only the directory to save the disk cache is to be created, the user will be requested to confirm the deletion.

An error message (KECX09506-E) is output in the standard error output, when using the cacheoff command, and an internal directory and the internal files are not accessible due to the abnormalities in the system, and the command process is interrupted.

The error message (KECX09510-E) is output, when you specify the J2EE server name that does not exist in the argument of the cacheoff command.

The error message (KECX09510-E) is output when ON is not specified in the com.cosminexus.jaxp.grammar_caching.preload property of the user-defined file of the J2EE server, and the cacheoff command is used for the J2EE server.

When there is a mistake in the argument of the command, the following error message is output and the process is interrupted:

KECX09513-E cacheoff : Invalid parameter.
usage : cacheoff J2EE_server_name

(2) cacheon command (cache resetting with XML parser)

(a) Format

cacheon J2EE server name

(b) Operation when executing the cacheon command

The following are the operations, when using the cacheon command:

When using the cacheon command, the XML parser releases the cache from the memory and deletes the directories having the name same as that of the J2EE server in the directory specified in diskcache_path of the schema definition file, and all the disk cache created below the directory. Consequently, the cache is set up again according to the contents of the schema definition file.

The schema cache functionality is enabled after using the cacheon command, and the XML parser executes the schema validation using the cache.

The cacheon command instructs the reset up of cache with the XML parser, but does not directly delete or reset up the cache. The cache is deleted or reset up when the XML parse is passed for the first time, after using the cacheon command.

When using the cacheon command, an internal directory and the internal files are not accessible because of the abnormalities in the system, the error message (KECX09506-E) is output in the standard error output, and the command process is interrupted.

When you specify the J2EE server name that does not exist in the argument of the cacheon command, the error message (KECX09510-E) is output.

When ON is not specified in the com.cosminexus.jaxp.grammar_caching.preload property of the user-defined file of the J2EE server, and the cacheon command is executed for that J2EE server, the error message (KECX09510-E) is output.

When there is a mistake in the argument of the command, the following error message is output and the process is interrupted:

KECX09513-E cacheon : Invalid parameter.
usage : cacheon J2EE_server_name

(3) cachestate command (display the cache functionality status)

(a) Format

cachestate [-d] [J2EE server name]

(b) Operation when executing the cachestate command

The following are the operations when using the cachestate command:

If the cachestate command is executed without the -d option, the status of the schema cache functionality is output in the standard output. The following table describes the displayed contents:

Table 3-5 Status of the schema cache functionality to be displayed

No. | Status of schema cache functionality | Content displayed
1 | Enabled | "KECX09501-I J2EE Server 'J2EE server name': schema cache: ON"
2 | Disabled | "KECX09501-I J2EE Server 'J2EE server name': schema cache: OFF"

When the cachestate command is executed, and an internal directory and internal files are not accessible because of the abnormalities in the system, the error message (KECX09506-E) is output in the standard error output, and the command process is interrupted.

When you specify a J2EE server name that does not exist in the argument of the cachestate command, the error message (KECX09510-E) is output.

When J2EE server name of the argument of the cachestate command is omitted, the information of all the J2EE servers is output.

In the user-defined file of the J2EE server, information is output, if ON is not specified in the com.cosminexus.jaxp.grammar_caching.preload property, no information will be output, even when you specify the -d option in the cachestate command and execute the command.

When there is a mistake in the argument of the command, the following error message is output, and the process is interrupted:

KECX09513-E cachestate : Invalid parameter.
usage : cachestate [-d] [J2EE_server_name]

If the -d option is specified in the cachestate command and the command is executed, the following information is displayed in the standard output:

Schema cache functionality status (ON or OFF)

The current valid schema definition file

The current valid diskcache_path (directory where the disk cache is created)

Start and end time of the cache setup

Cache setup status of the schema document

Error information during the cache setup

The following figure shows the output format of the information.

Figure 3-3 Output format when executing the cachestate command

When you do not specify the server name, only the information about the number of servers will output. Even if the error KECX09506-E occurs during the execution, the information of the remaining servers will output. The content of this information is cleared whenever the cache is reset and updated.

(4) Relation of the synchronous processing of each command and parsing

The following table describes the relation of the synchronous processing of the cacheon command, cacheoff command, cachestate command, and the parsing.

Table 3-6 Relation of the synchronous processing of each command and parsing

No.
Action to be executed
System status

Other than when parsing and the cases mentioned at the right side
When setting up cache
When deleting cache

1
Parsing
Start parsing
(start the process immediately).
Start parsing after the setup is complete.
Start parsing after completing the deletion.

2
cacheon command
Executed in the following order:

Immediately end the command. However, the schema cache setup is not executed at that time.

Start the next parsing.

Setup cache.

3
cacheoff command
Execute in the following order:

Immediately end the command. However, schema cache is not deleted at that time.

Start the next parse.

Delete cache.

4
cachestate command
Display the following information:

When the schema cache functionality is enabled:

"KECX09501-I J2EE Server 'J2EE server name': schema cache: ON"

When the schema cache functionality is disabled:

"KECX09501-I J2EE Server 'J2EE server name': schema cache: OFF"

"KECX09501-I J2EE Server 'J2EE server name': schema cache: displays OFF".

3.3.6 About using the most appropriate schema cache

When you use the schema cache functionality, you can reduce the parsing time for validation. However, the problems such as increase in the memory usage or when the disk cache is used, the expected effects might not output.

This subsection describes how to avoid such problems and use the appropriate schema cache.

Organization of this subsection

(1) Relation of the size and the validation time of schema and instance document

(2) Difference between memory cache and disk cache

(3) Precautions when using the memory cache

(1) Relation of the size and the validation time of schema and instance document

A schema document is coded with XML. The parsing is performed before the validation check, and converted to internal grammar objects. Using cache, you can omit the processing of setting the grammar objects from the schema document. The following time is required for parsing the validation check:

validation-time-of-the-instance-document + time-for-setting-grammar-objects-from-schema-document

The time required for setting grammar objects can be omitted from the cache, so the effect of the schema cache as displayed in the first condition will be more in the following conditions:

size-of-the-schema-document > size-of-the-instance-document

size-of-the-schema-document < size-of-the-instance-document

(2) Difference between memory cache and disk cache

When using the schema cache functionality, grammar objects are set up from the schema document in advance, so you can omit the time required for setting the grammar objects during the validation.

However, when the memory and the disk cache are used, the time required for parsing the validation check is as follows:

Memory cache
For parsing the validation check, the time taken for validating the instance document is required.

Disk cache
The following time is required for parsing the validation check:
validation-time-of-the-instance-document + deserialize#-time + I/O-time

#

The processing that converts the data in such a way (serialized) so that the file with all the Java objects can be saved with the format of the original object.

(3) Precautions when using the memory cache

When using the memory cache, after a cache is setup, the cache remains in the memory. Therefore, adjust the memory usage within the permitted range of resources. It is effective to select a schema document that is frequently used, and then using the memory cache with the priority.

3.4 High-speed parse support function

This section describes the high-speed parse support function.

Organization of this section

3.4.1 Overview of the high-speed parse support function

3.4.2 Flow of operations for high-speed parse

3.4.3 Creating the Pre-Parse XML document

3.4.4 Generating the preparsed object

3.4.5 Setting up the preparsed object

3.4.6 Parsing the XML document

3.4.7 Classes used in preparing the high-speed parse support function

3.4.8 Coding example for using the high-speed parse support function

3.4.9 Tuning the Pre-Parse XML document

3.4.10 Details of the tuning summary file

3.4.11 Details of the tuning details file

3.4.1 Overview of the high-speed parse support function

The high-speed parse support function improves the execution speed of the parsing by studying the features of the XML document to be parsed through pre-parsing, and thereafter using the study results when parsing the XML document. The high-speed parse support function is suitable for systems that perform iterative parsing of XML documents in which the structural features such as order of elements and attributes or embedded relations are same. The following figure shows a system in which the high-speed parse support function is used:

Figure 3-4 System in which the high-speed parse support function is used

The features of the XML document studied through pre-parsing are recorded in the preparsed object. The following figure shows the flow of generating the preparsed object and implementing high-speed parse.

Figure 3-5 Flow of generating the preparsed object and implementing high-speed parse

Generating the preparsed object
The Preparsed object is generated by performing preparse of information, such as the order of elements, the order of attributes, and the iteration of elements from the Pre-Parse XML document, in Cosminexus XML Processor. The Pre-Parse XML document is an XML document with the same structural features as the XML document for parsing.
The Pre-Parse XML document must be created by the user. As an XML document generally has a free structure, a preparsed object corresponding to all XML documents cannot be generated. Therefore, the Pre-Parse XML document is created by concentrating on the document structure with high occurrence frequency, and after considering the XML documents for parsing.

Using the preparsed object (implementing high-speed parse)
The XML document is parsed using the preparsed object when parsing with the XML parser function of Cosminexus XML Processor in which the preparsed object is set up. The parsing speed will improve if the structure of the XML document for parsing matches with the structure of the document recorded in the preparsed object.

When using the high-speed parse support function as per the flow shown in Figure 3-5, you must describe the codes for generating the preparsed object and setting it up in an XML parser, in the user program. For details about how to use the high-speed parse support function by describing the codes in the user program, see 3.4.2 Flow of operations for high-speed parse.

However, Hitachi does not guarantee that the parse speed can be improved than that of the normal speed in all cases. Therefore, when using the high-speed parse support function, Hitachi recommends that you evaluate the performance by actually using the XML document for parsing.

When using the high speed parse support function, check the contents of 6.19 Notes on the high-speed parse support function as well.

Reference note

About the amount of the parsing time that can be reduced using the high-speed parse support function

The high-speed parse support function reduces the parsing time in the SAX parser. Furthermore, as parsing with a DOM parser is implemented by parsing with the SAX parser and generation of a DOM tree, the parsing time of the DOM parser can also be reduced. However, the time for generating the DOM tree does not change even after using the high-speed parse support function. Therefore, as shown in the following figure, in comparison to parse with SAX parser, the amount of the reduced time as against the entire parsing time is less.

Also, when the validation check is performed, the amount of parsing time for the validation check process is high, and therefore, the amount of the reduced parsing time will be relatively less. Particularly, when the validation process is executed without using the javax.xml.validation.Schema class, the parsing time is hardly reduced.

Even for parsing a small-size XML document, the amount of initialization time of the XML parser in the entire parsing time is high, and therefore, the amount of the reduced parsing time will be relatively lesser.

3.4.2 Flow of operations for high-speed parse

This subsection describes the flow of operations executed by the users when the high-speed parse support function is executed by describing the code in the user program.

Figure 3-6 Flow of operations for using the high-speed parse support function

Each operation is as follows:

Creating a Pre-Parse XML document
Create the Pre-Parse XML document considering the structural features of the XML document for parsing. For details about the policies for creating the Pre-Parse XML document, see 3.4.3 Creating the Pre-Parse XML document.

Generating a preparsed object
Parse the Pre-Parse XML document, and then generate the preparsed object. For details about how to generate the preparsed object, see 3.4.4 Generating the preparsed object.

Setting up the preparsed object
Set up the preparsed object in an XML parser of Cosminexus XML Processor. For details about how to set up the preparsed object, see 3.4.5 Setting up the preparsed object.

Parsing the XML document
Parse the XML document by the parse method of the XML parser in which the preparsed object is set up. For details about the parse methods for high-speed parse support function, see 3.4.6 Parsing the XML document.

Tuning the Pre-Parse XML document
Tune the Pre-Parse XML document as and when required. The parsing speed can be improved furthermore by optimizing the Pre-Parse XML document after examining the tuning information. For details about how to tune the Pre-Parse XML document, see 3.4.9 Tuning the Pre-Parse XML document.

For details about coding examples to be described in the user program for using the high-speed parse support function, see 3.4.8 Coding example for using the high-speed parse support function.

3.4.3 Creating the Pre-Parse XML document

Create the Pre-Parse XML document considering the structural features of the XML document for parsing. Create a Pre-Parse XML document as per the following policies:

Table 3-7 Policies for creating a Pre-Parse XML document

No. | Applicable location | Policy
1 | XML declaration | Must match with the XML document for parsing.
2 | Elements and attributes | Describe the elements and attributes described in the XML document for parsing.
3 | Order of elements and attributes | Must match with the XML document for parsing.
4 | Embedded structure of elements | Must match with the XML document for parsing.
5 | Iteration structure of elements | Code the iterative elements in an iterative format.
6 | Text, CDATA sections, and attribute values | Need not match with the XML document for parsing.
7 | DTDs, comments, and processing instructions | Need not be coded.

Each of these policies is described as follows by citing specific coding example:

Organization of this subsection

(1) XML declaration

(2) Elements and attributes

(3) Order of elements and attributes

(4) Embedded structure of elements

(5) Iteration structure of elements

(6) Text, CDATA sections, and attribute values

(7) DTDs, comments, and processing instructions

(1) XML declaration

The XML declaration of the XML document for parsing is coded as it is in the Pre-Parse XML document. The following figure shows an example:

Figure 3-7 Example for describing XML declaration (policy for creating a Pre-Parse XML document)

(2) Elements and attributes

The elements and attributes of the XML document for parsing are coded in the Pre-Parse XML document. The information about the elements and attributes described in the Pre-Parse XML document is recorded in the preparsed object that is generated.

If there are different elements and attributes in the XML documents for parsing, then code all those elements and attributes in the Pre-Parse XML document. The following figure shows an example:

Figure 3-8 Example of coding of elements and attributes (policy for creating a Pre-Parse XML document)

However, the text in the elements, CDATA sections, and the contents of the attribute values need not match the XML document for parsing. For details, see 3.4.3 (6) Text, CDATA sections, and attribute values.

The following codes are not differentiated according to XML standards, but are differentiated when pre-parsing as different elements:

Blank elements and blank element tags (example: <a></a> and <a/>)

Elements with different number and position of linefeed characters, space characters, or tags

If these elements exist in the XML document for parsing, they must be differentiated and coded in the Pre-Parse XML document. The following figure shows an example:

Figure 3-9 Example of coding of blank elements and blank element tags (policy for creating the Pre-Parse XML document)

Figure 3-10 Example of coding elements with different number and position of linefeed characters or blank characters (policy for creating the Pre-Parse XML document)

(3) Order of elements and attributes

The elements and attributes of the XML document for parsing are coded in the same order in the Pre-Parse XML document. The following figure shows an example:

Figure 3-11 Example of describing elements and attributes (policy for creating the Pre-Parse XML document, and order of elements and attributes)

If elements and attributes with the same combination but different order are described in the XML document for parsing, all such elements and attributes will be described in the Pre-Parse XML document. The following figure shows an example:

Figure 3-12 Example of describing attributes with the same combination but different order (policy for creating the Pre-Parse XML document)

(4) Embedded structure of elements

The embedded structure of elements in the XML document for parsing is described in the same format in the Pre-Parse XML document. The following figure shows an example:

Figure 3-13 Example of describing the embedded structure of elements (Policy for creating the Pre-Parse XML document)

If there are many different embedded structures in the XML document for parsing, all embedded structures will be coded in the Pre-Parse XML document. The following figure shows an example:

Figure 3-14 Example of coding multiple embedded structures of elements (policy for creating the Pre-Parse XML document)

(5) Iteration structure of elements

If the XML document for parsing contains iterative elements, the iterative elements are described in continuation for two or more times in the Pre-Parse XML document. The elements described continuously for two or more times are treated as iterative elements when parsing. If the frequency of continuous description in the pre-parsing XML document is two or more times, there would be no impact on the performance of the high-speed parse support function even if the iteration frequency differs from that of the XML document for parsing. The following figure shows an example:

Figure 3-15 Example of coding the iteration structure of elements (Policy for creating the Pre-Parse XML document)

(6) Text, CDATA sections, and attribute values

The text, CDATA sections, and contents of the attribute values described in the Pre-Parse XML document do not have an impact on the preparsed object that is generated. Therefore, the text, CDATA sections, and contents of the attribute values in the Pre-Parse XML document need not match with the XML document for parsing.

Also, the text and CDATA sections are not differentiated (the preparsed object is same no matter which one is coded). The following figure shows an example:

Figure 3-16 Example of coding the text, CDATA sections, and attribute values (policy for creating the Pre-Parse XML document)

Elements with contents (example: <a>12</a>) and empty elements (example: <a></a>) are differentiated. Furthermore, as the linefeed, tab, and space are considered as text, the elements containing such text (example: <a>[linefeed]</a>) and empty elements (example: <a></a>) are differentiated. Therefore, if the XML document for parsing contains such elements, all elements must be differentiated and described in the Pre-Parse XML document. The following figure shows an example:

Figure 3-17 Example of coding of empty elements (policy for creating the Pre-Parse XML document)

(7) DTDs, comments, and processing instructions

The DTDs, comments, and processing instructions are not included in the preparsed object. Therefore, these might not be described in the Pre-Parse XML document (even if these are described, they will not have an impact on the preparsed object that will be generated). The following figure shows an example:

Figure 3-18 Example related to DTDs, comments, and processing instructions (policy for creating the Pre-Parse XML document)

However, the DTDs that define the entities referenced from within the XML document for parsing must be described in the Pre-Parse XML document. Following figure shows an example:

Figure 3-19 Example of coding the definition of entities referenced from within the XML document (policy for creating the Pre-Parse XML document)

3.4.4 Generating the preparsed object

Parse the Pre-Parse XML document and generate the PreparsedObject instance that is the preparsed object.

To generate the preparsed object (PreparsedObject instance), use the following methods:

newInstance method of the com.cosminexus.jaxp.preparsedxml.PreparsedObjectFactory class

newPreparsedObject method of the com.cosminexus.jaxp.preparsedxml.PreparsedObject class

For details about the methods, see 3.4.7 Classes used in preparing the high-speed parse support function.

An example of code for generating the preparsed object is as follows:

// Prepare the Pre-Parse XML document
File xml = new File("learning1.xml");
// Prepare the entity resolver
MyEntityResolver entityResolver = new MyEntityResolver();
// Prepare the error handler
MyErrorHandler errorHandler = new MyErrorHandler();
// Generate PreparsedObjectFactory
PreparsedObjectFactory pof = PreparsedObjectFactory.newInstance();
// Enable the namespace
pof.setNamespaceAware(true);
// Set up the entity resolver
pof.setEntityResolver(entityResolver);
// Set up the error handler
pof.setErrorHandler(errorHandler);
// Generate the preparsed object
PreparsedObject pobj = pof.newPreparsedObject(xml);

3.4.5 Setting up the preparsed object

Set up the preparsed object in an XML parser of Cosminexus XML Processor. The preparsed object can be set up in the following XML parsers:

javax.xml.parsers.DocumentBuilder

javax.xml.parsers.SAXParser

org.xml.sax.XMLReader

To set up the preparsed object in an XML parser, use the http://cosminexus.com/xml/properties/preparsedobject-load property. For details about the property, see 4.6 How to use the properties of the high-speed parse support function.

3.4.6 Parsing the XML document

Parsing the XML document by the parse method of XML parser in which the preparsed object is set up. The following table describes the parse methods for high-speed parse support function:

Note

The operation is not guaranteed if the high-speed parse support function is used with a parse method that is not mentioned in the table.

Table 3-8 Parse methods with which the high-speed parse support function is used

Class name | Method name
javax.xml.parsers.DocumentBuilder | parse(File f)
parse(InputSource is)
parse(InputStream is)
parse(InputStream is, String systemId)
parse(String uri)
javax.xml.parsers.SAXParser | parse(File f, DefaultHandler dh)
parse(InputSource is, DefaultHandler dh)
parse(InputStream is, DefaultHandler dh)
parse(InputStream is, DefaultHandler dh, String systemId)
parse(String uri, DefaultHandler dh)
org.xml.sax.XMLReader | parse(InputSource input)
parse(String systemId)

3.4.7 Classes used in preparing the high-speed parse support function

Use the following classes while preparing the high-speed parse support function:

PreparsedObjectFactory

PreparsedObject

Each class is as follows:

Organization of this subsection

(1) PreparsedObjectFactory class

(2) PreparsedObject class

(1) PreparsedObjectFactory class

(a) Description

Factory class used to generate the preparsed object.

The PreparsedObjectFactory class is not thread safe. Therefore, the same PreparsedObjectFactory cannot be accessed simultaneously from more than one thread. To avoid conflicts between threads, use one of the following methods in PreparsedObjectFactory class:

Each thread has one PreparsedObjectFactory instance.

Each thread exclusively accesses the PreparsedObjectFactory instance.

(b) Package and class names

com.cosminexus.jaxp.preparsedxml.PreparsedObjectFactory

(c) Format

public class PreparsedObjectFactory

(d) List of methods

Method name | Function
newInstance | Generate and return the factory for generating the preparsed object.
setNamespaceAware | Set up whether the namespace is enabled or disabled when the Pre-Parse XML document is parsed.
setErrorHandler | Set up the error handler for receiving the errors that occur when parsing the Pre-Parse XML document.
setEntityResolver | Set up the entity resolver for resolving the entities included in the Pre-Parse XML document.
setTuningInfoFlag | Set up whether to output the tuning information.
newPreparsedObject | Parse the Pre-Parse XML document, and then generate the preparsed object.

(e) Method details

newInstance method

Description

Generates and returns the factory for generating the preparsed object.

Format

public static PreparsedObjectFactory newInstance()

Parameter

None

Return value

This method returns the new instance of PreparsedObjectFactory.

Exception

None

setNamespaceAware method

Description

Sets up whether the namespace is enabled or disabled when the Pre-Parse XML document is parsed.

By default, false is set up.

Format

public void setNamespaceAware(boolean awareness)

Parameter

awareness
Sets up whether the namespace is enabled or disabled.
true: The namespace is enabled
false: The namespace is disabled

Return value

None

Exception

None

setErrorHandler method

Description

Sets up the error handler for receiving the errors that occur when parsing the Pre-Parse XML document when the newPreparsedObject method is invoked.

By default, the operation is performed considering that the following error handler is set up:

class DefaultErrorHandler implements ErrorHandler {
public void fatalError(SAXParseException e) throws SAXException {
 throw e;
}
public void error(SAXParseException e) throws SAXException {
 throw e;
}
public void warning(SAXParseException e) throws SAXException {
 // No operations
}
}

Format

public void setErrorHandler(org.xml.sax.ErrorHandler errorHandler)

Parameter

errorHandler
Sets up the error handler. When null is set up, the default operation is performed.

Return value

None

Exception

None

setEntityResolver method

Description

Sets up the entity resolver for resolving the entities included in the Pre-Parse XML document when the newPreparsedObject method is invoked.

By default, the operation is performed considering that the following entity resolver is set up:

class DefaultEntityResolver implements EntityResolver {
InputSource resolveEntity(String publicId, String systemId)
throws SAXException, IOException {
 returns null; // Always returns null
}
}

Format

public void setEntityResolver(org.xml.sax.EntityResolver entityResolver)

Parameter

entityResolver
Sets up the entity resolver. When null, the default operation is performed.

Return value

None

Exception

None

setTuningInfoFlag method

Description

Sets up whether to output the tuning information.

By default, false is set.

To output the tuning information, you must set true in this method, and INFO in the system property com.cosminexus.jaxp.preparsedxml.tuning.level. For details about how to output the tuning information, see 3.4.9(3) How to output the tuning information.

Format

public void setTuningInfoFlag(boolean state)

Parameter

state
Sets up whether to output the tuning information.
true: The tuning information is output
false: The tuning information is not output

Return value

None

Exception

None

newPreparsedObject method

Description

Parse the Pre-Parse XML document, and generates the preparsed object.

Format

public PreparsedObject newPreparsedObject(java.io.File xml)

throws IllegalArgumentException, SAXException, IOException

Parameter

xml
Specifies the File object that indicates the Pre-Parse XML document. You cannot specify null.

Return value

This method returns the new instance of PreparsedObject that is the preparsed object.

Exception

IllegalArgumentException
This exception occurs when null is specified in the xml parameter.

SAXException
This exception occurs in the following cases:
- When an SAX error occurs while processing
- When an attempt is made to pre-parse XML1.1 document (for details, see 6.19.3 Notes on XML1.1)

IOException
This exception occurs when an I/O error occurs.

(2) PreparsedObject class

(a) Description

This class indicates the preparsed object.

(b) Package and class names

com.cosminexus.jaxp.preparsedxml.PreparsedObject

(c) Format

public class PreparsedObject

(d) List of methods

Method name | Function
isNamespaceAware | Returns whether the namespace set up when parsing the Pre-Parse XML document is enabled or disabled.
getErrorHandler | Returns the error handler set up when parsing the Pre-Parse XML document.
getEntityResolver | Returns the entity resolver set up when parsing the Pre-Parse XML document.

(e) Method details

isNamespaceAware method

Description

Returns whether the namespace set up when parsing the Pre-Parse XML document is enabled or disabled.

Format

public boolean isNamespaceAware()

Parameter

None

Return value

true: The namespace is enabled

false: The namespace is disabled

Exception

None

getErrorHandler method

Description

Returns the error handler set up when parsing the Pre-Parse XML document.

Format

public ErrorHandler getErrorHandler()

Parameter

None

Return value

This method returns the error handler set up when parsing the Pre-Parse XML document. Returns null if this method is not set up.

Exception

None

getEntityResolver method

Description

Returns the entity resolver set up when parsing the Pre-Parse XML document.

Format

public EntityResolver getEntityResolver()

Parameter

None

Return value

This method returns the entity resolver set up when parsing the Pre-Parse XML document. Returns null if this method is not set up.

Exception

None

3.4.8 Coding example for using the high-speed parse support function

An example of code described in the user program for using the high-speed parse support function is as follows:

import java.io.File;
import java.io.IOException;
import javax.xml.parsers.SAXParserFactory;
import javax.xml.parsers.SAXParser;
import org.xml.sax.EntityResolver;
import org.xml.sax.ErrorHandler;
import org.xml.sax.SAXException;
import org.xml.sax.helpers.DefaultHandler;
import com.cosminexus.jaxp.preparsedxml.PreparsedObjectFactory;
import com.cosminexus.jaxp.preparsedxml.PreparsedObject;

public class TestSAXParser{
public static void main(String[] args){
try{
 // Generate the preparsed object from the Pre-Parse XML document
 File xml = new File("learning1.xml");
 MyHandler handler = new MyHandler ();
 PreparsedObjectFactory pof = PreparsedObjectFactory.newInstance();
 pof.setNamespaceAware(true);
 pof.setEntityResolver(handler);
 pof.setErrorHandler(handler);
 PreparsedObject pobj = pof.newPreparsedObject(xml);

 // Generate the XML parser
 SAXParserFactory spf = SAXParserFactory.newInstance();
 spf.setNamespaceAware(true);
 SAXParser sp = spf.newSAXParser();

 // Set up the preparsed object in the XML parser, and parse
 sp.setProperty("http://cosminexus.com/xml/properties/preparsedobject-load", pobj);
 sp.parse("SampleSAX.xml", handler);
} catch(IllegalArgumentException iae){
 System.out.println("MSG : " + iae.getMessage());
}catch(SAXException se){
 System.out.println("MSG : " + se.getMessage());
}catch(IOException ioe){
 System.out.println("MSG : " + ioe.getMessage());
}catch(Exception e){
 e.printStackTrace();
}
}
}

class MyHandler extends DefaultHandler {
//Describe the implementation of the error handler and entity resolver
}

3.4.9 Tuning the Pre-Parse XML document

If you reference the tuning information of the Pre-Parse XML document, you can examine whether the high-speed parse support function is running effectively. The parsing speed can be improved by optimizing the Pre-Parse XML document based on the examination results.

This subsection describes the types of the tuning information of Pre-Parse XML document, and also describes how to use and output the information.

Organization of this subsection

(1) Types of tuning information

(2) How to use the tuning information

(3) How to output the tuning information

(1) Types of tuning information

The following two types of files can be output as the tuning information:

Tuning summary file

Tuning details file

The information about the matching process when parsing is output to these files. The matching process is used to determine whether you can use the information about the preparsed object when parsing. The cases where you can use the information about the preparsed object are referred to as successful in matching process, while the cases where you cannot use the information about the preparsed object are referred to as failed matching process.

Each file is as follows:

(a) Tuning summary file

The success rate of the matching process, file names of the Pre-Parse XML document used to generate the preparsed object, system identifier of the XML document for parsing and tuning details file name is output for each parsing in which the high-speed parse support function is used. You can examine the extent of effective usage of the preparsed object in parsing with the high-speed parse support function.

For details about the tuning summary file, see 3.4.10 Details of the tuning summary file.

(b) Tuning details file

Besides the information about the tuning summary file, the history of the matching process is output for a single parsing in which the high-speed parse support function is used. For the parsing executed using the high-speed parse support function, you can examine the details of the location where the matching process has failed.

For details about the tuning details file, see 3.4.11 Details of the tuning details file.

(2) How to use the tuning information

The details on how to use the tuning information is as follows:

Output the tuning information.
For details about how to output the tuning information, see 3.4.9 (3) How to output the tuning information.

Reference the tuning summary file, and extract the parsing with a low success rate in matching process.
A low success rate of the matching process indicates that there is a vast difference between the structure of the Pre-Parse XML document, which is studied by the preparsed object, and the structure of the XML document for parsing, and the high-speed parse support function is not operating effectively.

Reference the tuning details file for each parsing extracted in step 2, and examine the history of the locations at which the matching process has failed.
Examine the history of the locations where the matching process has failed, and extract the parts where the structure of the Pre-Parse XML document does not match the structure of the XML document for parsing.

Revise the Pre-Parse XML document.
Revise the Pre-Parse XML document based on the examination results of step 3. For details about the policy for creating the Pre-Parse XML document, see 3.4.3 Creating the Pre-Parse XML document.

Note

If the success rate of the matching process is low the effect of the high-speed parse support function will reduce, even if all elements and attributes described in the XML document for parsing are included in the Pre-Parse XML document.

An example when the success rate of the matching process is low even if all elements and attributes described in the XML document for parsing are included in the Pre-Parse XML document is as follows.

In this example, as the remark element is omitted in the XML document for parsing, the matching process for the remark element would fail, and the failure history will be recorded in the tuning details file. As a result, the success rate of the matching process will decline.

(3) How to output the tuning information

To output the tuning information, you must set up the system property provided by Cosminexus XML Processor. To output the tuning information with high-speed parse using PreparsedObject, besides the setup of the system property, you must set up true in the setTuningInfoFlag method of the PreparsedObjectFactory class, and then generate PreparsedObject. For details about the PreparsedObjectFactory class, see 3.4.7(1) PreparsedObjectFactory class.

The system property used to output the tuning information, the output destination of the tuning information, and the operation when an error occurs is as follows.

Note

The parsing performance deteriorates when the tuning information is output. Therefore, output the tuning information only when evaluating the performance of the high-speed parse support function.

(a) System property used to output the tuning information

System property name

com.cosminexus.jaxp.preparsedxml.tuning.level

Value

When OFF or when this property is not set up: The tuning information is not output

INFO: The tuning information is output

Assumed that OFF is specified when other than INFO in upper case is specified.

(b) Output destination of the tuning information

The tuning information is output when parsing with the high-speed parse support function terminates. The output destination of the tuning information is determined in the following order:

Server-log-output-directory#/jaxp
#: The server-log-output-directory differs depending on the server in use.

For the J2EE server

The directory specified in the ejb.server.log.directory key of the option definition file (usrconf.cfg) of J2EE server. By default, it is the following directory:

Cosminexus-work-directory/ejb/server-name/logs

For the Web container server

The directory specified in the web.server.log.directory key of the option definition file (usrconf.cfg) of Web container server. By default, it is the following directory:

Cosminexus-installation-directory/CC/web/containers/server-name/logs

Directory-that-can-be-acquired-with-the-user.dir-system-property/logs/jaxp

A file with the same name will be overwritten. If a file with the same name exists, save that file, as and when required. For details about the rules for file names, see 3.4.10(1) File name (tuning summary file) and 3.4.11(1) File name (tuning details file).

The tuning summary file and tuning details file are not deleted automatically. Delete these files as and when required. For details about the upper-limit value of the file size of the tuning summary file, see 3.4.10(3) Upper-limit value of the file size. For details about the upper-limit value of the total file size of tuning details file, see 3.4.11(3) Upper-limit value of the total file size.

(c) Operation when an error occurs

The operation performed when the tuning information cannot be output for occurrence of an error is as follows:

When an I/O error occurs

If an I/O error occurs during the output of the tuning summary file and tuning details file, these files will not be output. Also, the exception IOException occurs.

When an error occurs when parsing the XML document

The information will not be output to the tuning summary file. The information until the occurrence of the error will be output to the tuning details file.

3.4.10 Details of the tuning summary file

This subsection describes the file name, output format, and upper-limit of the file size of the tuning summary file.

Organization of this subsection

(1) File name (tuning summary file)

(2) Output format (tuning summary file)

(3) Upper-limit value of the file size

(1) File name (tuning summary file)

csmjaxp_ppxml_summary.csv

(2) Output format (tuning summary file)

Output line
Output contents

First line
Header indicating the tuning summary file

Cosminexus XML Processor Fast Parse Function Tuning Summary Information

Second line
Week, date and time on which the tuning summary file was created

Third line
Line header from the fourth line onwards

matching rate,preparsed XML,parsed XML,tuning detail file,date

Fourth line and thereafter
The following information is demarcated by a comma and output:

Success rate of the matching process
Success frequency matching process execution frequency 100

pre-parse XML file name #

System identifier of the XML document for parsing#
If the system identifier is not set up, null will be output.

File name of the tuning details file#

Date and time of completion of parsing

#

Even if commas (,) are included in the output character string, they will be output as it is.

Output example

(3) Upper-limit value of the file size

1 MB#

#

If the file size exceeds 1MB, the data thereafter will not be added.

Note that you can change the upper-limit value of the file size with the following system property:

System property name

com.cosminexus.jaxp.preparsedxml.tuning.summaryfile_maxsize

Value

Specify an integer value of 0 or more. The unit is MB.

If this property is not set up, and if a value out of range is specified, 1 will be set up.

3.4.11 Details of the tuning details file

This subsection describes the file name, output format, and upper-limit of the file size of the tuning details file.

Organization of this subsection

(1) File name (tuning details file)

(2) Output format (tuning details file)

(3) Upper-limit value of the total file size

(1) File name (tuning details file)

csmjaxp_ppxml_{character string indicating the Pre-Parse XML document}_{character string indicating the Pre-Parse XML document}_{serial number}.txt

Character string indicating the Pre-Parse XML document

Indicates the character string obtained from the end part of the absolute path of Pre-Parse XML document and excluding the part after the last period (.).

Example: When the absolute path of the Pre-Parse XML document is D:\home\xml\training\tr1.xml

The character string indicating the Pre-Parse XML document will be tr1.

Character string indicating the XML document for parsing

Indicates the character string obtained from the end part of the system identifier of XML document for parsing and excluding the part after the last period (.).

Example: When the system ID of the XML document for parsing is file:/home/xml/data/novelA.xml

The character string indicating the XML document for parsing will be novelA.

Serial number

Serial number from 00 to 99. This number increases with each parsing.

Note that this number will be reset to 00 when the J2EE server or Web container is restarted. After 99 it would be reset to 00.

(2) Output format (tuning details file)

Output line
Output contents

First line
Header indicating the tuning details file

Cosminexus XML Processor Fast Parse Function Tuning Detail Information

Second line
Date and time when the tuning details file was created

Third line
File name of the Pre-Parse XML document

Fourth line
System identifier of the XML document for parsing
If the system identifier is not set up, null will be output.

Fifth line
Header indicating the start of the matching information

Matching Information start

Sixth line and thereafter
Matching information (history of the matching process)

When the matching process is successful

o:{element or attribute for which the matching process was executed}#

When the matching process fails

x: expected {pattern where matching was tried}# but {pattern that appears in the XML document for parsing}#

Second from the last line
Footer indicating the end of the matching information

Matching Information end

Last line
Success rate of the matching process
Success frequency matching process execution frequency 100 (%)
However, if the matching process is not executed even once, 0.0% will be output

#

Only a part of the element or attribute is output. The characters before and after the element or attribute are also output. For a specific example, see the output example:

Output example

(3) Upper-limit value of the total file size

32 MB#

#

If the total file size of the output tuning details files exceeds 32 MB, no more tuning detail files will be generated thereafter.

For example, if the tuning detail files are generated in the following order of 1 to 5, and if the total file size of 1 to 4 files while the 4th file is being generated becomes 40 MB, which is greater than 32 MB, the fifth file will not be generated.

csmjaxp_ppxml_trl_novelistA_00.txt (10MB)

csmjaxp_ppxml_trl_novelistB_00.txt (10MB)

csmjaxp_ppxml_trl_novelistC_00.txt (10MB)

csmjaxp_ppxml_trl_novelistD_00.txt (10MB)

csmjaxp_ppxml_trl_novelistE_00.txt (10MB)

Note that the upper-limit value of the total file size can be changed by the following system property.

System property name

com.cosminexus.jaxp.preparsedxml.tuning.detailfile_totalmaxsize

Value

Specify an integer value as 0 or more. The unit is MB.

If this property is not set up, and if a value out of range is specified, 32 will be set up.

3.5 Apache-specific functions

In version 08-70 and later versions of Cosminexus XML Processor, you can set up Apache-specific features and properties corresponding to XML parsers and XSLT or XSLTC transformers. You can also use Apache-specific Namespace URIs.

This section introduces Apache-specific features, properties, and Namespace URIs that can be used. For details on the respective functions, see the Apache sites for Xerces2 Java and Xalan Java 2.

Note

The functions described in this section are specific to Apache and are not covered by the JAXP standards. Therefore, the operations performed by using these functions are not guaranteed. To use these functions, you must adequately check the operations beforehand.

Organization of this section

3.5.1 Features that can be set up

3.5.2 Properties that can be set up

3.5.3 Namespace URIs that can be set up

3.5.1 Features that can be set up

The Apache-specific features that can be specified in XML parsers are as follows:

http://apache.org/xml/features/allow-java-encodings

http://apache.org/xml/features/continue-after-fatal-error

http://apache.org/xml/features/disallow-doctype-decl

http://apache.org/xml/features/dom/create-entity-ref-nodes

http://apache.org/xml/features/dom/defer-node-expansion

http://apache.org/xml/features/dom/include-ignorable-whitespace

http://apache.org/xml/features/generate-synthetic-annotations

http://apache.org/xml/features/honour-all-schemaLocations

http://apache.org/xml/features/nonvalidating/load-dtd-grammar

http://apache.org/xml/features/nonvalidating/load-external-dtd

http://apache.org/xml/features/scanner/notify-builtin-refs

http://apache.org/xml/features/scanner/notify-char-refs

http://apache.org/xml/features/standard-uri-conformant

http://apache.org/xml/features/validate-annotations

http://apache.org/xml/features/validation/dynamic

http://apache.org/xml/features/validation/schema

http://apache.org/xml/features/validation/schema/augment-psvi

http://apache.org/xml/features/validation/schema/element-default

http://apache.org/xml/features/validation/schema/normalized-value

http://apache.org/xml/features/validation/schema-full-checking

http://apache.org/xml/features/validation/warn-on-duplicate-attdef

http://apache.org/xml/features/validation/warn-on-undeclared-elemdef

http://apache.org/xml/features/warn-on-duplicate-entitydef

http://apache.org/xml/features/xinclude

http://apache.org/xml/features/xinclude/fixup-base-uris

http://apache.org/xml/features/xinclude/fixup-language

The Apache-specific features that can be specified in XSLT or XSLTC transformers are as follows:

http://xml.apache.org/xalan/features/incremental

http://xml.apache.org/xalan/features/optimize

3.5.2 Properties that can be set up

The Apache-specific properties that can be specified in XML parsers are as follows:

http://apache.org/xml/properties/dom/current-element-node

http://apache.org/xml/properties/dom/document-class-name

http://apache.org/xml/properties/input-buffer-size

http://apache.org/xml/properties/schema/external-noNamespaceSchemaLocation

http://apache.org/xml/properties/schema/external-schemaLocation

http://apache.org/xml/properties/security-manager

The Apache-specific properties that can be specified in XSLT or XSLTC transformers are as follows:

http://xml.apache.org/xalan/properties/source-location

3.5.3 Namespace URIs that can be set up

The Apache-specific Namespace URIs that can be used in XSLT or XSLTC transformers are as follows:

http://xml.apache.org/xalan

http://xml.apache.org/xalan/java

http://xml.apache.org/xalan/PipeDocument

http://xml.apache.org/xalan/redirect

http://xml.apache.org/xalan/sql

http://xml.apache.org/xalan/xsltc

http://xml.apache.org/xalan/xsltc/java

http://xml.apache.org/xslt

http://xml.apache.org/xslt/java

3.6 Correspondence Between Error Messages in XML Schema and W3C Specifications

Each error message output by Cosminexus XML Processor is provided with an identifier to identify the associated W3C specification. This is to provide consistent error information for the syntax error in the schema documents and the validation error in XML documents.

The list of error message identifiers is found in Part1: Structure Appendices C of the W3C XML Schema specification.

For example, if character-string data is specified in an XML document even though the integer data type (xsd:integer) is defined for an element in the schema document, the following message is output:

In this message, the identifier is cvc-datatype-valid.1.2.1. This indicates a violation of the rule described in 1.2.1 of Validation Rule:Datatype Valid.

3.7 Parser Switching functionality

Organization of this section

3.7.1 Overview of the Parser Switching functionality

3.7.2 Usage of the Parser Switching functionality

3.7.3 Performance of the Parser Switching functionality

3.7.4 Notes on the Parser Switching functionality

3.7.1 Overview of the Parser Switching functionality

The Parser Switching functionality switches the priority order of the XML implementation by XML Processor and the framework or user-specified XML implementation. The XML implementation can be switched to the one supplied with the framework by using this functionality.

By using the Parser Switching functionality, the XML implementation can be switched even in the applications that use frameworks presuming other XML implementations. However, the XML implementation used by the Application Server components cannot be switched from XML Processor with the Parser Switching functionality.

Organization of this subsection

(1) Scope of the Parser Switching functionality

(2) Types of the target XML implementations

(1) Scope of the Parser Switching functionality

The Parser Switching functionality is applicable to J2EE servers. The parser switching settings do not affect other J2EE servers.

Also, even if the Parser Switching functionality is enabled, XML Processor is used to start or deploy a J2EE server instead of the user-specified XML implementation. The following figure shows the scope of the Parser Switching functionality.

Figure 3-20 Scope of the Parser Switching functionality

(2) Types of the target XML implementations

The following table describes the methods used for switching the XML implementation in the JAXP, StAX, and JAXB APIs.

Table 3-9 Names of the methods for switching the XML implementation

No. | API type | Class name | Method name
1 | JAXP API | javax.xml.datatype.DatatypeFactory | newInstance()
2 | javax.xml.parsers.DocumentBuilderFactory | newInstance()
3 | javax.xml.parsers.SAXParserFactory | newInstance()
4 | javax.xml.transform.TransformerFactory | newInstance()
5 | javax.xml.transform.sax.SAXTransformerFactory | newInstance()
6 | javax.xml.validation.SchemaFactory | newInstance(String schemaLanguage)
7 | javax.xml.xpath.XPathFactory | newInstance()
8 | newInstance(String URI)
9 | org.w3c.dom.bootstrap.DOMImplementationRegistry | newInstance()
10 | org.xml.sax.helpers.XMLReaderFactory | createXMLReader()
11 | StAX API | javax.xml.stream.XMLInputFactory | newInstance()
12 | newFactory()
13 | javax.xml.stream.XMLOutputFactory | newInstance()
14 | newFactory()
15 | javax.xml.stream.XMLEventFactory | newInstance()
16 | newFactory()
17 | JAXB API | javax.xml.bind.JAXBContext | newInstance(Class... classesToBeBound)
18 | newInstance(Class[] classesToBeBound, Map<String,?> properties)
19 | newInstance(String contextPath)
20 | newInstance(String contextPath, ClassLoader classLoader)
21 | newInstance(String contextPath, ClassLoader classLoader, Map<String,?> properties)

3.7.2 Usage of the Parser Switching functionality

The Parser Switching functionality includes the XML implementation used in an application and is set up in the following J2EE server definition files:

User property file for J2EE servers (usrconf.properties)

Security policy file for J2EE servers (server.policy)

For details on these files, see 2. Files Used in J2EE Servers in the uCosminexus Application Server Definition Reference Guide.

The storage locations of these files are as follows:

In Windows

Application-Server-installation-directory\CC\server\usrconf\ejb\server-name\

In UNIX

/opt/Cosminexus/CC/server/usrconf/ejb/server-name/

Organization of this subsection

(1) Including the XML implementation

(2) Setting up the user property file for J2EE servers

(3) Setting up the security policy file for J2EE servers

(1) Including the XML implementation

To include the XML implementation, you store the XML implementation under the library JAR of a J2EE application, or WEB-INF/lib of a Web application that will switch the implementation. If you want to switch the XML implementation with multiple applications, include the XML implementation in the applications. For details on the library JAR, see 2.3.3 J2EE applications and J2EE components in the uCosminexus Application Server System Design Guide.

Note that in the local call optimization functionality of Component Container, if all is specified in the optimization scope, see the notes described in 3.7.4(5) Notes on using the local call optimization functionality of Component Container.

(2) Setting up the user property file for J2EE servers

The user property file for J2EE servers (usrconf.properties) defines the system properties to be specified for starting a J2EE server. To use the Parser Switching functionality, you must specify the properties described in the following table in the user property file for J2EE servers, according to the target XML implementation type.

Table 3-10 Properties to be specified in the user property file for J2EE servers

API type | Property name
JAXP API | com.cosminexus.jaxp.change
StAX API | com.cosminexus.stax.change
JAXB API | com.cosminexus.jaxb.change

The following table describes the values that can be specified in these properties and their meanings.

Table 3-11 Set values and meanings of the properties

Set value of the property | Meaning
true | The process switches to the XML implementation that includes the XML implementation for APIs.
false (Default value) | The XML implementation provided by XML Processor will be used.

(3) Setting up the security policy file for J2EE servers

To start a J2EE server without specifying the -nosecurity option (releasing SecurityManager), you specify the following settings in the security policy file for J2EE servers (server.policy) depending on the API type:

If the switching of the JAXP API implementation is specified

permission java.io.FilePermission "${cosminexus.home}/jaxp/lib/csmjaxp.jar", "read";

If the switching of the StAX API implementation is specified

permission java.io.FilePermission "${cosminexus.home}/jaxp/lib/csmstax.jar", "read";

If the switching of the JAXB API implementation is specified

permission java.lang.RuntimePermission "accessDeclaredMembers";
permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
permission java.io.FilePermission "${cosminexus.home}/jaxp/lib/csmjaxb.jar", "read";

3.7.3 Performance of the Parser Switching functionality

When you do not use the Parser Switching functionality, the processing has the same performance as in the case of version 09-00.

If the Parser Switching functionality is used, the processing speed reduces by a few milliseconds the first time when the Factory class instances described in 3.7.1(2) Types of the target XML implementations are generated. From the second and subsequent times, the deterioration is not problematic. There is no performance deterioration for the javax.xml.validation.SchemaFactory, javax.xml.xpath.XPathFactory, and javax.xml.bind.JAXBContext APIs.

3.7.4 Notes on the Parser Switching functionality

Organization of this subsection

(1) XML implementation for the container extension library

(2) Notes on using the Application Server functionality

(3) Versions of XML implementation to be switched

(4) Switching the XML implementation class

(5) Notes on using the local call optimization functionality of Component Container

(6) Switching the XML implementation of the client-operated Java applications

(1) XML implementation for the container extension library

If you specify a class path for an XML implementation other than XML Processor in usrconf.cfg, the start processing of Application Server or operations of the components are affected, hence, you cannot specify the XML implementation in the container extension library.

For details on the container extension library, see 14. Container Extension Library in the uCosminexus Application Server Common Container Functionality Guide.

(2) Notes on using the Application Server functionality

The functionality provided with Application Server includes functionality that requires XML Processor operations. Note that the functionality described in the following table might not operate normally if used concurrently with the Parser Switching functionality in the same application.

Table 3-12 Application Server functionality that does not support the switching of XML implementation

API type
Application Server functionality that does not support the switching of XML implementation

JAXP API

All the functions of the Web Sservice functionality (JAX-WS functionality, JAX-RS functionality, WS-RM1.1 functionality, and WS-RM1.2 functionality)

All the functions for the communication between a Web Service and SOAP (existing functionality)

All the functions of the JPA functionality

All the functions of the JSF functionality

All the functions of the JSTL functionality

All the functions of the BeanValidation functionality

All the functions of the CDI functionality

All the functions of the security management (Web Service) functionality

All the functionality of cFramework

Reliable Messaging functionality for transmission between queues

JAXB functionality of XML Processor

All the functionality of Service Coordinator

StAX API

All the functions of the Web Service functionality (JAX-WS functionality, JAX-RS functionality, and WS-RM1.2 functionality)

All the functions of the JSTL functionality

All the functions of the BeanValidation functionality

JAXB functionality of XML Processor

All the functions of Service Coordinator

JAXB API

All the functions of the Web Service functionality (JAX-WS functionality, JAX-RS functionality, and WS-RM1.2 functionality)

All the functions of the JSTL functionality

All the functions of the BeanValidation functionality

All the functions of the Service Coordinator

As a roundabout, consider dividing the components that require the user-specified XML implementation and the components that require the Application Server functionality into separate applications.

Also, on the J2EE servers that operate Service Coordinator, operate the applications that require the user-specified XML implementation on a J2EE server different than the user-specified XML implementation with Service Coordinator.

(3) Versions of XML implementation to be switched

Switching the XML implementation with the Parser Switching functionality does not switch APIs. Therefore, you cannot change the API version from the one supported by Application Server.

For example, if you switch the XML implementation conforming to a version different from one supported by Application Server, JAXP1.4/StAX1.0/JAXB2.2 supported by XML Processor 09-50 are used and the APIs added to the new version cannot be used for development and execution. Also, take precautions when you switch to an XML implementation of a different version because the operations might be affected by changes in the specifications and errors or exceptions might occur when the APIs are used.

(4) Switching the XML implementation class

JAXP1.4 and JAXB2.2 provide the mechanism for switching the implementation classes. If the implementation classes have already been switched with the system properties in the user property file for J2EE servers, the specification has a higher priority, and therefore, the specification of the Parser Switching functionality is not enabled.

(5) Notes on using the local call optimization functionality of Component Container

When an XML implementation is included with a J2EE application and if all is specified in the optimization scope for the local call optimization functionality of Component Container (ejbserver.rmi.localinvocation.scope=all), the XML implementation of all the applications running on the same J2EE server switches. The EJB-JARs and library JARs of J2EE applications are loaded using the same class loader, so the classes with the same name are shared between the J2EE applications. If there are classes with the same names but different contents, according to the Java specifications, note that only the class loaded first is enabled.

For details on the local call optimization functionality, see Appendix B.2 Class loader configuration for local call optimization in the uCosminexus Application Server Common Container Functionality Guide.

(6) Switching the XML implementation of the client-operated Java applications

With Java applications, the XML implementation is switched by specifying the system properties in the user property file for Java applications, so the Parser Switching functionality is not supported.

For details on the user property file for Java applications, see 14.3 usrconf.properties (User property file for Java applications) in the uCosminexus Application Server Definition Reference Guide.

3.8 Compatibility option functionality

With XML Processor version 07-00 or later, some of the functionality and operations differ from the previous versions because of migration from JAXP1.2 to JAXP1.3. If you use the compatibility option functionality of XML Processor, you can perform the same operations as the previous versions.

Organization of this section

3.8.1 Overview of the compatibility option functionality

3.8.2 How to set up the compatibility option functionality

3.8.1 Overview of the compatibility option functionality

With the compatibility option functionality of XML Processor, you can use the functionality for validated parsing compatibility that uses the XML schema. With the functionality for validated parsing compatibility, version 06-00 operations and version 07-00 or later operations are switched for the items described in the following table.

Table 3-13 Operations switched with the functionality for validated parsing compatibility

Items
XML Processor 06-00 operations
XML Processor 07-00 or later operations

When the schema document and instance document reference a URI with an invalid syntax
No exception is thrown.
The following exceptions are thrown:

For operations with JDK5
IllegalArgumentException

For operations with JDK6
NullPointerException or IllegalArgumentException

When a non-existing schema document is referenced
The KECX06069-E error (warning event) is not reported.
The KECX06069-E error (warning event) is reported.

3.8.2 How to set up the compatibility option functionality

Organization of this subsection

(1) Files for setting up the compatibility option functionality

(2) Setting up the properties

(1) Files for setting up the compatibility option functionality

You can set up the compatibility option functionality in one of the following files according to the environment in use:

User property file for J2EE servers

Application-Server-installation-directory/CC/server/usrconf/ejb/server-name/usrconf.properties

User property file for Web container servers

Application-Server-installation-directory/CC/web/containers/server-name/usrconf/usrconf.properties

User property file for EJB client applications

Directory-for-storing-user-defined-file/usrconf.properties

(2) Setting up the properties

Specify the properties in the file in the following format. The values of the compatibility option are only read once during startup. You cannot change the values after startup.

Property-name=Set-value

The following table describes the property names and the set values used in the functionality for validated parsing compatibility.

Table 3-14 Property names and set values used in the functionality for validated parsing compatibility

Items
Property name
Set value

When the schema and instance documents reference a URI with an invalid syntax
com.cosminexus.jaxp.compat.schema_illegal_uri

ON
The same operations are executed as in version 06-00.

OFF, other characters
The same operations are executed as in version 07-00 or later (default).

When a non-existing schema document is referenced
com.cosminexus.jaxp.compat.schemalocation

4. How to Use Features and Properties

This chapter describes how to use the features and properties provided in JAXP and JAXB. This chapter describes how to use the features and properties defined in JAXP, and the features and properties related to the extended functions of Cosminexus XML Processor.

Organization of this chapter

4.1 How to Use the SAX2 Features and Properties

4.2 How to use StAX properties

4.3 How to use XSLT features

4.4 How to Use the XML Schema Properties

4.5 How to use the properties of the Shift_JIS switch function

4.6 How to use the properties of the high-speed parse support function

4.7 How to use the properties of JAXB

4.1 How to Use the SAX2 Features and Properties

The SAX2 standards define how to use the SAX parser's optional functions by using features and properties.

A feature or property name is a URI corresponding to an optional function of the SAX parser. The formats of the feature and property names are as follows:

Table 4-1 and Table 4-2 list the SAX2 features and SAX2 properties supported by Cosminexus XML Processor respectively.

Table 4-1 SAX2 features supported by Cosminexus XML Processor

No. | Feature name
1 | http://xml.org/sax/features/external-general-entitie
2 | http://xml.org/sax/features/external-parameter-entities
3 | http://xml.org/sax/features/namespaces
4 | http://xml.org/sax/features/namespace-prefixes
5 | http://xml.org/sax/features/use-attributes2
6 | http://xml.org/sax/features/use-locator2
7 | http://xml.org/sax/features/use-entity-resolver2
8 | http://xml.org/sax/features/validation

Table 4-2 SAX2 properties supported by Cosminexus XML Processor

No. | Property name
1 | http://xml.org/sax/properties/declaration-handler
2 | http://xml.org/sax/properties/lexical-handler

For the meaning of each feature and property, see the following parts in Javadoc of Simple API for XML (SAX) 2.0.2 (sax2r3):

SAX2 Standard Feature Flags in the org.xml.sax package

SAX2 Standard Handler and Property IDs in the org.xml.sax package

Organization of this section

(1) How to use the SAX2 features

(2) How to use the SAX2 properties

(1) How to use the SAX2 features

To set a SAX2 feature, use the setFeature method of the org.sax.xml.XMLReader class. How to set a feature is shown below:

(2) How to use the SAX2 properties

To set a SAX2 property, use the setProperty method of the org.sax.xml.XMLReader class. How to set a property is shown below.

4.2 How to use StAX properties

The StAX standards allow you to specify properties in XMLInputFactory and XMLOutputFactory. You can specify the following properties:

javax.xml.stream.isNamespaceAware

javax.xml.stream.isCoalescing

javax.xml.stream.isReplacingEntityReferences

javax.xml.stream.isSupportingExternalEntities

javax.xml.stream.reporter

javax.xml.stream.resolver

javax.xml.stream.allocator

javax.xml.stream.isRepairingNamespaces

For meanings of the respective properties, see the following subsections in Streaming API For XML Version 1.0 (JSR-173):

Chapter 4.5.1.1. Supported Properties of XMLInputFactory

Chapter 4.5.2.1 Supported Properties of XMLOutputFactory

Javadoc

Organization of this section

(1) How to use StAX properties

(1) How to use StAX properties

To specify properties for XMLInputFactory, use the setProperty method of the javax.xml.stream.XMLInputFactory class, and to specify properties for XMLOutputFactory, use the setProperty method of the javax.xml.stream.XMLOutputFactory class.

The following points describe how to specify the respective properties:

To specify properties for XMLInputFactory

To specify properties for XMLOutputFactory

4.3 How to use XSLT features

The JAXP standard defines how to use the XSLT transformer's optional functions by using features.

A feature name is a URI corresponding to an optional function of the XSLT transformer. The following table lists the XSLT features defined in JAXP.

Table 4-3 XSLT features defined in JAXP

No. | Feature name
1 | http://javax.xml.transform.stream.StreamSource/feature
2 | http://javax.xml.transform.stream.StreamResult/feature
3 | http://javax.xml.transform.dom.DOMSource/feature
4 | http://javax.xml.transform.dom.DOMResult/feature
5 | http://javax.xml.transform.sax.SAXSource/feature
6 | http://javax.xml.transform.sax.SAXResult/feature
7 | http://javax.xml.transform.sax.SAXTransformerFactory/feature
8 | http://javax.xml.transform.sax.SAXTransformerFactory/feature/xmlfilter

For the meanings of the features, see the FEATURE field described in each class of Javadoc in the documentation JSR 206 Java API for XML Processing(JAXP) 1.4.

Organization of this section

(1) How to use the XSLT features

(1) How to use the XSLT features

You cannot set any XSLT features. To get an XSLT feature, use the getFeature method of the javax.xml.transform.TransformerFactory class. The result of getFeature is always true.

4.4 How to Use the XML Schema Properties

By setting a property defined in JAXP, you can identify the schema language and document used in the schema validation. For details about properties, see Properties For Enabling Schema Validation in Chapter 4. Plugability Layer of the documentation JSR 206 Java API for XML Processing (JAXP) 1.4.

Organization of this section

4.4.1 How to Set the XML Schema Properties for the DOM Parser

4.4.2 How to Set the XML Schema Properties SAX Parser

4.4.3 How to Set the Schema Document in the XML Document

4.4.1 How to Set the XML Schema Properties for the DOM Parser

To set any XML Schema properties to the DOM parser, use the setAttribute method of the javax.xml.parsers.DocumentBuilderFactory class. How to set a property is shown below.

The following describes the coding example. Each item number corresponds to the number in the comments in the coding example.

Perform the setting that enables validation.
Set the argument of the setValidating method on the javax.xml.parsers.DocumentBuilderFactory class to true. This setting enables the XML document validation function.

Set the schema language to use for schema validation.
Using the setAttribute method of the javax.xml.parsers.DocumentBuilderFactory class, for the property string "http://java.sun.com/xml/jaxp/properties/schemaLanguage" set the value "http://www.w3.org/2001/XMLSchema", which indicates that validation will follow the XML Schema specification.

Identify the schema document.
Using the setAttribute method of the javax.xml.parsers.DocumentBuilderFactory class, for the property string "http://java.sun.com/xml/jaxp/properties/schemaSource" specify the schema document used for validation. This specification is not necessary if the schema document is identified in the XML document.

4.4.2 How to Set the XML Schema Properties SAX Parser

To set any XML Schema properties to the SAX parser, use the setProperty method of the javax.xml.parsers.SAXParser class. How to set a property is shown below.

The following describes the coding example. Each item number corresponds to the number in the comments in the coding example.

Perform the setting that enables validation.
Set the argument of the setValidating method on the javax.xml.parsers.SAXParserFactory class to true. This setting enables the XML document validation function.

Set to comply with the XML Schema specification.
Using the setProperty method of the javax.xml.parsers.SAXParser class, for the property string "http://java.sun.com/xml/jaxp/properties/schemaLanguage" set the value "http://www.w3.org/2001/XMLSchema", which indicates that validation will follow the XML Schema specification.

Identify the schema document.
Using the setProperty method of the javax.xml.parsers.SAXParser class, for the property string "http://java.sun.com/xml/jaxp/properties/schemaSource" specify the schema document used for validation. This specification is not necessary if the schema document is identified in the XML document.

4.4.3 How to Set the Schema Document in the XML Document

Each approach described in 4.4.1 How to Set the XML Schema Properties for the DOM Parser and 4.4.2 How to Set the XML Schema Properties SAX Parser sets the schema document by using the property. Alternatively, you can identify the schema document directly in the XML document to be validated. Note that if you identify the schema document both in the XML document and by using the property, the schema document identified by using the property is used.

To identify the schema document in the XML document to be validated, use the xsi:schemaLocation or xsi:noNamespaceSchemaLocation attribute. Which attribute to use depends on whether the namespace is defined in the schema document. The following table lists the types of schema document to identify and the attributes to use for them.

Table 4-4 Types of the schema document to identify and the attributes to use for them

Type of schema document to identify | Attribute to use
Schema document with the namespace defined | xsi:schemaLocation
Schema document with no namespace defined | xsi:noNamespaceSchemaLocation

When using the xsi:schemaLocation attribute, specify both the namespace URI of the elements and attributes declared in the schema document to identify and the name of the schema document to identify, separated by a space.

Both the xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes belong to the namespace http://www.w3.org/2001/XMLSchema-instance. Therefore, when these attributes are used to identify a schema document, the namespace http://www.w3.org/2001/XMLSchema-instance needs to be declared.

The follow shows an example of specifying a schema document by using the xsi:schemaLocation:

Declare the namespace of the xsi:schemaLocation attribute.
To use the xsi:schemaLocation attribute for specifying the schema document, declare this attribute's namespace http://www.w3.org/2001/XMLSchema-instance.

Identify the schema document.
Specify both the namespace URI of the elements and attributes declared in the schema document to identify and the name of the schema document, separated by a space.
The above example specifies purchaseOrder.xsd as the schema document and http://www.myshopping.com/schema/purchaseOrder as the namespace for elements and attributes declared in the schema document purchaseOrder.xsd.

4.5 How to use the properties of the Shift_JIS switch function

To use the Shift_JIS switch function, you need to set the following property defined independently by Cosminexus XML Processor.

Set a character encoding as the property value. The following table lists the property values to set and their meanings.

Table 4-5 Property values to set and their meanings

Value set in the property#1 | Meaning
SJIS | Applies the SJIS encoding.
MS932 | Applies the MS932 encoding.
Any other character string | Ignores the specification.#2

#1

The specified character string is not case-sensitive.

#2

If the specification is ignored, the last specified encoding is valid.

Note

If the Shift_JIS switch function is not specified, the default encoding is SJIS.

The Shift_JIS switch function property needs to be set for each instance of the classes and interfaces shown below. The following table lists the methods for setting the Shift_JIS switch function. This table lists the methods to use for setting the properties for each class and interface.

Table 4-6 Methods for setting the Shift_JIS switch function

Class and interface | Method
javax.xml.parsers.DocumentBuilderFactory | setAttribute
javax.xml.parsers.SAXParser | setProperty
org.xml.sax.XMLReader | setProperty
javax.xml.parsers.TransformerFactory | setAttribute

The following subsections describe the cases in which to use the Shift_JIS switch function for the DOM parser, SAX parser, and XSLT transformer.

Organization of this section

4.5.1 How to Use the Shift_JIS Switch Function for the DOM Parser

4.5.2 How to Use the Shift_JIS Switch Function for the SAX Parser

4.5.3 How to Use the Shift_JIS Switch Function for the XSLT Transformer

4.5.1 How to Use the Shift_JIS Switch Function for the DOM Parser

This subsection describes the flow of basic coding that uses the Shift_JIS switch function in the DOM parser.

The following describes the coding example. Each item number corresponds to the number in the comments in the coding example.

Create DocumentBuilderFactory.
Use the static method newInstance() of javax.xml.parsers.DocumentBuilderFactory to create the factory.

Switch Shift_JIS to MS932.
In the setAttribute method for the DOM parser setting, specify the first argument to the setting key http://cosminexus.com/xml/properties/shift_jis_map and the second argument to MS932.

Create DocumentBuilder.
Use the newDocumentBuilder() method to create DocumentBuilder.

4.5.2 How to Use the Shift_JIS Switch Function for the SAX Parser

This subsection describes the flow of basic coding that uses the Shift_JIS switch function in the SAX parser. The follow shows an example of the coding:

The following describes the coding example. Each item number corresponds to the number in the comments in the coding example.

Create SAXParserFactory.
Use the static method newInstance() of javax.xml.parsers.SAXParserFactory to create the factory.

Create SAXParser.
Use newSAXParser() to create the SAX parser.

Obtain the XMLReader.
Use getXMLReader() to obtain the XMLReader.

Switch Shift_JIS to MS932.
In the setProperty method for the SAX parser setting, specify the first argument to the setting key http://cosminexus.com/xml/properties/shift_jis_map and the second argument to MS932.

4.5.3 How to Use the Shift_JIS Switch Function for the XSLT Transformer

This subsection describes the flow of basic coding that uses the Shift_JIS switch function in the XSLT transformer. The follow shows an example of the coding:

The following describes the coding example. Each item number corresponds to the number in the comments in the coding example.

Create TransformerFactory.
Use the static method newInstance() of javax.xml.transform.TransformerFactory to create the factory.

Switch Shift_JIS to MS932.
In the setAttribute method for the XSLT transformer factory setting, specify the first argument to the setting key http://cosminexus.com/xml/properties/shift_jis_map and the second argument to MS932.

Create Transformer.
Use the newTransformer() method to create a transformer.

4.6 How to use the properties of the high-speed parse support function

To use the high-speed parse support function, you need to set the following property defined independently by Cosminexus XML Processor.

Set up either null or PreparsedObject object in the property value. The following table lists the property values to set and their meanings.

Table 4-7 Value and meaning of the property to be set up (high-speed parse support function)

Value set in the property# | Meaning
null | The preparsed object is not used when parsing.
PreparsedObject object | The specified preparsed object is used when parsing.

#

If no value is specified, it is assumed to be null.

If a value other than null and the PreparsedObject object is set up, the following exceptions occur depending on the XML parser in which the property is set up:

In DocumentBuilderFactory: IllegalArgumentException

In SAXParser or XMLReader: SAXNotSupportedException

The properties of the high-speed parse support function must be set up in each object of the following XML parsers. The following table describes how to set up the preparsed object. This table lists the methods to use for setting the properties for each class and interface.

Table 4-8 Methods for setting up the preparsed object

Class and interface | Method
javax.xml.parsers.DocumentBuilderFactory | setAttribute
javax.xml.parsers.SAXParser | setProperty
org.xml.sax.XMLReader | setProperty

The details for using the high-speed parse support function in DocumentBuilder, SAXParser, and XMLReader are described in the following subsections with appropriate examples.

Organization of this section

4.6.1 How to set up the preparsed object in DocumentBuilder

4.6.2 How to set up the preparsed object in SAXParser

4.6.3 How to set up the preparsed object in XMLReader

4.6.1 How to set up the preparsed object in DocumentBuilder

A coding example to set up the preparsed object in DocumentBuilder is as follows:

The following describes the coding example. Each item number corresponds to the number in the comments in the coding example.

Generate the preparsed object.
For details about how to generate the preparsed object, see 3.4.4 Generating the preparsed object.

Set up the preparsed object in DocumentBuilder.
In the first argument of the setAttribute method used to set up the preparsed object, specify the setup key http://cosminexus.com/xml/properties/preparsedobject-load, and in the second argument, specify pobj that indicates the PreparsedObject object.

4.6.2 How to set up the preparsed object in SAXParser

A coding example to set up the preparsed object in SAXParser is as follows:

Generate the preparsed object.
For details about how to generate the preparsed object, see 3.4.4 Generating the preparsed object.

Set up the preparsed object in SAXParser.
In the first argument of the setProperty method used to set up the preparsed object, specify the setup key http://cosminexus.com/xml/properties/preparsedobject-load, and in the second argument, specify pobj that indicates the PreparsedObject object.

4.6.3 How to set up the preparsed object in XMLReader

A coding example to set up the preparsed object in XMLReader is as follows:

Generate the preparsed object.
For details about how to generate the preparsed object, see 3.4.4 Generating the preparsed object.

Set up the preparsed object in XMLReader.
In the first argument of the setProperty method used to set up the preparsed object, specify the setup key http://cosminexus.com/xml/properties/preparsedobject-load, and in the second argument, specify pobj that indicates the PreparsedObject object.

4.7 How to use the properties of JAXB

In JAXB, you can set up the properties in Marshaller. The JAXB properties supported by Cosminexus XML Processor are as follows:

JAXB properties supported by Cosminexus XML Processor

jaxb.encoding

jaxb.formatted.output

jaxb.schemaLocation

jaxb.noNamespaceSchemaLocation

jaxb.fragment

For details about properties, see Chapter 4.5.2. Marshalling Properties and javadoc of JSR 222 The Java Architecture for XML Binding(JAXB) 2.2.

For details about the character encodings that can be specified in jaxb.encoding, see 1.3.2 Character encodings that can be processed.

To set up properties in Marshaller, use the setProperty method of the javax.xml.bind.Marshaller class. How to set a property is shown below.

5. How to Create a Program

This chapter describes the general procedure for creating a program, packages to be used, and sample programs that use the key JAXP functions.

Organization of this chapter

5.1 General Procedure for Creating a Program

5.2 Package Names Used by Cosminexus XML Processor

5.3 Troubleshooting Program Execution

5.4 Sample Program that Uses the DOM Parser

5.5 Sample Program that Uses the SAX Parser

5.6 Sample Program that Uses the XML Schema

5.7 Sample Program that Uses the XSLT Transformer

5.8 Sample Program that Uses the XSLTC Transformer

5.1 General Procedure for Creating a Program

The following figure shows the general procedure for creating a program by using Cosminexus XML Processor:

Figure 5-1 Procedure for creating a program using Cosminexus XML Processor

Organization of this section

(1) Deciding which package to use

(2) Creating source files

(3) Creating an executable file

(4) Executing the program

(1) Deciding which package to use

Cosminexus XML Processor provides the packages defined in the JAXP specification, the packages of XSLTC transformer function, and the packages defined in the JAXB specification. When creating a program, select a suitable package for use with the program.

For instance, use DOM when it is necessary to maintain the XML document in memory to change its structure or perform complex operations; use SAX when the processing is performed while interactively parsing the XML document, and use XSLT when the XML document is transformed into any other format such as HTML.

For details about packages provided in the JAXP specifications, see 2.2 JAXP-defined Packages and Their Functionality, for packages of the XSLTC transformer function, see 3.2.3 Class Used by the XSLTC Transformer, and for packages stipulated in the JAXB specifications, see 2.4 JAXB-defined Packages and Their Functionality.

(2) Creating source files

After deciding the package to use, create source files using the classes and interfaces contained in each package.

(3) Creating an executable file

Create an executable file from the source files you created.

To create an executable file, you need to compile the created source files by the javac command and link any libraries necessary for the classes and interfaces to be used.

(4) Executing the program

Execute the program you have compiled.

5.2 Package Names Used by Cosminexus XML Processor

Cosminexus XML Processor uses package names starting with the following strings:

com.cosminexus.jaxp.

com.cosminexus.jaxb.

com.cosminexus.stax.

Note

Do not use com.cosminexus.jaxp., com.cosminexus.jaxb., or com.cosminexus.stax. at the beginning of any user program package name.

5.3 Troubleshooting Program Execution

When operating a system that uses Cosminexus XML Processor, if an error occurs that the system administrator needs to be notified of, or the appropriate countermeasure for an error is unclear, the following information used to investigate the failure must be gathered from application logs.

Date and time when the failure occurred

Name of the input XML documents when the failure occurred (including the schema document name and the stylesheet name)

Obtain the following failure information together with the application log above, and then contact the system administrator.

Application log files

The input XML documents when the failure occurred (including the schema document and the stylesheet)

Cosminexus XML Processor error messages output when the failure occurred

System properties and system class paths set on the server and client

Server and client standard output and standard error output

Cosminexus Component Container log and Web server log

The information, as defined for Cosminexus Component Container, to be obtained when a failure occurs
The following shows the information, as defined for Cosminexus Component Container, to be obtained when a failure occurs.

User definition file of the J2EE server

Maintenance information of the J2EE server

User definition file of the server management commands

Maintenance information of server management commands

Standard output and standard error output of the J2EE server

Cosminexus TPBroker log on the J2EE server

System properties and system class paths set in EJB client application

Standard output and standard error output of the EJB client application

Packet content collected by the network monitor tool

For details on how to obtain the failure information provided in Cosminexus Component Container, see 2.3 Obtaining data in the uCosminexus Application Server Maintenance and Migration Guide.

5.4 Sample Program that Uses the DOM Parser

This section describes a sample program that uses the DOM parser.

The sample program is provided only in Windows.

The installation folder and file name of the sample program are as follows.

Installation folder:

installation-folder-of-Cosminexus-XML-Processor\samples\DOM

File name:

SampleDOM.java

Organization of this section

5.4.1 Processing Performed by the Sample Program

5.4.2 General Procedure for Creating the Sample Program

5.4.3 Sample program (SampleDOM.java)

5.4.4 Execution Result of the Sample Program (SampleDOM.java)

5.4.1 Processing Performed by the Sample Program

The sample program performs the following processing:

The program creates a new DOM tree that codes the product information.

The program transforms the created DOM tree into an XML document and outputs the XML document.

The program reads the output XML document.

From the read XML document, the program outputs the total cost of products to the window.

5.4.2 General Procedure for Creating the Sample Program

The following figure shows the general procedure for creating a sample program that uses the DOM parser.

Figure 5-2 General procedure for creating a sample program that uses the DOM parser

Create a Document object.
Create a new Document object.

Create the Document node.
By using the Document object you created in step 1, create the Document node that is the parent of the DOM tree.

Create the Element nodes.
Create the necessary Element nodes from the Document node to create the DOM tree.

Create the Text nodes.
Create the character strings that are the contents of the elements.

5.4.3 Sample program (SampleDOM.java)

The following shows the sample program:

import java.io.*;
import javax.xml.parsers.*;
import javax.xml.transform.*;
import javax.xml.transform.dom.*;
import javax.xml.transform.stream.*;
import org.xml.sax.SAXException;
import org.w3c.dom.*;

public class SampleDOM
{
 public static final void main(String[] args)
 {
   try{
     new SampleDOM().CreateXMLFile();
     new SampleDOM().GetStringFromXML();
   }catch(Exception exception){
     exception.printStackTrace();
   }
 }

 //create XML file
 public final void CreateXMLFile()
 {
   try{
     DocumentBuilderFactory dbf =
         DocumentBuilderFactory.newInstance();
     DocumentBuilder db = dbf.newDocumentBuilder();

     Document doc = db.newDocument();
     Element parent = doc.createElement("Payment_Slip");

     Element sub = doc.createElement("Merchandise");
     Element leaf1 = doc.createElement("Brand_Name");
     Element leaf2 = doc.createElement("Unit_Price");
     Element leaf3 = doc.createElement("Amount");
     leaf1.appendChild(doc.createTextNode("Television"));
     sub.appendChild(leaf1);
     leaf2.appendChild(doc.createTextNode("15000"));
     sub.appendChild(leaf2);
     leaf3.appendChild(doc.createTextNode("14"));
     sub.appendChild(leaf3);
     parent.appendChild(sub);

     sub = doc.createElement("Merchandise");
     leaf1 = doc.createElement("Brand_Name");
     leaf2 = doc.createElement("Unit_Price");
     leaf3 = doc.createElement("Amount");
     leaf1.appendChild(doc.createTextNode("Radio"));
     sub.appendChild(leaf1);
     leaf2.appendChild(doc.createTextNode("3500"));
     sub.appendChild(leaf2);
     leaf3.appendChild(doc.createTextNode("6"));
     sub.appendChild(leaf3);
     parent.appendChild(sub);

     sub = doc.createElement("Merchandise");
     leaf1 = doc.createElement("Brand_Name");
     leaf2 = doc.createElement("Unit_Price");
     leaf3 = doc.createElement("Amount");
     leaf1.appendChild(doc.createTextNode("Video"));
     sub.appendChild(leaf1);
     leaf2.appendChild(doc.createTextNode("21000"));
     sub.appendChild(leaf2);
     leaf3.appendChild(doc.createTextNode("4"));
     sub.appendChild(leaf3);
     parent.appendChild(sub);

     doc.appendChild(parent);

     OutputStream os =
         new BufferedOutputStream(
         new FileOutputStream("SampleDOM.xml"));
     TransformerFactory tf =
         TransformerFactory.newInstance();
     Transformer tran = tf.newTransformer();
     tran.setOutputProperty("encoding", "Shift_JIS");
     tran.setOutputProperty("indent", "yes");
     tran.transform(new DOMSource(doc),
         new StreamResult(os));

     os.flush();
     os.close();

   }catch(ParserConfigurationException e){
     e.printStackTrace();
   }catch(TransformerConfigurationException e){
     e.printStackTrace();
   }catch(TransformerException e){
     e.printStackTrace();
   }catch(IOException e){
     e.printStackTrace();
   }
 }

 //acquire data from the XML file made by CreateXMLFile, and calculate
 public final void GetStringFromXML()
 {
   try{
     int tvPrice = 0;
     int radioPrice = 0;
     int videoPrice = 0;

     DocumentBuilderFactory factory =
         DocumentBuilderFactory.newInstance();
     DocumentBuilder builder = factory.newDocumentBuilder();

     Document doc = builder.parse("SampleDOM.xml");
     Element element1 = doc.getDocumentElement();
     NodeList nodelist1 = element1.getElementsByTagName("Merchandise");

     //loop for number of the merchandise
     for(int nShouhin = 0 ;
         nShouhin < nodelist1.getLength() ; nShouhin++){
       String str = new java.lang.String();
       int price = 0;
       int number = 0;
       Element element2 = (Element)nodelist1.item(nShouhin);

       //get the brand name
       NodeList nodelist2 =
           element2.getElementsByTagName("Brand_Name");
       Node node1 = nodelist2.item(0);
       if(node1.getNodeType() == Node.ELEMENT_NODE){
         Element element3 = (Element)node1;
         NodeList nodelist3 = element3.getChildNodes();
         Node node2 = nodelist3.item(0);
         str = node2.getNodeValue();
       }

       //get the unit price of a brand name
       nodelist2 = element2.getElementsByTagName("Unit_Price");
       node1 = nodelist2.item(0);
       if(node1.getNodeType() == Node.ELEMENT_NODE){
         Element element3 = (Element)node1;
         NodeList nodelist3 = element3.getChildNodes();
         Node node2 = nodelist3.item(0);
         price = Integer.parseInt(node2.getNodeValue());
       }

       //get the amount of a brand name
       nodelist2 = element2.getElementsByTagName("Amount");
       node1 = nodelist2.item(0);
       if(node1.getNodeType() == Node.ELEMENT_NODE){
         Element element3 = (Element)node1;
         NodeList nodelist3 = element3.getChildNodes();
         Node node2 = nodelist3.item(0);
         number = Integer.parseInt(node2.getNodeValue());
       }

       //subtotal calculation of each merchandise
       if(str.equals("Television")){
         tvPrice = price * number;
       }else if(str.equals("Radio")){
         radioPrice = price * number;
       }else if(str.equals("Video")){
         videoPrice = price * number;
       }
     }
     int sum = tvPrice + radioPrice + videoPrice;
     System.out.println(sum + " yen in total.");
   }catch(ParserConfigurationException e){
     e.printStackTrace();
   }catch(SAXException e){
     e.printStackTrace();
   }catch(IOException e){
     e.printStackTrace();
   }
 }
}

5.4.4 Execution Result of the Sample Program (SampleDOM.java)

The execution result of this sample program is output to the standard output and SampleDOM.xml.

Content of the standard output:

$ The total is 315000 yen.

Content output to SampleDOM.xml:

<?xml version="1.0" encoding="Shift_JIS"?>
<Payment_Slip>
<Merchandise>
<Brand_Name>Television</Brand_Name>
<Unit_Price>15000</Unit_Price>
<Amount>14</Amount>
</Merchandise>
<Merchandise>
<Brand_Name>Radio</Brand_Name>
<Unit_Price>3500</Unit_Price>
<Amount>6</Amount>
</Merchandise>
<Merchandise>
<Brand_Name>Video</Brand_Name>
<Unit_Price>21000</Unit_Price>
<Amount>4</Amount>
</Merchandise>
</Payment_Slip>

5.5 Sample Program that Uses the SAX Parser

This section describes a sample program that uses the SAX parser.

The sample program is provided only in Windows.

The installation folder and file name of the sample program are as follows.

Installation folder:

installation-folder-of-Cosminexus-XML-Processor\samples\SAX

File name:

SampleSAX.xml

SampleSAX.java

Organization of this section

5.5.1 Processing Performed by the Sample Program

5.5.2 General Procedure for Creating the Sample Program

5.5.3 XML Document to Use (SampleSAX.xml)

5.5.4 Sample Program (SampleSAX.java)

5.5.5 Execution Result of the Sample Program (SampleSAX.java)

5.5.1 Processing Performed by the Sample Program

The sample program performs the following processing:

The program reads the XML document that codes the product information.

From the read XML document, the program outputs the total cost of products to the window.

5.5.2 General Procedure for Creating the Sample Program

The following figure shows the general procedure for creating a sample program that uses the SAX parser.

Figure 5-3 General procedure for creating a sample program that uses the SAX parser

Create the callback handler.
When parsing is started using the SAX parser, the information in the XML document is reported from the SAX parser. Create the callback handler to receive the information.

Register the callback handler with the SAX parser.
Register the callback handler you created in step 1 with the SAX parser.

Pass the XML document to the SAX parser to parse it.
Parse the XML document.

Methods called by the SAX parser:

The following diagram shows the methods called by the SAX parser:

5.5.3 XML Document to Use (SampleSAX.xml)

The following shows the XML document to use:

<?xml version="1.0" encoding="Shift_JIS"?>
<Payment_Slip>
 <Merchandise>
   <Brand_Name>Television</Brand_Name>
   <Unit_Price>15000</Unit_Price>
   <Amount>14</Amount>
 </Merchandise>
 <Merchandise>
   <Brand_Name>Radio</Brand_Name>
   <Unit_Price>3500</Unit_Price>
   <Amount>6</Amount>
 </Merchandise>
 <Merchandise>
   <Brand_Name>Video</Brand_Name>
   <Unit_Price>21000</Unit_Price>
   <Amount>4</Amount>
 </Merchandise>
</Payment_Slip>

5.5.4 Sample Program (SampleSAX.java)

The following shows the sample program:

import javax.xml.parsers.*;
import org.xml.sax.*;
import org.xml.sax.helpers.*;
import org.xml.sax.SAXException;
import java.io.*;

public class SampleSAX{

 public static final void main(String[] args){
   try{
     SAXParserFactory factory = SAXParserFactory.newInstance();
     SAXParser parser = factory.newSAXParser();
     String xml = "SampleSAX.xml";
     DefaultHandler handler = new EventHandler();

     parser.parse(xml, handler);
   }catch(ParserConfigurationException e){
     e.printStackTrace();
   }catch(IOException e){
     e.printStackTrace();
   }catch(SAXException e){
     e.printStackTrace();
   }
 }
}

//calculate an amount of money in total and output it
class EventHandler extends DefaultHandler{

 int     tvPrice;        //Television unit price
 int     radioPrice;     //Radio unit price
 int     videoPrice;     //Video unit price
 int     tvNum;          //Television amount
 int     radioNum;       //Radio amount
 int     videoNum;       //Video amount
 boolean tvFlag;         //Television flag
 boolean radioFlag;      //Radio flag
 boolean videoFlag;      //Video flag
 boolean tankaFlag;      //Unit price flag
 boolean volFlag;        //Amount flag
 boolean nameFlag;       //Brand Name flag

 String str;             //Character string of element contents
 StringBuffer buffer;    //buffer for character string connections of element contents

 //start notice event of XML
 public void startDocument(){
   tvPrice = 0;
   radioPrice = 0;
   videoPrice = 0;
   tvNum = 0;
   radioNum = 0;
   videoNum = 0;
   tvFlag = false;
   radioFlag = false;
   videoFlag = false;
   tankaFlag = false;
   volFlag = false;
   nameFlag = false;
 }

 //end notice event of XML
 public void endDocument(){
   int sum = tvNum * tvPrice + radioNum * radioPrice +
       videoNum * videoPrice;
   System.out.println(sum + " yen in total.");
 }

 //element start (a start of a tag) notice event
 public void startElement(String nameSpace, String localName,
     String modName, Attributes attr){
   buffer = new StringBuffer();
   if(modName.equals("Unit_Price")){
     tankaFlag = true;
   }
   if(modName.equals("Amount")){
     volFlag = true;
   }
   if(modName.equals("Brand_Name")){
     nameFlag = true;
   }
 }

 //element end (the end of a tag) notice event
 public void endElement(String nameSpace, String localName,
     String modName){
   str = buffer.toString();
   if(nameFlag == true){
     if(str.equals("Television")){
       tvFlag = true;
     }
     if(str.equals("Radio")){
       radioFlag = true;
     }
     if(str.equals("Video")){
       videoFlag = true;
     }
   }else if(tvFlag == true){
     if(tankaFlag == true){
       //set unit price of television
       tvPrice = Integer.parseInt(str);
     }else if(volFlag == true){
       //set amount of television
       tvNum = Integer.parseInt(str);
     }
   }else if(radioFlag == true){
     if(tankaFlag == true){
       //set unit price of radio
       radioPrice = Integer.parseInt(str);
     }else if(volFlag == true){
       //set amount of radio
       radioNum = Integer.parseInt(str);
     }
   }else if(videoFlag == true){
     if(tankaFlag == true){
       //set unit price of video
       videoPrice = Integer.parseInt(str);
     }else if(volFlag == true){
       //set amount of video
       videoNum = Integer.parseInt(str);
     }
   }
   if(modName.equals("Unit_Price")){
     tankaFlag = false;
   }
   if(modName.equals("Amount")){
     volFlag = false;
   }
   if(modName.equals("Brand_Name")){
     nameFlag = false;
   }
   if(modName.equals("Merchandise")){
     tvFlag = false;
     radioFlag = false;
     videoFlag = false;
   }
 }

 //notice of character string event
 public void characters(char[] ch, int start, int length){
   buffer.append(ch, start, length);
 }
}

5.5.5 Execution Result of the Sample Program (SampleSAX.java)

The execution result of this sample program is output to the standard output. The following shows the content of the standard output:

$  The total is 315000 yen.

5.6 Sample Program that Uses the XML Schema

This section describes a sample program that uses an XML Schema.

The sample program is provided only in Windows.

The installation folder and file name of the sample program are as follows.

Installation folder:

installation-folder-of-Cosminexus-XML-Processor\samples\XMLSchema

File name:

purchaseOrder.xml

purchaseOrder-fail.xml

purchaseOrder.xsd

personalData.xsd

SampleValidateDOM.java

SampleValidateSAX.java

Organization of this section

5.6.1 Processing Performed by the Sample Program

5.6.2 XML Document to Use (purchaseOrder.xml and purchaseOrder-fail.xml)

5.6.3 Schema Documents to Use (purchaseOrder.xsd, personalData.xsd)

5.6.4 Sample Program When Using the DOM parser

5.6.5 Sample Program When Using the SAX Parser

5.6.1 Processing Performed by the Sample Program

The sample program validates a purchase order created as an XML document. Because the purchase order uses the shared customer personal data, the schema document of the purchase order reads the schema document of the personal data. Note that the schema documents are identified in the Java program.

The following figure shows the flow of processing of the sample program that uses the XML Schema.

Figure 5-4 Flow of processing of the sample program that uses the XML schema

The sample program performs the following processing:

The program reads the schema document purchaseOrder.xsd.
PurchaseOrder.xsd is the schema document that defines the product purchase order.

PurchaseOrder.xsd reads the schema document personalData.xsd.
PersonalData.xsd is the schema document for defining the personal data of the customers who place an order and has a different namespace than purchaseOrder.xsd.

The program reads the XML document purchaseOrder.xml (or purchaseOrder-fail.xml).
PurchaseOrder.xml or purchaseOrder-fail.xml is the XML document for the purchase order to be validated.

The program validates the XML document.
If the XML document is valid against the schema document, the standard output displays Validation OK. If not valid, the standard output displays Validation NG with a message.

5.6.2 XML Document to Use (purchaseOrder.xml and purchaseOrder-fail.xml)

Cosminexus XML Processor provides the following types of XML documents for validation by the XML Schema:

XML document that is validated successfully (purchaseOrder.xml)

XML document that fails validation (purchaseOrder-fail.xml)

Organization of this subsection

(1) XML document (purchaseOrder.xml)

(2) XML document (purchaseOrder-fail.xml)

(1) XML document (purchaseOrder.xml)

The following shows an XML document (purchaseOrder.xml) that is validated successfully.

<?xml version="1.0"?>
<po:purchaseOrder
   xmlns:po="http://www.myshopping.com/schema/purchaseOrder"
   xmlns:psd="http://www.myshopping.com/schema/personalData">
 <po:shipTo age="20">
   <psd:firstName>John</psd:firstName>
   <psd:familyName>Doe</psd:familyName>
   <psd:occupation>accountant</psd:occupation>
   <psd:email>johnD@bpl.com</psd:email>
   <psd:tel>050-1234-1234</psd:tel>
   <psd:address country="US">
     <psd:street>Universal street 100</psd:street>
     <psd:city>Carson</psd:city>
     <psd:state>Nevada</psd:state>
     <psd:zip>10-456</psd:zip>
   </psd:address>
 </po:shipTo>
 <po:billTo age="20">
   <psd:firstName>Jane</psd:firstName>
   <psd:familyName>Doe</psd:familyName>
   <psd:occupation>lawyer</psd:occupation>
   <psd:email>janeD@bpl.com</psd:email>
   <psd:tel>033-1111-2345</psd:tel>
   <psd:address country="US">
     <psd:street>Times Square 555</psd:street>
     <psd:city>New York</psd:city>
     <psd:state>New York</psd:state>
     <psd:zip>155-5600</psd:zip>
   </psd:address>
   <po:credit year="2007" month="10">
     <po:creditHolder>Jane Doe</po:creditHolder>
     <po:creditNumber>1111444422229999</po:creditNumber>
     <po:creditCompany>CardCompanyA</po:creditCompany>
   </po:credit>
 </po:billTo>
 <po:items>
   <po:item>
     <po:productName
         productID="DTPC2000S">DeskTop PC</po:productName>
     <po:quantity>1</po:quantity>
     <po:price>1500</po:price>
     <po:shipDate>2004-05-20</po:shipDate>
   </po:item>
   <po:item>
     <po:productName
         productID="DC500MP">Digital Camera</po:productName>
     <po:quantity>1</po:quantity>
     <po:price>450</po:price>
     <po:shipDate>2004-05-20</po:shipDate>
   </po:item>
   <po:item>
     <po:productName
         productID="LP800S">Printer</po:productName>
     <po:quantity>1</po:quantity>
     <po:price>200</po:price>
     <po:shipDate>2004-05-20</po:shipDate>
   </po:item>
 </po:items>
</po:purchaseOrder>

(2) XML document (purchaseOrder-fail.xml)

The following shows a fragment of an XML document (purchaseOrder-fail.xml) that fails validation.

        ...
        ...
   <po:credit year="2007" month="10">
     <po:creditHolder>Jane Doe</po:creditHolder>
     <po:creditNumber>111144442222999955</po:creditNumber>
     <po:creditCompany>CardCompanyA</po:creditCompany>
   </po:credit>
        ...
        ...

This XML document is identical with the one described in 5.6.2 (1) XML document (purchaseOrder.xml) except for the definition of the credit number starting with <po:creditNumber>. An 18-digit number is used as the value for the credit number starting with <po:creditNumber>. However, the sample schema document defines the credit number as 16 digits, resulting in an error at the time of validation.

5.6.3 Schema Documents to Use (purchaseOrder.xsd, personalData.xsd)

This sample uses purchaseOrder.xsd and personalData.xsd as the schema documents.

Organization of this subsection

(1) Relation between namespaces in schema documents

(2) Schema document (purchaseOrder.xsd)

(3) Schema document (personalData.xsd)

(1) Relation between namespaces in schema documents

The following figure shows the relation among namespaces in purchaseOrder.xsd and personalData.xsd. Each arrow indicates the target namespace in which the type definition or element to be referred to is defined.

Figure 5-5 Relation among namespaces in the schema documents

(2) Schema document (purchaseOrder.xsd)

The following shows the schema document to use (purchaseOrder.xsd):

<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 targetNamespace="http://www.myshopping.com/schema/purchaseOrder"
 xmlns:po="http://www.myshopping.com/schema/purchaseOrder"
 xmlns:psd="http://www.myshopping.com/schema/personalData">

<xsd:import
 namespace="http://www.myshopping.com/schema/personalData"
 schemaLocation="personalData.xsd"/>

<xsd:element name="purchaseOrder" type="po:purchaseOrderType"/>
<xsd:element name="shipTo" type="psd:personalDataType"/>
<xsd:element name="billTo" type="po:billToPersonalDataType"/>
<xsd:element name="items" type="po:itemsType">
 <xsd:key name="productID_unique">
   <xsd:selector xpath="po:item/po:productName"/>
   <xsd:field xpath="@productID"/>
 </xsd:key>
</xsd:element>

<xsd:element name="item" type="po:itemType"/>
<xsd:element name="productName" type="po:productNameType"/>
<xsd:element name="quantity">
 <xsd:simpleType>
   <xsd:restriction base="xsd:positiveInteger">
     <xsd:maxExclusive value="100"/>
   </xsd:restriction>
 </xsd:simpleType>
</xsd:element>

<xsd:element name="price" type="xsd:positiveInteger"/>
<xsd:element name="shipDate" type="xsd:date"/>
<xsd:element name="credit" type="po:creditType"/>
<xsd:element name="creditHolder" type="xsd:string"/>
<xsd:element name="creditNumber">
 <xsd:simpleType>
   <xsd:restriction base="xsd:string">
     <xsd:pattern value="\d{16}"/>
   </xsd:restriction>
 </xsd:simpleType>
</xsd:element>

<xsd:element name="creditCompany">
 <xsd:simpleType>
   <xsd:restriction base="xsd:string">
     <xsd:enumeration value="CardCompanyA"/>
     <xsd:enumeration value="CardCompanyB"/>
     <xsd:enumeration value="CardCompanyC"/>
     <xsd:enumeration value="CardCompanyD"/>
   </xsd:restriction>
 </xsd:simpleType>
</xsd:element>

<xsd:complexType name="purchaseOrderType">
 <xsd:sequence>
   <xsd:element ref="po:shipTo"/>
   <xsd:element ref="po:billTo"/>
   <xsd:element ref="po:items"/>
 </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="billToPersonalDataType">
 <xsd:sequence>
   <xsd:group ref="psd:personalDataGroup"/>
   <xsd:element ref="po:credit"/>
 </xsd:sequence>
 <xsd:attributeGroup ref="psd:personalAttributeGroup"/>
</xsd:complexType>

<xsd:complexType name="itemsType">
 <xsd:sequence>
   <xsd:element ref="po:item"
       minOccurs="0" maxOccurs="unbounded"/>
 </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="itemType">
 <xsd:sequence>
   <xsd:element ref="po:productName"/>
   <xsd:element ref="po:quantity"/>
   <xsd:element ref="po:price"/>
   <xsd:element ref="po:shipDate"/>
 </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="productNameType">
 <xsd:simpleContent>
   <xsd:extension base="xsd:string">
     <xsd:attribute name="productID" type="xsd:string"/>
   </xsd:extension>
 </xsd:simpleContent>
</xsd:complexType>

<xsd:complexType name="creditType">
 <xsd:sequence>
   <xsd:element ref="po:creditHolder"/>
   <xsd:element ref="po:creditNumber"/>
   <xsd:element ref="po:creditCompany"/>
 </xsd:sequence>
 <xsd:attribute name="year" type="po:yearType" use="required"/>
 <xsd:attribute name="month" type="po:monthType" use="required"/>
</xsd:complexType>

<xsd:simpleType name="yearType">
 <xsd:annotation>
   <xsd:documentation>
     Year set from 2004 to 2008
   </xsd:documentation>
 </xsd:annotation>
 <xsd:restriction base="xsd:string">
   <xsd:pattern value="200[4-8]"/>
 </xsd:restriction>
</xsd:simpleType>

<xsd:simpleType name="monthType">
 <xsd:restriction base="xsd:string">
   <xsd:pattern value="0[1-9]|1[0-2]"/>
 </xsd:restriction>
</xsd:simpleType>

</xsd:schema>

(3) Schema document (personalData.xsd)

The following shows the schema document to use (personalData.xsd):

<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 targetNamespace="http://www.myshopping.com/schema/personalData"
 xmlns:psd="http://www.myshopping.com/schema/personalData">

<xsd:element name="personalData" type="psd:personalDataType"/>
<xsd:element name="firstName" type="xsd:string"/>
<xsd:element name="familyName" type="xsd:string"/>
<xsd:element name="occupation" type="xsd:string"/>
<xsd:element name="email" type="xsd:string"/>
<xsd:element name="tel" type="xsd:string"/>
<xsd:element name="address" type="psd:addressType"/>
<xsd:element name="building" type="xsd:string"/>
<xsd:element name="street" type="xsd:string"/>
<xsd:element name="city" type="xsd:string"/>
<xsd:element name="state" type="xsd:string"/>
<xsd:element name="zip" type="xsd:string"/>

<xsd:complexType name="personalDataType">
 <xsd:group ref="psd:personalDataGroup"/>
 <xsd:attributeGroup ref="psd:personalAttributeGroup"/>
</xsd:complexType>

<xsd:group name="personalDataGroup">
 <xsd:sequence>
   <xsd:element ref="psd:firstName"/>
   <xsd:element ref="psd:familyName"/>
   <xsd:element ref="psd:occupation"/>
   <xsd:element ref="psd:email"/>
   <xsd:element ref="psd:tel"/>
   <xsd:element ref="psd:address"/>
 </xsd:sequence>
</xsd:group>

<xsd:attributeGroup name="personalAttributeGroup">
 <xsd:attribute name="age"
     type="xsd:positiveInteger" use="optional"/>
 <xsd:attribute name="company"
     type="xsd:string" use="optional"/>
 <xsd:attribute name="department"
     type="xsd:string" use="optional"/>
 <xsd:attribute name="title"
     type="xsd:string" use="optional"/>
 <xsd:attribute name="fax"
     type="xsd:string" use="optional"/>
</xsd:attributeGroup>

<xsd:complexType name="addressType">
 <xsd:sequence>
   <xsd:element ref="psd:building" minOccurs="0"/>
   <xsd:element ref="psd:street"/>
   <xsd:element ref="psd:city"/>
   <xsd:element ref="psd:state"/>
   <xsd:element ref="psd:zip"/>
 </xsd:sequence>
 <xsd:attribute name="country" type="xsd:string"
     use="optional" default="US"/>
</xsd:complexType>
</xsd:schema>

5.6.4 Sample Program When Using the DOM parser

This section describes a sample program for validating XML documents using the DOM parser, how the sample program is executed, and the execution results.

Organization of this subsection

(1) Sample program (SampleValidateDOM.java)

(2) Execution result of the sample program

(1) Sample program (SampleValidateDOM.java)

The following shows the sample program (SampleValidateDOM.java) when using the DOM parser:

import javax.xml.parsers.*;
import org.w3c.dom.*;
import org.xml.sax.*;
import java.io.*;

public class SampleValidateDOM implements ErrorHandler{
 public static final void main(String[] argv){
   if (argv.length != 2) {
     System.out.println(
       "Usage: java SampleValidateDOM <xml_file> <schema_file>");
     System.exit(1);
   }

   try{
     DocumentBuilderFactory dbf =
       DocumentBuilderFactory.newInstance();
     dbf.setNamespaceAware(true);
     dbf.setValidating(true);
     dbf.setAttribute(
       "http://java.sun.com/xml/jaxp/properties/schemaLanguage",
       "http://www.w3.org/2001/XMLSchema");
     dbf.setAttribute(
       "http://java.sun.com/xml/jaxp/properties/schemaSource",
       argv[1]);

     DocumentBuilder db = dbf.newDocumentBuilder();
     db.setErrorHandler(new SampleValidateDOM());
     Document doc = db.parse(argv[0]);
     System.out.println("Validation OK");

   }catch(ParserConfigurationException e){
     e.printStackTrace();
   }catch(SAXParseException e){
     e.printStackTrace();
   }catch(SAXException e){
     System.out.println("Validation NG: " + e.getMessage());
   }catch(IOException e){
     e.printStackTrace();
   }
 }

 public void warning(SAXParseException exception)
     throws SAXException {
   System.out.println("**Parsing Warning**\n" +
       "  Line:    " +
       exception.getLineNumber() + "\n" +
       "  URI:     " +
       exception.getSystemId() + "\n" +
       "  Message: " +
       exception.getMessage());
 }

 public void error(SAXParseException exception)
     throws SAXException {
   System.out.println("**Parsing Error**\n" +
       "  Line:    " +
       exception.getLineNumber() + "\n" +
       "  URI:     " +
       exception.getSystemId() + "\n" +
       "  Message: " +
       exception.getMessage());
   throw new SAXException("Error encountered");
 }

 public void fatalError(SAXParseException exception)
     throws SAXException {
   System.out.println("**Parsing Fatal Error**\n" +
       "  Line:    " +
       exception.getLineNumber() + "\n" +
       "  URI:     " +
       exception.getSystemId() + "\n" +
       "  Message: " +
       exception.getMessage());
   throw new SAXException("Fatal Error encountered");
 }
}

(2) Execution result of the sample program

The execution result of this sample program is output to the standard output. The following shows the content of the standard output:

When purchaseOrder.xml is specified for validation

Validation OK

When purchaseOrder-fail.xml is specified for validation

**Parsing Error**
 Line:    33
 URI:     file:///folder-where-sample-is-stored/purchaseOrder-fail.xml
 Message: KECX06063-E cvc-pattern-valid: Value '111144442222999955' is not facet-valid with respect to pattern '\d{16}' for type '#AnonType_creditNumber'.
Validation NG: Error encountered

5.6.5 Sample Program When Using the SAX Parser

This section describes a sample program for validating XML documents using the SAX parser, how the sample program is executed, and the execution result.

Organization of this subsection

(1) Sample program (SampleValidateSAX.java)

(2) Execution result of the sample program

(1) Sample program (SampleValidateSAX.java)

The following shows the sample program (SampleValidateSAX.java) when using the SAX parser:

import javax.xml.parsers.*;
import org.xml.sax.*;
import java.io.*;

public class SampleValidateSAX implements ErrorHandler{
 public static final void main(String[] argv){
   if (argv.length != 2) {
     System.out.println(
       "Usage: java SampleValidateSAX <xml_file> <schema_file>");
     System.exit(1);
   }

   try{
     SAXParserFactory spf = SAXParserFactory.newInstance();
     spf.setNamespaceAware(true);
     spf.setValidating(true);
     SAXParser sp = spf.newSAXParser();
     sp.setProperty(
       "http://java.sun.com/xml/jaxp/properties/schemaLanguage",
       "http://www.w3.org/2001/XMLSchema");
     sp.setProperty(
       "http://java.sun.com/xml/jaxp/properties/schemaSource",
       argv[1]);

     XMLReader reader = sp.getXMLReader();
     reader.setErrorHandler(new SampleValidateSAX());
     reader.parse(argv[0]);
     System.out.println("Validation OK");

   }catch(ParserConfigurationException e){
     e.printStackTrace();
   }catch(SAXParseException e){
     e.printStackTrace();
   }catch(SAXException e){
     System.out.println("Validation NG: " + e.getMessage());
   }catch(IOException e){
     e.printStackTrace();
   }
 }

 public void warning(SAXParseException exception)
     throws SAXException {
   System.out.println("**Parsing Warning**\n" +
       "  Line:    " +
       exception.getLineNumber() + "\n" +
       "  URI:     " +
       exception.getSystemId() + "\n" +
       "  Message: " +
       exception.getMessage());
 }

 public void error(SAXParseException exception)
     throws SAXException{
   System.out.println("**Parsing Error**\n" +
       "  Line:    " +
       exception.getLineNumber() + "\n" +
       "  URI:     " +
       exception.getSystemId() + "\n" +
       "  Message: " +
       exception.getMessage());
   throw new SAXException("Error encountered");
 }

 public void fatalError(SAXParseException exception)
     throws SAXException {
   System.out.println("**Parsing Fatal Error**\n" +
       "  Line:    " +
       exception.getLineNumber() + "\n" +
       "  URI:     " +
       exception.getSystemId() + "\n" +
       "  Message: " +
       exception.getMessage());
   throw new SAXException("Fatal Error encountered");
 }
}

(2) Execution result of the sample program

The execution result of this sample program is output to the standard output. The following shows the content of the standard output:

When purchaseOrder.xml is specified for validation

Validation OK

When purchaseOrder-fail.xml is specified for validation

**Parsing Error**
 Line:    33
 URI:     file:///folder-where-sample-is-stored/purchaseOrder-fail.xml
 Message: KECX06063-E cvc-pattern-valid: Value '111144442222999955' is not facet-valid with respect to pattern '\d{16}' for type '#AnonType_creditNumber'.
Validation NG: Error encountered

5.7 Sample Program that Uses the XSLT Transformer

This section describes a sample program that uses the XSLT transformer.

The sample program is provided only in Windows.

The installation folder and file name of the sample program are as follows.

Installation folder:

installation-folder-of-Cosminexus-XML-Processor\samples\XSLT

File name:

SampleXSLT.xml

SampleXSLT.xsl

SampleXSLT.java

Organization of this section

5.7.1 Processing Performed by the Sample Program

5.7.2 General Procedure for Creating the Sample Program

5.7.3 XML Document to Use (SampleXSLT.xml)

5.7.4 XSL File to Use (SampleXSLT.xsl)

5.7.5 Sample Program (SampleXSLT.java)

5.7.6 Execution Result of the Sample Program (SampleXSLT.java)

5.7.1 Processing Performed by the Sample Program

The sample program performs the following processing:

The program reads the source XML document.

Next, the program transforms the XML document read in step1. into HTML data.

5.7.2 General Procedure for Creating the Sample Program

The following figure shows the general procedure for creating a sample program that uses the XSLT transformer.

Figure 5-6 General procedure for creating a sample program that uses the XSLT transformer

Get the TransformerFactory instance.
Get the TransformerFactory instance using the newInstance method.

Create a Transformer object.

Transform into HTML data.
Transform the XML document into HTML data by using the Transformer object.

5.7.3 XML Document to Use (SampleXSLT.xml)

The following shows the XML document read by the sample program.

<?xml version="1.0" encoding="Shift_JIS"?>
<?xml-stylesheet type="text/xsl" href="SampleXSLT.xsl" ?>
<START>
 <Payment_Slip>
   <Merchandise>
     <Brand_Name>Television</Brand_Name>
     <Unit_Price>15000</Unit_Price>
     <Amount>14</Amount>
   </Merchandise>
   <Merchandise>
     <Brand_Name>Radio</Brand_Name>
     <Unit_Price>3500</Unit_Price>
     <Amount>6</Amount>
   </Merchandise>
   <Merchandise>
     <Brand_Name>Video</Brand_Name>
     <Unit_Price>21000</Unit_Price>
     <Amount>4</Amount>
   </Merchandise>
 </Payment_Slip>
</START>

5.7.4 XSL File to Use (SampleXSLT.xsl)

The following shows the XSL file read by the sample program.

<?xml version="1.0" encoding="Shift_JIS"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   version="1.0">
 <xsl:output method="html" indent="yes" encoding="Shift_JIS"/>

 <xsl:template match="/">
   <xsl:apply-templates />
 </xsl:template>

 <!-- start conversion for START as a root -->
 <xsl:template match="START">
   <HTML>
     <HEAD>
       <TITLE>Display XML at a table of HTML</TITLE>
     </HEAD>
     <BODY BGCOLOR="#C0C0C0">
     <FONT SIZE="5">Ordering Payment Slip</FONT>
     <TABLE BORDER="2">
     <TR><TH>Brand_Name</TH><TH>Unit_Price</TH>
         <TH>Amount</TH><TH>Subtotal</TH></TR>
     <xsl:apply-templates />
     <TR><TH>Total</TH><TD>&#160;</TD><TD>&#160;</TD>
     <TD ALIGN="RIGHT"><xsl:value-of
         select="(//Merchandise[1]/Unit_Price * //Merchandise[1]/Amount +
                  //Merchandise[2]/Unit_Price * //Merchandise[2]/Amount +
                  //Merchandise[3]/Unit_Price * //Merchandise[3]/Amount)" /></TD></TR>
     </TABLE>
     </BODY>
   </HTML>
 </xsl:template>

 <xsl:template match="Payment_Slip">
   <xsl:apply-templates />
 </xsl:template>

 <!-- make one line with one merchandise, and output a subtotal -->
 <xsl:template match="Merchandise">
   <TR><xsl:apply-templates />
   <TD ALIGN="RIGHT">
       <xsl:value-of select="number(Unit_Price)*number(Amount)" />
   </TD></TR>
 </xsl:template>

 <!-- output a brand name -->
 <xsl:template match="Brand_Name">
   <TD><xsl:value-of select="."/></TD>
 </xsl:template>

 <!-- output unit price -->
 <xsl:template match="Unit_Price">
   <TD ALIGN="RIGHT"><xsl:value-of select="."/></TD>
 </xsl:template>

 <!-- output amount -->
 <xsl:template match="Amount">
   <TD ALIGN="RIGHT"><xsl:value-of select="."/></TD>
 </xsl:template>
</xsl:stylesheet>

5.7.5 Sample Program (SampleXSLT.java)

The following shows the sample program:

import java.io.*;
import javax.xml.transform.*;
import javax.xml.transform.stream.*;
import javax.xml.parsers.*;

public class SampleXSLT{
 public static void main(String[] args){

   try{
     File file = new File(args[0]);

     //read XML file
     Source source  = new StreamSource(file);
     Result result = new StreamResult(System.out);
     TransformerFactory factory =
         TransformerFactory.newInstance();

     //convert to HTML file
     Source style = factory.getAssociatedStylesheet(source,
         null, null, null);

     Transformer transformer = factory.newTransformer(style);
     transformer.transform(source, result);

   }catch(TransformerConfigurationException e){
     e.printStackTrace();
   }catch(TransformerException e){
     e.printStackTrace();
   }
 }
}

5.7.6 Execution Result of the Sample Program (SampleXSLT.java)

Organization of this subsection

(1) Execution result of the sample program

(1) Execution result of the sample program

The execution result of this sample program is output to the standard output. The following shows the content of the standard output:

<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=Shift_JIS">
<TITLE>Display XML at a table of HTML</TITLE>
</HEAD>
<BODY BGCOLOR="#C0C0C0">
<FONT SIZE="5">Ordering Payment Slip</FONT>
<TABLE BORDER="2">
<TR>
<TH>Brand_Name</TH><TH>Unit_Price</TH><TH>Amount</TH><TH>Subtotal</TH>
</TR>
<TR>
<TD>Television</TD>
     <TD ALIGN="RIGHT">15000</TD>
     <TD ALIGN="RIGHT">14</TD>
   <TD ALIGN="RIGHT">210000</TD>
</TR>
<TR>
<TD>Radio</TD>
     <TD ALIGN="RIGHT">3500</TD>
     <TD ALIGN="RIGHT">6</TD>
   <TD ALIGN="RIGHT">21000</TD>
</TR>
<TR>
<TD>Video</TD>
     <TD ALIGN="RIGHT">21000</TD>
     <TD ALIGN="RIGHT">4</TD>
   <TD ALIGN="RIGHT">84000</TD>
</TR>
<TR>
<TH>Total</TH><TD>&nbsp;</TD><TD>&nbsp;</TD><TD ALIGN="RIGHT">315000</TD>
</TR>
</TABLE>
</BODY>
</HTML>

5.8 Sample Program that Uses the XSLTC Transformer

This section describes a program that uses the XSLTC transformer.

The section provides a method for using the XSLTC transformer function by changing the sample program described in 5.7 Sample Program that Uses the XSLT Transformer.

The following figure shows the changes to the program to enable use of the XSLTC transformer function. The changes shown in this figure make the XSLTC transformer function available. The method for executing the program and the execution result are identical to the sample program for using XSLT transformers. For details, see 5.7.6 Execution Result of the Sample Program (SampleXSLT.java).

Note

Do not change the file name even if you change the program. Compilation fails if the file name is changed.

Figure 5-7 Changes to the program to enable use of the XSLTC transformer function

The following describes the changes to the program. Each item number corresponds to the number in the comments in the program.

Import the package to use the XSLTC transformer function.

Apply the newInstance method to the TransformerFactoryXSLTC class and generate the TransformerFactory object.

6. Notes on Using Cosminexus XML Processor

This chapter gives cautionary notes on using Cosminexus XML Processor.

Organization of this chapter

6.1 Notes common to JAXP1.4 functions

6.2 Notes on the DOM Parser

6.3 Notes on the SAX Parser

6.4 Notes on StAX

6.5 Notes on the Schema Validation

6.6 General Notes on XSLT and XSLTC

6.7 Notes on XSLT

6.8 Notes on XSLTC

6.9 Notes on the javax.xml.datatype Package

6.10 Notes on the javax.xml.validation Package

6.11 Notes on the javax.xml.xpath Package

6.12 Notes on the org.w3c.dom Package

6.13 Notes on the org.w3c.dom.bootstrap Package

6.14 Notes on the org.w3c.dom.ls Package

6.15 Notes on the org.xml.sax.ext Package

6.16 Notes on XInclude

6.17 Notes on implementation-dependent specifications

6.18 Precautions related to the schema cache functionality

6.19 Notes on the high-speed parse support function

6.20 Notes on JAXB

6.21 General XML Processor related notes

6.1 Notes common to JAXP1.4 functions

The following table gives general notes on JAXP 1.4:

Table 6-1 General notes on JAXP 1.4

No.
Notes

1
For some methods in the JAXP 1.4 specification, the behavior when an argument is set to null is not defined. Note that if you specify null for an argument of these methods, they might result in undefined behavior, including a NullPointerException.

2
If an exception occurs in one of the methods defined in the JAXP 1.4 specification, applying the getMessage method to the exception object can often provide detailed messages. However, you cannot always get detailed messages. Therefore, in the application, proper processing must be executed according to the exception type instead of the exception handling dependent on the content of detailed messages. For example, in case of a DOMException, determine the detailed cause of the error by using the code field.

3
Specify the correct format for URIs to be specified in the arguments of the parse(String uri) method of the DocumentBuilder class and parse(String uri, ...) method of the SAXParser class. If you specify an invalid string as URI, a RuntimeException exception, such as IllegalArgumentException might occur.

4
The File object to be specified in the arguments of the parse(File f) method of the DocumentBuilder class and parse(File f, ...) method of the SAXParser class must be generated by a File constructor that does not include a percent sign (%), hash mark (#), or question mark (?) in the arguments. If you specify a File object generated by the File constructor that contains these characters in its arguments, the following phenomena might occur:

Occurrence of a RuntimeException exception, such as IllegalArgumentException

Occurrence of a SAXException exception

The operations of the XML parser are invalid

5
Unify the encoding of XML documents, encoding of the pseudo attribute of the XML declaration, and encoding of InputSource and Reader. Only operations with unified encoding are guaranteed.

When you use JAXP1.4, you cannot use the classes and methods listed in the following table.

Table 6-2 Classes and methods not supported in JAXP1.4

No. | Package name | Class name | Method name
1 | javax.xml.stream | XMLEventFactory | newInstance(String, ClassLoader)
2 | XMLInputFactory | newInstance(String, ClassLoader)
3 | XMLOutputFactory | newInstance(String, ClassLoader)

Also, you can only specify the factory class names described in the table for the methods listed in the following table. The operations might not function normally, if other factory class names are specified.

Table 6-3 Factory-generating methods and specifiable factory class names

No. | Package name | Class name | Method name | Specifiable factory class name
1 | javax.xml.datatype | DatatypeFactory | newInstance(String, ClassLoader) | com.cosminexus.jaxp.impl.parsers.jaxp.datatype.DatatypeFactoryImp
2 | javax.xml.parsers | DocumentBuilderFactory | newInstance(String, ClassLoader) | com.cosminexus.jaxp.impl.parsers.jaxp.DocumentBuilderFactoryImpl
3 | SAXParserFactory | newInstance(String, ClassLoader) | com.cosminexus.jaxp.impl.parsers.jaxp.SAXParserFactoryImpl
4 | javax.xml.stream | XMLEventFactory | newFactory(String, ClassLoader) | com.cosminexus.stax.xml.stream.events.ZephyrEventFactory
5 | XMLInputFactory | newFactory(String, ClassLoader) | com.cosminexus.stax.xml.stream.ZephyrParserFactory
6 | XMLOutputFactory | newFactory(String, ClassLoader) | com.cosminexus.stax.xml.stream.ZephyrWriterFactory
7 | javax.xml.transform | TransformerFactory | newInstance(String, ClassLoader) | com.cosminexus.jaxp.impl.transform.processor.TransformerFactoryImpl
8 | javax.xml.validation | SchemaFactory | newInstance(String, String, ClassLoader) | com.cosminexus.jaxp.impl.parsers.jaxp.validation.XMLSchemaFactory
9 | javax.xml.xpath | XPathFactory | newInstance(String, String, ClassLoader) | com.cosminexus.jaxp.impl.xpath.jaxp.XPathFactoryImpl

Organization of this section

6.1.1 Range supported in the javax.xml.transform.stax.StAXSource class and the javax.xml.transform.stax.StAXResult class

6.1.2 Other notes

6.1.1 Range supported in the javax.xml.transform.stax.StAXSource class and the javax.xml.transform.stax.StAXResult class

In version 08-50 and later versions of Cosminexus XML Processor, you can use the javax.xml.transform.stax.StAXSource class and javax.xml.transform.stax.StAXResult class.

Some of the methods defined in JAXP 1.4 and JAXB use the javax.xml.transform.stax.StAXSource class and the javax.xml.transform.stax.StAXResult class, or the FEATURE field of these classes as arguments. However, some of the methods are not supported. The following table describes the status of support.

Table 6-4 Status of support for methods using StAXSource class or StAXResult class in arguments

No.
Package name
Class name
Method name
Support

1
javax.xml.transform
TransformerFactory
getAssociatedStylesheet
(Source, String, String, String)
N

2
getFeature(String)
N

3
newTemplates(Source)
Y

4
newTransformer(Source)
Y

5
Transformer
transform(Source, Result)
Y

6
javax.xml.transform.sax
SAXTransformerFactory
newTransformerHandler(Source)
N

7
newXMLFilter(Source)
Y

8
SAXSource
sourceToInputSource(Source)
N

9
TransformerHandler
setResult(Result)
Y

10
javax.xml.validation
SchemaFactory
newSchema(Source)
N

11
newSchema(Source[])
N

12
Validator
validate(Source)
Y

13
validate(Source, Result)
Y

14
javax.xml.bind
JAXB
marshal(Object, Result)
N

15
unmarshal(Source, Class<T>)
N

16
Marshaller
marshal(Object, Result)
N

17
Unmarshaller
unmarshal(Source)
N

18
unmarshal(Source, Class<T>)
N

19
javax.xml.stream
XMLOutputFactory
createXMLEventWriter(Result)
Y

20
createXMLStreamWriter(Result)
Y

21
XMLInputFactory
createXMLEventReader(Source)
Y

22
createXMLStreamReader(Source)
Y

Legend

Y: Supported.

N: Not supported.

6.1.2 Other notes

The following table describes notes other than those described for JAXP 1.4 in the previous sections.

Reference note

For related notes, see 6.4 Notes on StAX as and when required.

Table 6-5 Notes on using JAXP 1.4

No.
Notes

1
StAX does not support the Shift_JIS switch functionality.
The operations might not function properly if the Node, Source, and Result created by a DOM parser or a SAX parser, specifying the Shift_JIS switch functionality, are passed as arguments of a StAX API.

2
StAX does not support the Shift_JIS switch functionality.
The operations cannot be guaranteed if StAXSource or StAXResult is used in the I/O of the XSLT or the XSLTC transformer.

3
The following features have been added to XSLT, but Cosminexus XML Processor always returns false:

http://javax.xml.transform.stax.StAXSource/feature

http://javax.xml.transform.stax.StAXResult/feature

6.2 Notes on the DOM Parser

The following table gives cautionary notes on the DOM parser.

Table 6-6 Notes on the DOM parser

No.
Notes

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.

6.3 Notes on the SAX Parser

The following table gives cautionary notes on the SAX parser.

Table 6-7 Notes on the SAX parser

No.
Notes

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

Each thread has one SAXParserFactory instance.

Each thread exclusively accesses the SAXParserFactory instance.

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

Each thread has one SAXParser instance.

3
In multi-thread programming, the objects defined by org.xml.sax, org.xml.sax.ext, and org.xml.sax.helpers 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.

4
The SAX parser can divide single character string data into multiple character strings (chunks) and report to the application as multiple characters events. Therefore, in the ContentHandler implementation, you must be concerned that character string data might be divided.
An example of the ContentHandler implementation is coded below. In this example, the character string data is buffered each time a characters event occurs, and the character string data is considered to be ended when an endElement event is reported.

class MyHandler implements ContentHandler {
String str = null;
StringBuffer buffer = null;
:
public void startElement(String uri, String localName, String qName, Attributes atts)
throws SAXException {
buffer = new StringBuffer();
}
:
public void characters(char c[], int start, int length) throws SAXException {
buffer.append(c, start, length);
}
:

public void endElement(String uri, String name, String qname) throws SAXException {
str = buffer.toString();
}
:

5
If you generate an XMLReader by using the createXMLReader(String className) method of the XMLReaderFactory class, specify com.cosminexus.jaxp.impl.parsers.parsers.SAXParser for the className argument. An example of XMLReader generation is as follows:

XMLReader reader =
XMLReaderFactory.createXMLReader("com.cosminexus.jaxp.impl.parsers.parsers.SAXParser");

6
When an error occurs in the parse methods that take InputStream or InputSource as an argument of the SAX parser 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.

7
When you parse 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.

8
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.

9
The java.lang.IllegalStateException exception might occur, if the following conditions are satisfied:

The TypeInfoProvider object is acquired with the ValidatorHandler.getTypeInfoProvider method.

The getElementTypeInfo method is invoked for the object described in step 1 with the event handler of the endElement event of SAX.

6.4 Notes on StAX

The following table lists the notes on StAX.

Table 6-8 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:

Example 1: An exception of a type that is not described in the Javadoc exception column occurs.

The NullPointerException occurs because the operation to be performed when null is specified in an argument is not defined.

Example 2: An exception occurs because the operations to be performed when methods are invoked in an invalid order are not defined.

An XMLStreamException occurs if you invoke the writeEndDocument method before invoking the writeStartDocument method for the XMLStreamWriter interface.

Example 3: If a method is invoked with arguments that might cause a conflict, the arguments are ignored.

If you specify different element names as arguments in the createStartElement and createEndElement methods for the XMLEventFactory interface, the argument specified in the createEndElement method is ignored.

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:

The IllegalStateException exception does not occur (not described in Javadoc)

getCharacterEncodingScheme()

getEncoding ()

getVersion()

getNamespaceURI()

getNamespaceURI(String prefix)

getPrefix()

standaloneSet()

isStandalone()

The thrown exception differs from that in Javadoc (the IllegalStateException exception occurs in Javadoc)

getElementText()

nextTag()

next()

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:

getAttributeLocalName(int index)

getAttributeName(int index)

getAttributeNamespace(int index)

getAttributePrefix(int index)

getAttributeType(int index)

getAttributeValue(int index)

getNamespaceURI(int index)

isAttributeSpecified(int index)

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:

Javadoc
Acquire the text related to CHARACTERS, SPACE, or CDATA.

XMLStreamReader
The getTextCharacters method is enabled for the COMMENT event type.

Operations of Cosminexus XML Processor
The text related to the COMMENT event is acquired.

8
Condition
When all the following conditions are satisfied:

The getPrefix(String uri) method of the XMLStreamWriter interface is executed.

The namespace of the uri argument in 1. is bound to multiple prefixes.

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:

The setPrefix(String prefix, String uri) method of the XMLStreamWriter interface is executed.

The prefix of the prefix argument in 1. is already bound to a different namespace.

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:

The XML document is encoded by using UTF-16BE or UTF-16LE.

The encoding specified in the XML declaration is UTF-16.

The encoding for the XML document is obtained by using the getEncoding method of XMLStreamReader or the getCharacterEncodingScheme method of StartDocument.

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.

javax.xml.stream.allocator

javax.xml.stream.reporter

javax.xml.stream.resolver

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:

javax.xml.stream.isReplacingEntityReferences

javax.xml.stream.isSupportingExternalEntities

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:

Empty element (example: <element1/>)

The encoding attribute of the XML declaration

The standalone attribute of the XML declaration

Operations of Cosminexus XML Processor

Only the start and end tags are output for the empty element (example: <element1></element1>).

<?xml version="1.0" ?> is output for the XML declaration.

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:

Public identifiers in DTD

System identifiers in DTD

Entities to be parsed internally

Attribute value

Comments

CData

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:

For attributes specified explicitly in the XML document: true

For default attributes specified implicitly in DTD: false

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:

An XML document without an ENTITY declaration is read by using the XMLStreamReader interface and the getProperty("javax.xml.stream.notations") method of the XMLStreamReader interface is executed in the DTD event type.

An XML document without a NOTATION declaration is read by using the XMLStreamReader interface and the getProperty("javax.xml.stream.entities") method of the XMLStreamReader interface is executed in the DTD event type.

Operations of Cosminexus XML Processor
The return value is java.util.List without an element.

33
Condition
When all the following conditions are satisfied:

A DTD declaration is specified in a parameter entity definition.

The parameter entity specified in 1. is used in the DOCTYPE declaration.

The XML documents from 1. and 2. are parsed by using StAX.

The DTD declaration text is acquired by using the getText method of XMLStreamReader or by the javax.xml.stream.events.DTD interface.

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.
(Example)
com.cosminexus.stax.xml.stream.internal.xni.XNIException:
The standalone document declaration value must be "yes" or "no", not "{0}".

35
Condition
When you execute one of the following methods:

XMLStreamException.getLocation() method

XMLEvent.getLocation() method

XMLStreamReader.getLocation() method

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:

The XML document contains an element name beginning with: (colon).

The namespace for the StAX parser is enabled.

The XML document from 1. is parsed by using the StAX parser from 2.

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:

An XML document without version declaration is parsed with XMLEventReader.

The getVersion method of the StartDocument interface is executed

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:

Blank string

CDATA section

Notation declaration

Operations of Cosminexus XML Processor

The blank string becomes the CHARACTERS event type, and not the SPACE event type.

The CDATA section becomes the CHARACTERS event type and not the CDATA event type.

The NOTATION_DECLARATION event does not occur for the notation declaration.

40
Condition
When you execute the getEventType() method of the XMLStreamReader interface for the following parts in the XML document:

Blank string

CDATA section

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:

namespaceURI is not bound to a prefix.

1. is specified in the namespaceURI argument of the following method of the XMLStreamWriter interface:
writeAttribute(String prefix, String namespaceURI, String localName, String value)

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:

Attribute

Characters

Comment

DTD

EndDocument

EndElement

EntityDeclaration

EntityReference

Namespace

NotationDeclaration

ProcessingInstruction

StartDocument

StartElement

XMLEvent

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:

Each thread has one XMLOutputFactory instance.

Each thread accesses the XMLOutputFactory instance exclusively.

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:

Each thread has one XMLOutputFactory instance.

Each thread accesses the XMLOutputFactory instance exclusively.

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:

Each thread has one XMLEventFactory instance.

Each thread accesses the XMLEventFactory instance exclusively.

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:

java.io.InputStream

javax.xml.stream.XMLStreamReader

java.xml.stream.XMLEventReader

53
The return value of the getLocation() method for the following events is null:

javax.xml.stream.events.Attribute

javax.xml.stream.events.Namespace

javax.xml.stream.events.NotationDeclaration

javax.xml.stream.events.EntityDeclaration

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:

createXMLEventWriter(Result result)

createXMLStreamWriter(Result result)

55
Condition
When all the following conditions are satisfied:

true is specified for the javax.xml.stream.isRepairingNamespaces property.

One of the following methods is executed for the XMLStreamWriter interface:
writeAttribute(prefix, namespaceURI, localName, value)
writeStartElement(prefix, localName, namespaceURI)
writeEmptyElement(prefix, localName, namespaceURI)

The namespaceURI argument is the same as the default namespace URI.

The prefix argument is neither "" nor null.

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:

true is specified for the javax.xml.stream.isRepairingNamespaces property.

One of the following methods is executed for the XMLStreamWriter interface:
writeAttribute(prefix, namespaceURI, localName, value)
writeStartElement(prefix, localName, namespaceURI)
writeEmptyElement(prefix, localName, namespaceURI)

The namespaceURI argument is bound, but to a different prefix.

Standard specifications
The prefix is generated randomly.
(Example)
xmlns:{generated}="namespaceURI" {generated}:localName="value"
<{generated}:localName xmlns:{generated}="namespaceURI">

Operations of Cosminexus XML Processor
A random prefix is not generated.
(Example)
xmlns:prefix="namespaceURI" prefix:localName="value"
<prefix:localName xmlns:prefix="namespaceURI">

57
Condition
When all the following conditions are satisfied:

The javax.xml.stream.isRepairingNamespaces property is not specified, or false is specified.

The writeAttribute(prefix, namespaceURI, localName, value) method of the XMLStreamWriter interface is executed.

The namespaceURI argument is not bound.

The prefix argument is neither "" nor null.

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:

The javax.xml.stream.isRepairingNamespaces property is not specified, or false is specified.

One of the following methods of the XMLStreamWriter interface is executed:
writeAttribute(prefix, namespaceURI, localName, value)
writeStartElement(prefix, localName, namespaceURI)
writeEmptyElement(prefix, localName, namespaceURI)

The namespaceURI argument is bound, but to a different prefix.

Standard specifications
The XMLStreamException exception occurs.

Operations of Cosminexus XML Processor
There is no error. The value is written as follows:

prefix:localName="value"

<prefix:localName>

59
Condition
When all the following conditions are satisfied:

The javax.xml.stream.isRepairingNamespaces property is not specified, or false is specified.

One of the following methods of the XMLStreamWriter interface is executed:
writeAttribute(prefix, namespaceURI, localName, value)
writeStartElement(prefix, localName, namespaceURI)
writeEmptyElement(prefix, localName, namespaceURI)

The namespaceURI argument is the same as the default namespace URI.

The prefix argument is neither "" nor null.

Standard specifications
The prefix is not written.

Operations of Cosminexus XML Processor
The following prefixes are written:

prefix:localName="value"

<prefix:localName>

60
Condition
When all the following conditions are satisfied:

The javax.xml.stream.isRepairingNamespaces property is not specified, or false is specified.

The writeAttribute(prefix, namespaceURI, localName, value) method of the XMLStreamWriter interface is executed.

The namespaceURI argument is the same as the default namespace URI.

The prefix argument is "" or null.

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:

true is specified for the javax.xml.stream.isRepairingNamespaces property.

The writeEmptyElement(prefix, localName, namespaceURI) method of the XMLStreamWriter interface is executed.

The prefix argument is "".

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:

createXMLEventReader(stream, encoding)

createXMLStreamReader(stream, encoding)

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:

The getNamespaceContext() method of the StartElement event is used to obtain NamespaceContext.

The namespace URI of xml and xmlns prefixes is obtained for NamespaceContext acquired in 1.

Standard specifications

The prefix xml is bound to http://www.w3.org/XML/1998/namespace.

The prefix xmlns is bound to http://www.w3.org/2000/xmlns/.

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:

DOMSource

SAXSource

StAXSource

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:

The character data in an XML document contains an independent end of CDATA section delimiter ("]]>").
(Example)
<?xml version="1.0" encoding="UTF-8" ?>
<root>te]]>xt</root>

The character data from 1. is read by using the XMLStreamReader or XMLEventReader interface and the following syntax parsing event is acquired by using the next() method.

Standard specifications
The XMLStreamException exception is thrown from the XMLStreamReader interface or XMLEventReader interface.

Operations of Cosminexus XML Processor

For the XMLStreamReader interface

The execution result of the getTextXXXX() method that can be executed when the event type of the XMLStreamReader interface is CHARACTERS, contains ]]>.

If you execute the getText() method, a string containing ]]> is returned.

If you execute the getTextCharacters() method, an array containing '] ''] ''>' is returned.

If you execute the getTextCharacters(int sourceStart, char[] target, int targetStart, int length) method, '] ''] ''>' is included in the char array target.

If you execute the getTextLength() method, the length of the string that contains ]]> is returned.

For the XMLEventReader interface

If you execute the getData() method for the Characters object returned by the nextEvent() method, a string containing ]]> is returned.

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:

The output encoding specified in the createXMLEventWriter and createXMLStreamWriter methods of the XMLOutputFactory class is not UTF-8 or UTF-16.

An XML document containing a 2-byte code is output with the created XMLEventWriter and XMLStreamWriter.

The encoding specified for the XML document to be output satisfies either of the following conditions:
The output encoding specified in the createXMLEventWriter method of the XMLOutputFactory class does not match the encoding pseudo attribute of the output XML declaration specified in the createStartDocument method of the XMLEventFactory class.
The encoding argument is not specified in the writeStartDocument method of the XMLStreamWriter interface.

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:

Boolean.FALSE is set in the javax.xml.stream.isRepairingNamespaces property of XMLOutputFactory.

XMLStreamWriter or XMLEventWriter is created from XMLOutputFactory described in step 1.

StAXResult is created from XMLStreamWriter or XMLEventWriter described in step 2.

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:

validate(Source source, Result result) method of the javax.xml.validation.Validator class

transform(Source source, Result result) method# of the javax.xml.transform.Transformer class
# However, this method is applicable only in the case of an identity transformation without using style sheets.

Workaround
Specify Boolean.TRUE in the javax.xml.stream.isRepairingNamespaces property of XMLOutputFactory.

6.5 Notes on the Schema Validation

The following table gives cautionary notes on the schema validation.

Table 6-9 Notes on the schema validation

No.
Notes

1
To register an entity resolver with the XML parser, you must always set a system identifier for the return value, InputSource, of the resolveEntity method of the entity resolver. If you do not set the system identifier, resolution of the location of the schema document specified by xsd:import or xsd:include might fail, resulting in an error.

6.6 General Notes on XSLT and XSLTC

The following table gives general cautionary notes on XSLT and XSLTC.

Table 6-10 General notes on XSLT and XSLTC

No.
Notes

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.

Instead of XSLTC, XSLT is used as the transformer.

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.

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

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.

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.

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.

6.7 Notes on XSLT

The following subsections give cautionary notes on XSLT.

Organization of this section

6.7.1 Cases Where XSLT Does Not Report Errors

6.7.2 Other Notes

6.7.1 Cases Where XSLT Does Not Report Errors

Table 6-11 Notes on XSLT (cases where XSLT does not report errors)

No. | Notes
1 | If an expression that combines operands other than the node set with | operators is coded in the select attribute of the xsl:copy-of element, the XSLT transformer does not report the error.
2 | When the select attribute of the xsl:for-each element contains a character that is not permitted for the XPath expression, for example, ~ or #, the XSLT transformer does not report the error.
3 | If you specify a character string that does not match the QName rule for the cdata-section-elements attribute of the xsl:output element, the XSLT transformer does not report the error.
4 | If you specify an argument other than character string type for the element-available and function-available functions, the XSLT transformer does not report the error.

6.7.2 Other Notes

Table 6-12 Notes on XSLT (other notes)

No.
Notes

1
If you specify a negative value unavailable for the grouping-size attribute of the xsl:number element, grouping is carried out after transforming the value to a positive value.

2
Specify a character string other than the empty character string for the elements attribute of the xsl:preserve-space and xsl:strip-space elements.

3
If you perform transformation by using XSLT, when you specify * for the elements attribute of the xsl:strip-space or xsl:preserve-space element, elements with a namespace prefix might not be selected for the target to delete the blank spaces or to be stored. If you select an element with a namespace prefix for the target to delete the blank spaces or to be stored, specify the element name with a namespace prefix for the elements attribute.

4
Specify a format pattern that includes one or more characters for the second argument of the format-number function.

5
If you specify html for the method attribute of the output property and an element name for the cdata-section-elements attribute, the cdata-section-elements attribute is not ignored, and the content of the element specified as a CDATA section is output.

6.8 Notes on XSLTC

The following subsections provide notes on XSLTC:

Organization of this section

6.8.1 Notes on the Stylesheet Size

6.8.2 Notes on Transformation Performance

6.8.3 Notes on XSLT Elements

6.8.4 Notes on the XPath Expression

6.8.5 Cases where XSLTC Does Not Report Errors

6.8.6 Other Notes

6.8.1 Notes on the Stylesheet Size

Table 6-13 Notes on XSLTC (stylesheet size)

No.
Notes

1
XSLTC imposes an upper limit on the size of the stylesheets for processing. When processing a stylesheet that exceeds 18,000 bytes, the KECX07058-E error may occur and the processing may be aborted. However, the upper limit on the size of the stylesheet depends on the content of the stylesheet. For details on the messages, see 11. KECX (Messages Output by Cosminexus XML Processor) in the manual uCosminexus Application Server Messages.

6.8.2 Notes on Transformation Performance

Table 6-14 Notes on XSLTC (transformation performance)

No.
Notes

1
In all cases described in 3.2.1 (1) Transforming multiple XML documents by using the same XSLT stylesheet, it is not guaranteed that the transformation performance of the XSLTC transformer may be higher than that of the XSLT transformer. When using the XSLTC transformer, Hitachi recommends that you evaluate the performance with the XSLT stylesheet that is actually used and target XML document for the transformation.

6.8.3 Notes on XSLT Elements

Table 6-15 Notes on XSLTC (XSLT elements)

No.
Notes

1
The xsl:apply-imports element is not processed.

2
When the template receives a node set as the parameter by xsl:with-param and you refer to the parameter in the select attribute of the xsl:apply-templates element, you can no longer retrieve the node set even if you refer to the same parameter.

3
If the child element of the xsl:attribute element is xsl:copy, the output attribute value is null.

4
If you specify the xsl:value-of element for the content of the xsl:attribute element, write the XPath expression in the select attribute as an absolute location path.

5
If the xsl:attribute-set element refers to itself (circular reference) in the use-attribute-sets attribute, a stack overflow may occur in XSLTC.

6
If you define multiple xsl:decimal-format elements and every attribute has the same value among those elements, XSLTC reports the error.

7
Do not specify an attribute value template for the name attribute of the xsl:element or xsl:attribute element.

8
When all of the following conditions are met, the namespace to which the element belongs is invalid:

There is an xsl:attribute element as a child element of the xsl:element element.

The name attribute of the xsl:element element is named with a prefix, and the namespace attribute is specified.

The name attribute of the xsl:attribute element is named with a prefix, and the namespace attribute is specified.

The prefixes specified in the name attributes of xsl:element and xsl:attribute are identical, and their namespace attribute values are different from each other.

An example of the stylesheet that meets the above cases is as follows:

<xsl:template match="/">
<xsl:element name="child1" namespace="AAA">
<xsl:element name="A:child2" namespace="XXX">
<xsl:attribute name="A:attr" namespace="AAA">1</xsl:attribute>
</xsl:element>
</xsl:element>
</xsl:template>

9
If you specify an XPath expression with a predicate for the select attribute of the xsl:for-each element, do not specify a node-comparison expression for the predicate. In this case, modify the stylesheet as follows:

Delete the predicate from the XPath expression in the select attribute of the xsl:for-each element.

Insert the xsl:if element as a child of the xsl:for-each element, and specify the content of the predicate deleted in step 1 for the test attribute.

An example of the modification of the stylesheet is as follows:
(Before modification)

<xsl:template match="/">
<xsl:for-each select="element[sub='x']">
<xsl:value-of select="."/>
</xsl:for-each>
</xsl:template>

(After modification)

<xsl:template match="/">
<xsl:for-each select="element">
<xsl:if test="sub='x'">
<xsl:value-of select="."/>
</xsl:if>
</xsl:for-each>
</xsl:template>

10
For the select attribute of the xsl:for-each element, do not specify an XPath expression that includes descendant::node() or descendant-or-self::node(). If you want to use the XPath expression above in order to select element and text nodes, modify the stylesheet as follows:

Replace descendant::node() with descendant::node()|descendant::text().

Replace descendant-or-self::node() with descendant-or-self::node()|descendant-or-self::text().

11
For the test attribute of the xsl:if or xsl:when element, do not specify an XPath expression that has both a self axis and a predicate. In this case, modify the stylesheet as follows:

Delete the predicate from the XPath expression in the test attribute of the xsl:if or xsl:when element.

Insert the xsl:if element as a child of the xsl:if element or xsl:when element, and specify the content of the predicate deleted in step 1 for the test attribute.

An example of the modification of the stylesheet is as follows:
(Before modification)

<xsl:template match="/element/sub">
<xsl:if test="self::sub[attribute::attr='x']">
<xsl:value-of select="."/>
</xsl:if >
</xsl:template>

(After modification)

<xsl:template match="/element/sub">
<xsl:if test="self::sub">
<xsl:if test="attribute::attr='x'">
<xsl:value-of select="."/>
</xsl:if>
</xsl:if >
</xsl:template>

12
If the href attribute value of the xsl:import element is an empty character string or only blank space, an error event occurs and null is output as the error message.

13
Do not specify a pattern that includes node() in the count attribute of the xsl:number element. If you want to use node() in order to number element nodes, use * (asterisk) or the element name instead.

14
If you specify multiple whitespace (tab, space, empty character string) strings, a string of one or more characters, or double-byte characters for the grouping-separator attribute of the xsl:number or the xsl:decimal-format element, an error does not occur and the values delimited by the specified string are output.

15
If you specify / (slash) for the count attribute of the xsl:number element, 1 is output in XSLT and a java.lang.VerifyError occurs in XSLTC.

16
If you specify / (slash) for the from attribute of the xsl:number element, 1 is output in XSLT and a java.lang.VerifyError occurs in XSLTC.

17
Specify a character string other than the empty character string for the doctype-public attribute of the xsl:output element. Similarly, if you set the doctype-public property by using the setOutputProperty method of the Transformer class, specify a character string other than an empty character string.

18
If you specify XML that is unacceptable as a target name of a processing instruction for the name attribute of the xsl:processing-instruction element, an invalid processing instruction <?XML?> is output.

19
If you specify an invalid value NUMBER (uppercase) for the data-type attribute of xsl:sort, the default behavior (to sort in the same order as when text is specified) is not performed.

20
If you specify an invalid value DESCENDING (uppercase) for the order attribute of xsl:sort, the default behavior (to sort in the same order as when ascending is specified) is not performed.

21
For the match attribute of the xsl:template element, do not specify an XPath expression that includes node() and is followed by a location path. If you want to use node() in order to select element nodes, use an * (asterisk) instead. An example of the modification of the stylesheet is as follows:
(Before modification)

<xsl:template match="/node()/sub">
<result><xsl:value-of select="."/></result>
</xsl:template>

(After modification)

<xsl:template match="/*/sub">
<result><xsl:value-of select="."/></result>
</xsl:template>

22
If you code the top-level element for the child element of the xsl:template element, the top-level element is not ignored and processed as a valid child element.

23
If you code a string function that has a negative zero as the argument for the select attribute of the xsl:value-of element, 0 is output in XSLT, but -0 is output in XSLTC.

24
If you specify the xsl:call-template element for the child element of the xsl:variable element and there is a literal element with a namespace prefix in the template that is called by xsl:call-template, the namespace declaration of the element is not copied properly when you try to copy the element indicated by the variable in the xsl:copy-of element.

25
If you set an extended element by specifying the xsl:extension-element-prefixes attribute for the literal result element, the xsl:fallback element coded as a child element of the extended element may be ignored. Instead, specify the extension-element-prefixes attribute for the xsl:stylesheet element.

26
If you code a child element in an unacceptable location of the stylesheet according to the specifications (for example, when a literal element is coded as a child element of the xsl:stylesheet element or when an xsl:text element appears as a child element of the xsl:namespace-alias element), the invalid child element is ignored without an error occurring.

6.8.4 Notes on the XPath Expression

Table 6-16 Notes on XSLTC (XPath expression)

No. | Notes
1 | If you specify a document function followed by an XPath expression, use /descendant-or-self::node()/ instead of //.
2 | Do not use the current function in the top-level element.
3 | If you use the node test node() in an XPath expression, nodes cannot be obtained properly.
4 | If you code an XPath expression that combines a node test including an * (asterisk) with a logical operator as the XPath expression, an error occurs during the parsing of the XPath expression.
5 | If the value of a variable or parameter is a result tree fragment (not a value in the select attribute, but a value defined by the template that is coded as an element content), a NullPointerException may occur when there is a variable reference in the template.

6.8.5 Cases where XSLTC Does Not Report Errors

In some cases, for example, when the content of an element or attribute is invalid or when the function argument is invalid, XSLTC may not report errors. The following table lists and describes the cases where XSLTC does not report errors.

Table 6-17 Notes on XSLTC (cases where XSLTC does not report errors)

No.
Notes

1
A stylesheet element other than the xsl:sort and xsl:with-param elements is specified as a child element of the xsl:apply-templates element.

2
An empty character string is specified for the select attribute of the xsl:apply-templates element.

3
Element content other than text is specified for the xsl:comment element.

4
A value that consists of two or more characters is specified for the following attributes of the xsl:decimal-format element:

decimal-separator

grouping-separator

minus-sign

percent

per-mille

zero-digit

pattern-separator

5
An element name qualified with a prefix is specified for the name attribute of the xsl:element or xsl:attribute element, and an empty character string is specified for the namespace attribute.

6
xsl:sort is specified as a child element for an element other than the first element of the xsl:for-each element.

7
Element content is specified for the xsl:import element.

8
The xsl:import element is not the first element of the top-level element, or the xsl:import or xsl:include element is not the top-level element.

9
An XPath expression that includes the key function is specified for the use attribute of the xsl:key element.

10
An xsl:message element is specified as a child element of the xsl:stylesheet element.

11
A value other than yes or no is specified for the terminate attribute of the xsl:message element.

12
There is no namespace declaration corresponding to the prefix specified for the stylesheet-prefix or result-prefix attribute of the xsl:namespace-alias element.

13
The stylesheet-prefix or result-prefix attribute of the xsl:namespace-alias element is not specified.

14
Element content is specified for the xsl:namespace-alias element.

15
A character string that does not match the Number rule for the grouping-size attribute of the xsl:number element is specified.

16
An invalid value is specified for the lang and level attributes of the xsl:number element.

17
An invalid value is specified for the letter-value attribute of the xsl:number element.

18
A variable reference whose value is an empty character string is specified for the grouping-separator attribute of the xsl:number element.

19
An invalid value is specified for the version attribute of the xsl:output element.

20
An invalid value is specified for the indent attribute of the xsl:output element.

21
An invalid value is specified for the standalone attribute of the xsl:output element.

22
An invalid value is specified for the omit-xml-declaration attribute of the xsl:output element.

23
An empty character string is specified for the select attribute of the xsl:param element.

24
An invalid value is specified for the data-type, order, or case-order attribute of the xsl:sort element.

25
The data-type, order, or case-order attribute of the xsl:sort element is a variable reference whose value is an empty character string.

26
A value specified in uppercase for the data-type, order, or case-order attribute of the xsl:sort element is handled as specified in lowercase.

27
Element content is specified for the xsl:strip-space, xsl:preserve-space, xsl:apply-imports element, and so on which cannot have any element content according to the specifications.

28
An invalid value is specified for the version attribute of the xsl:stylesheet element.

29
The namespace URI corresponding to the prefix specified for the exclude-result-prefixes attribute of the xsl:stylesheet element is not valid for the elements that have this attribute.

30
The xsl:stylesheet element is specified in the xsl:stylesheet element.

31
An empty character string is specified in the match attribute and in the mode attribute of the xsl:template element.

32
Neither the name attribute nor the match attribute is specified for the xsl:template element.

33
An empty character string is specified for the mode attribute of the xsl:template or xsl:apply-templates element.

34
An empty character string is specified for the priority attribute of the xsl:template element.

35
A literal result element appears before the first xsl:template element.

36
The xsl:template element has a mode attribute but does not have a match attribute.

37
Multiple xsl:with-param elements have the name attribute with the same value.

38
A value other than yes or no is specified for the disable-output-escaping attribute of the xsl:text element.

39
A value other than yes or no is specified for the disable-output-escaping attribute of the xsl:value-of element.

40
An empty character string is specified for the select attribute of the xsl:variable element.

41
Both the select attribute and the text content exist in the xsl:variable or xsl:param element.

42
An empty character string is specified for the select attribute of the xsl:with-param element.

43
The number of arguments of a following function call is invalid:

number function

boolean function

lang function

concat function

44
The second argument of the document function is an empty character string.

45
An empty character string is specified for the third argument of the format-number function.

46
If a key name that does not exist is specified for the first argument of the key function.

47
If the number of arguments of the unparsed-entity-uri function is invalid.

6.8.6 Other Notes

Table 6-18 Notes on XSLTC (other notes)

No. | Notes
1 | If you use XSLTC, the default error listener throws an exception in case of an error.
2 | When the implementation of the warning or error method on the ErrorListener does not throw an exception and a warning and an error occurs while parsing the stylesheet, the transformation cannot be carried out because a translet cannot be created.
3 | The file name and line number of the file that caused the error may be output before the error ID in the error message.
4 | When the setContentHandler method of the XMLReader class is used to register (into the parser) TemplatesHandler object created by the newTemplatesHandler method of the SAXTransformerFactory class and to perform transformation, an error is not output even if a stylesheet with an error is processed.
5 | If you perform transformation by using SAXTransformerFactory, the error listener is not notified of the stylesheet error, regardless of the error listener setting.
6 | If you perform transformation by using XSLTC, a NullPointerException occurs if #default is specified for both the stylesheet-prefix and result-prefix attributes of the same xsl:namespace-alias element.
7 | If you perform transformation by using XSLTC, when two templates with different import priority have name and match attributes and also the name attributes have the same value, the template that has a lower import priority is ignored.
8 | If you perform transformation by using XSLTC, when the cdata-section-elements attribute of the output properties are set in both the stylesheet and the JAXP interface, the value defined in the stylesheet is overwritten by the value set in the JAXP interface.
9 | If you perform transformation by using XSLTC, when you use URIResolver, which is implemented to return DOMSource created from DocumentFragment, the correct transformation is not performed.
10 | If you specify the HTML output for the output method, when {name()} or {name( . )} is specified for the name attribute of the xsl:element element, the NullPointerException occurs.

6.9 Notes on the javax.xml.datatype Package

The following table gives cautionary notes on the javax.xml.datatype package.

Table 6-19 Notes on the javax.xml.datatype package

No.
Notes

1
In multi-thread programming, the objects defined by the javax.xml.datatype package are not thread-safe. Therefore, make sure that each thread exclusively accesses these objects.

2
If the IllegalArgumentException occurs in each method of the DatatypeFactory class, the parameter specified for each method is returned to the getMessage() method.

3
If you set the month field to either 4, 6, 9, or 11 in the newXMLGregorianCalendar, newXMLGregorianCalendarDate, and newXMLGregorianCalendarTime methods of the DatatypeFactory class, an error does not occur even when you set 31 in the day field.

4
Specify the value from 0 to 999 for the millisecond argument of the newXMLGregorianCalendar and newXMLGregorianCalendarTime methods of the DatatypeFactory class.

5
If you compare a Duration object whose month field has the value 1 and a Duration object whose day field has the value 28, the result is as follows:

If you compare by using the compare method, DatatypeConstants.EQUAL is returned.

If you compare by using the equals method, true is returned.

6
The Duration object created in the newDuration(long durationInMilliSeconds), newDurationDayTime(long durationInMilliSeconds), or newDurationYearMonth(long durationInMilliSeconds) method of the DatatypeFactory class is the DatatypeConstants.DURATION_DAYTIME type. Therefore, the month field and day field of this Duration object are set to 0.

7
Specify the value from 0 to 23 for the hour argument of the setHour and setTime methods of the XMLGregorianCalendar class. Also, specify a value from 0 to 23 for the time field of the argument of the newXMLGregorianCalendar and newXMLGregorianCalendarTime methods of the DatatypeFactory class.

8
In the JAXP1.4 specifications, the specifications of the isValid method of the XMLGregorianCalendar class are defined as the Validate instance by getXMLSchemaType() constraints. In Cosminexus XML Processor, true is returned when all the following constraints are met:

If the month field is 2, the day field is 28 or smaller (other than leap year) or 29 or smaller (leap year).

The year field is not 0.

9
If the argument of the equals method of the XMLGregorianCalendar class is null, a NullPointerException does not occur, but false is returned.

10
The text expression obtained by applying the toString and toXMLFormat methods to the XMLGregorianCalendar object of the DatatypeConstants.GMONTH type is not the character string --MM defined in section 3.2.14 of the specification W3C XML Schema 1.0 Part 2 (second edition), but the string --MM-- defined in the specifications prior to the second edition.

6.10 Notes on the javax.xml.validation Package

The following table gives cautionary notes on the javax.xml.validation package.

Table 6-20 Notes on the javax.xml.validation package

No.
Notes

1
In multi-thread programming, the SchemaFactory, Validator, ValidatorHandler, and TypeInfoProvider classes are not thread-safe. Therefore, make sure that each thread exclusively accesses these objects.

2
The URI "http://www.w3.org/2001/XMLSchema" is the only URI that you can specify as the argument of the newInstance(String schemaLanguage) method of the SchemaFactory class.

3
for the isSchemaLanguageSupported method of the SchemaFactory class.
Specify http://www.w3.org/2001/XMLSchema. If you specify other schema languages, this method returns false.

4
Specify a schema document with a different targetNamespace for each array element of the schemas argument for the newSchema(Source[] schemas) method of the SchemaFactory class. If you specify multiple schema documents with the same targetNamespace or with no targetNamespace, a schema document for an array element with a lower index is prioritized.

5
If you execute the newSchema(Source[] schemas) method of the SchemaFactory class under the following condition, exceptions may not occur:

Array elements for the schemas argument may include both valid schema documents and invalid ones.

To avoid this problem, use the following workaround:

Save exception objects passed to the error and fatalError methods by the error handler for the SchemaFactory object.

After calling the newSchema method, check for whether an exception object has been saved in step 1, and if it is successfully saved, throw the exception.

6
Specify any combination of arguments described in Table 6-21 of this section for validate(Source) and validate(Source, Result) in the Validator class.

7
If you use a schema document including the definition for ID type attributes to validate XML documents by using the validate method of the Validator class, use either the validate(SAXSource), validate(DOMSource), or validate(SAXSource, SAXResult) method rather than the validate(DOMSource, DOMResult) method.

8
When all of the following conditions are met, if you execute the validate(Source source, Result result) method of the Validator class, a DOMException may occur:

The result argument is a DOMResult object.

The DOM node that includes the result tree set in the DOMResult object is the Document object with child nodes.

Therefore, make sure that the Document object described in condition 2 does not have any child node.

9
If a schema document includes the xsd:ENTITY type or xsd:ENTITIES type, schema validation by using the ValidatorHandler class is not supported. In such cases, perform the schema validation by using other methods such as the Validator class.

10
If the validation fails, a TypeInfo object obtained from the element or attribute that is not defined in the schema document becomes the same as the TypeInfo object of the xsd:anyType type.

11
If you specify the DOMSource object for the Source argument of the validate(Source) and validate(Source, Result) of the Validator class, make sure that the Node object owned by the DOMSource object meets all of the following conditions:

Generated by the parser with the namespace enabled.
For example, the DocumentBuilder generated by the DocumentBuilderFactory applied with setNamespaceAware(true).

Generated by the parser without validation.
For example, the DocumentBuilder generated by the DocumentBuilderFactory applied with setValidating (false).

12
If you specify the SAXSource object for the Source argument of the validate(Source) and validate(Source, Result) of the Validator class and the SAXSource object uses the XMLReader object, the XMLReader object must meet all of the following conditions:

The object is an XMLReader object with the namespace enabled.
For example, the XMLReader object taken out of the SAXParser that is generated by the SAXParserFactory applied with setNamespaceAware(true).

The object is an XMLReader object without validation.
For example, the XMLReader object taken out of the SAXParser that is generated by the SAXParserFactory applied with setValidating (false).

13
When all of the following conditions come in succession, the exception DOMException with the exception code NO_MODIFICATION_ALLOWED_ERR might occur:

The DOMSource object is specified in the newSchema(Source) and newSchema(Source[])arguments of the SchemaFactory class, and these methods are executed.

The DOM tree wrapping the DOMSource object specified in condition 1. is updated.

14
Using the newSchema method of the javax.xml.validation.SchemaFactory class, if you want to specify a SAXSource with an XMLReader specified, the XMLReader to be specified must satisfy the following conditions:

true is specified for the value of the SAX2 feature http://xml.org/sax/features/namespace-prefixes.

15
When you specify StAXSource and StAXResult in an argument of the validate(Source, Result) method of the Validator class, specify the same encoding in StAXSource and StAXResult.

16
Condition
When the getElementTypeInfo() method of the javax.xml.validation. TypeInfoProvider class is executed in the endElement event of ContentHandler set in ValidatorHandler.

Operation of Cosminexus XML Processor
The IllegalStateException exception is thrown. The TypeInfo object is not returned.

Table 6-21 Combination of arguments of the validate(Source) and validate(Source, Result) of the Validator class

Result argument | Source argument
SAXSource | DOMSource | StreamSource | null
SAXResult | Y | N | N | N
DOMResult | N | Y | N | N
StreamResult | N | N | N | N
Null | Y | Y | N | N

Legend:

Y: You can combine the arguments.

N: You cannot combine the arguments.

6.11 Notes on the javax.xml.xpath Package

The following table gives cautionary notes on the javax.xml.xpath package.

Table 6-22 Notes on the javax.xml.xpath package

No.
Notes

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

Each thread has one XPathFactory instance.

Each thread exclusively accesses the XPathFactory instance.

2
In multi-thread programming, XPath instances generated by the newInstance method of the XPathFactory class and XPathExpression instances generated by the compile method of the XPath interface are not thread-safe. Therefore, multiple threads must not access the same XPath instance and XPathExpression instance at the same time. To avoid conflicts between threads, use the following method:

Each thread has one XPath instance and one XPathExpression instance.

3
The URI http://java.sun.com/jaxp/xpath/dom is the only URI that you can specify as the argument of the newInstance(String uri) method of the XPathFactory class.

4
If you evaluate an XPath expression that refers to a context by using the following methods, specify a non-null context for the item argument:

evaluate(String expression, Object item, QName returnType) method of the XPath interface

evaluate(String expression, Object item) method of the XPath interface

evaluate(Object item, QName returnType) method of the XPathExpression interface

evaluate(Object item) method on the XPathExpression interface

5
Specify the Document, DocumentFragment, Element, Text, Attr, ProcessingInstruction, or Comment object for the item argument described in No.4 in this table.

6
For a return type of the evaluate method of the class that implements the XPathFunction interface and a return type of the resolveVariable method of the class that implements the XPathVariableResolver interface, specify either the java.lang.String, java.lang.Boolean, java.lang.Number, org.w3c.Node, or org.w3c.NodeList type.

7
If an exception occurs in a method for the javax.xml.xpath package, a detailed message may not be obtained because the return value from the getMessage method that was applied to the exception object can be null. In this case, if you obtain the wrapped exception object by applying the getCause method to the exception object and then apply the getMessage method, you may obtain the detailed message.

8
Specify spaces before and after and, or, mod, and div operators.
(Example) 1000 div 10

9
An XPath expression that meets all of the following conditions is not supported:

Specifies the XPath function that returns a node set for each operand in the | operator, and creates a union of the node sets.

Applies a predicate to the union of the node sets created in condition 1.

10
An XPath expression that meets all of the following conditions is not supported:

Uses either the local-name, namespace-uri, or name function.

Specifies the following expression for the argument of the function described in condition 1. above:
self::node()/descendant::prefix1:* (#)
In this case, you can work around this problem by changing the argument of the function described in condition 1 to the following expression:
self::node()/self::node()/descendant::prefix1:* (#)
The prefix1 indicates any namespace prefix.

11
An XPath expression that applies the following-sibling axis to the attribute and namespace nodes is not supported.

12
When an operand of the | operator is not a location set, the XPath expression is not supported.

13
If there are multiple namespace nodes where each set of a namespace prefix and namespace URI is the same, an XPath expression that applies an axis to their namespace nodes is not supported.

14
When 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.

6.12 Notes on the org.w3c.dom Package

The following table gives cautionary notes on the org.w3c.dom package.

Table 6-23 Notes on the org.w3c.dom package

No.
Notes

1
Table 6-24 lists the parameters that can be set for the DOMConfiguration object. Parameters that can be set do not match the return values from the getParameterNames and canSetParameter methods. Also, if you specify a value that cannot be set, an exception may not occur. If you specify a value that cannot be set, the operation is not guaranteed.

2
The parameter name for the DOMConfiguration object is not case-sensitive.

3
For the DOM Level 3, new methods are added to the interface for the existing DOM Level 2. For example, the isId method is added to the Attr interface. Usually, no application program implements these interfaces. If the application implements the interfaces, the method implementation added for the DOM Level 3 needs to be added to the application.

4
If you define the default value for an attribute in XMLSchema and delete the Attr node that corresponds to that attribute, the attribute node for which the getSpecified method returns false will not be generated.

5
The normalizeDocument method of the Document object is not supported.

6
The adoptNode method of the Document object is not supported. Instead, use a combination of the importNode method of the Document object and the removeChild method of the Node object.

7
The getInputEncoding method of the Document object and the getInputEncoding method of the Entity object are not supported.

8
When all of the following conditions are met, a DOMException does not occur by executing the renameNode(Node n, String namespaceURI, String qualifiedName) method of the Document object:

The n argument is an Attr object that does not support namespace.

The namespaceURI argument is null.

The qualifiedName argument is an invalid qualified name.

If you specify the Element or Attr object for the n argument and specify null for the qualifiedName argument, a NullPointerException occurs rather than a DOMException.

9
The getBaseURI method of the Attr, Text, EntityReference, CDATASection, DocumentType, and DocumentFragment objects cannot obtain a URI.

10
Apply the replaceWholeText(String) method of the Text object to the DOM tree without a EntityReference node.

11
A return value from the getByteOffset of the DOMLocator object is always -1.

12
An object of the return value when you apply the getRelatedData method to the DOMError argument of the handleError method of the DOMErrorHandler object is not always a Node object. The return value can be the String object indicating an error message.

13
For a Document object acquired by parsing, the DOMException exception might not occur even when the insertBefore method or the appendChild method is used to add an inappropriate node.

14
When all the following conditions are satisfied, the return value of invoking the getSchemaTypeInfo method for an element node is invalid:

Use an XML schema document to define a derived type element using union.

Use the schema document described in condition 1 above to implement verification check parsing.

Acquire the element node corresponding to condition 1 above from the DOM that is created in condition 2, and invoke the getSchemaTypeInfo method.

Table 6-24 Parameters that can be set for DOMConfiguration objects

Parameter name | Valid values
canonical-form | false
cdata-sections | true, false
check-character-normalization | false
comments | true, false
datatype-normalization | false
element-content-whitespace | true
entities | true, false
error-handler | DOMErrorHandler object
infoset | true, false
namespaces | true
namespace-declarations | true, false
normalize-characters | false
schema-location | Cannot be set.
schema-type | Cannot be set.
split-cdata-sections | true, false
validate | false
validate-if-schema | false
well-formed | true
resource-resolver | LSResourceResolver object

6.13 Notes on the org.w3c.dom.bootstrap Package

The following table describes the cautionary note on the org.w3c.dom.bootstrap package.

Table 6-25 Notes on the org.w3c.dom.bootstrap package

No. | Notes
1 | Specify non-empty character strings for the argument of the getDOMImplementation method and the argument of the getDOMImplementationList method, which are methods of the DOMImplementationRegistry class.

6.14 Notes on the org.w3c.dom.ls Package

The following table gives cautionary notes on the org.w3c.dom.ls package.

Table 6-26 Notes on the org.w3c.dom.ls package

No.
Notes

1
You can specify only the DOMImplementationLS.MODE_SYNCHRONOUS for the mode argument of the createLSParser(short mode, String schemaType) method on the DOMImplementationLS interface. Also, you can specify null, http://www.w3.org/2001/XMLSchema, or http://www.w3.org/TR/REC-xml for the schemaType argument.

2
Table 6-27 lists the parameters that can be set for the DOMConfiguration object that is obtained by applying the getDomConfig method to the LSParser object. In addition to those parameters, the parameters listed in Table 6-24 of 6.12 Notes on the org.w3c.dom Package can also be set. Parameters that can be set do not match the return values from the getParameterNames and canSetParameter methods. Also, if you specify a value that cannot be set, an exception may not occur. If you specify a value that cannot be set, the operation is not guaranteed.

3
If you specify any value for the charset-overrides-xml-encoding parameter of the LSParser object, the value is ignored.

4
The parseWithContext method for the LSParser interface is not supported.

5
The setNewLine method of the LSParser object is not supported.

6
The LSParser object cannot analyze the XML1.1 document.

7
The startElement method of the LSParser object is not called for the root element.

8
If a LSException occurs when you analyze by using the LSParser object or perform serialization by using the LSSerializer object, the return value from the getMessage() method may be null. In such cases, an exception may have occurred in the user implementation class of the LSParserFilter or LSSerializerFilter.

9
Table 6-28 lists the parameters that can be set for the DOMConfiguration object that is obtained by applying the getDomConfig method to the LSSerializer object. In addition to those parameters, the parameters listed in Table 6-24 of 6.12 Notes on the org.w3c.dom Package can also be set. Parameters that can be set do not match the return values from the getParameterNames and canSetParameter methods. Also, if you specify a value that cannot be set, an exception may not occur. If you specify a value that cannot be set, the operation is not guaranteed.

10
If you specify any node other than the Document, DocumentFragment, and Element nodes for the nodeArg argument of the write, the writeToString, and writeToURI methods for the LSSerialize object, those nodes are not serialized.

11
The write, writeToString, and writeToURI methods of the LSSerialize object cannot serialize the nodes whose namespaces are disabled.

12
The default value for the end-of-line sequence character obtained from the getNewLine method of the LSSerializer interface is \n.

13
If the processing instruction in the ProcessingInstruction object includes the character string ?>, no error notification is provided if the ProcessingInstruction object is serialized.

14
When using LSParser to parse, a DOMException exception might not occur even if the contents of the DocumentType object that is acquired from the Document object are changed.

Table 6-27 Parameters that can be set for DOMConfiguration objects (LSParser objects)

Parameter name | Valid values
charset-overrides-xml-encoding | true, false
disallow-doctype | false
ignore-unknown-character-denormalizations | true
supported-media-types-only | false

Table 6-28 Parameters that can be set for DOMConfiguration objects (LSSerializer objects)

Parameter name | Valid values
discard-default-content | true, false
format-pretty-print | false
ignore-unknown-character-denormalizations | true
xml-declaration | true, false

6.15 Notes on the org.xml.sax.ext Package

The following table gives cautionary notes on the org.xml.sax.ext package.

Table 6-29 Notes on the org.xml.sax.ext package

No.
Notes

1
The addAttribute method of the Attributes2Impl class is not supported.
Instead, use the addAttribute method of the AttributesImpl class and modify the application as follows:
(Before modification)

Attributes2Impl myAtt = new Attributes2Impl();
String type = "ID";
myAtt.addAttribute("http://hitachi-xmlprocessor.com/", "attr", "ht:attr", type, "value");
...

(After modification)

AttributesImpl myAtt = new AttributesImpl();
String type = "ID";
myAtt.addAttribute("http://hitachi-xmlprocessor.com/", "attr", "ht:attr", type, "value");
Attributes2Impl myAtt2 = new Attributes2Impl(myAtt);
int position = myAtt2.getLength() -1;
myAtt2.setSpecified(position, true);
myAtt2.setDeclared (position, !"CDATA".equals(type));
...

2
The getXMLVersion and getEncoding methods of the Locator2Impl class are not supported.

6.16 Notes on XInclude

The following table gives cautionary notes on XInclude.

Table 6-30 Notes on XInclude

No. | Notes
1 | You can specify only an element() schema and a shorthand pointer as a possible schema for the xpointer attribute of the xi:include element.
2 | If you specify a shorthand pointer for the xpointer attribute of the xi:include element, the shorthand pointer must be an attribute value of an attribute that is defined as an ID type in the DTD. You cannot specify an attribute value of an attribute that is defined as xsd:ID type in the XML Schema.

6.17 Notes on implementation-dependent specifications

The following tables describe the specifications that depend on the XML Schema implementation.

Table 6-31 Implementation-dependent specifications for data types

Data type
Maximum value
Maximum number of digits

duration type
(Format: PnYnMnDTnHnMnS)
nY (Year)
X
--

nM (Month)
X

nD (Day)
X

nH (Hour)
X

nM (Minute)
X

nS (Second)
1 or more seconds
X

Less than 1 second
X

date type
(Format: CCYY-MM-DD)
CCYY
(If 9999 is exceeded, digits can be added.)
X

gYearMonth type
(Format: CCYY-MM)

gYear type
(Format: CCYY)

dateTime type
(Format: CCYY-MM-DDThh:mm:ss)

Less than 1 second
(Values smaller than 1 second can be specified to the right of the decimal point after ss.)
X

time type
(Format: hh:mm:ss)

base64Binary type
Y
Z

hexBinary type
Z

decimal type
Z

integer type
Z

nonPositiveInteger type
Z

nonNegativeInteger type
Z

negativeInteger type
Z

positiveInteger type
Z

Legend:

X: Can be up to 2,147,483,647

Y: Maximum value is not defined

Z: Maximum number of digits depends on the memory

--: Not applicable

Table 6-32 Implementation-dependent specifications for constraining facet

Constraining facet | Maximum value | Maximum number of digits
length | X | --
minLength | X
maxLength | X
totalDigits | X
fractionDigits | X
maxInclusive | Y | Z
maxExclusive | Z
minInclusive | Z
minExclusive | Z

Legend:

X: Can be up to 2,147,483,647

Y: Maximum value is not defined

Z: Maximum number of digits depends on the memory

--: Not applicable

Table 6-33 Implementation-dependent specifications for the number of occurrences

Number of occurrences | Maximum value | Maximum number of digits
minOccurs | X | --
maxOccurs | X

Legend:

X: Can be up to 2,147,483,647

--: Not applicable

6.18 Precautions related to the schema cache functionality

The following subsections describe the precautions related to the schema cache functionality.

Organization of this section

6.18.1 Precautions related to performance

6.18.2 Precautions related to error output

6.18.3 Precautions related to schema definition files

6.18.4 Precautions related to reset up and deletion of a cache

6.18.1 Precautions related to performance

When you use the disk cache, the overheads increase for the process where the cache is read from the file and de-serialized to the object. Therefore, the performance might decrease than you do not use the cache.

6.18.2 Precautions related to error output

The error occurred during the cache setup is output in the error file and not in the standard error output stream. To confirm the contents output as the error output, execute the cachestate command after specifying the -d option after the J2EE server is started, and then output the error information.

6.18.3 Precautions related to schema definition files

The following table describes the precautions related to schema definition files:

Table 6-34 Precautions related to schema definition files

No.
Precautions

1
,D that is coded at the end of a specified value of the schema_xxx property is considered as a disk cache specifier, so do not use names ending with ,D for schema document files.

2
A schema document that is referenced using xsd:import is always cached in the memory regardless of the specification of schema definition files. The schema document that is referenced using xsd:include or xsd:redefine is merged with grammar objects of the schema document of reference source, so the cache location (memory or a disk) will be the same as the location of the schema document of the reference source.

3
If a schema document that is to be used for verification is specified in the format of InputStream and array of objects within the http://java.sun.com/xml/jaxp/properties/schemaSource property, a cache will not be used during the verification.
You can use a cache only when the schema document is specified in any of the following formats: String, File, or InputSource. However, for InputSource, you must use the getSystemId method to acquire a system identifier.

4
When a parser error occurs while setting up a cache, the schema document that caused the error and the schema document referencing that document will not be cached.

5
The internal files (INFO file) used for cache setup and deletion by the schema cache functionality are saved in the cache_info directory (INFO directory) below <JAXP_DIR>. Therefore, if the disk storage of <JAXP_DIR># exceeds 100%, the cache functionality might not work normally.

6
The schema cache functionality changes or deletes the directories and files exist in the directory specified for the diskcache_path property. Therefore, do not specify a directory used by the system in the diskcache_path property.

7
When specifying a XML schema document, for which an external reference is to be resolved using the entity resolver, in the schema definition file, resolution of the external reference cannot be performed during the cache setup. Therefore, an attempt to parse the schema document will fail and the cache will not be set up.

#

This is the jaxp directory in the directory where Cosminexus is installed.

6.18.4 Precautions related to reset up and deletion of a cache

The following table describes the precautions related to re-set up and deletion of a cache:

Table 6-35 Precautions related to reset up and deletion of a cache

No.
Notes

1
When resetting up a cache, all the schema documents specified in the schema definition file are parsed, and grammar objects are setup, so the parsing process takes more time.
Therefore, the first parser after executing the cacheon command will take more than normal time for processing.

2
When resetting up a cache and starting or stopping J2EE servers, the directories with the names same as of the J2EE server names that exist below the directories specified in diskcache_path will be deleted. Therefore, do not generate files or directories with the names same as that of the J2EE servers in the directory specified in diskcache_path.

3
After setting up a cache, if you change the directory specifications of diskcache_path in the schema definition file, the disk cache might not be deleted when stopping the J2EE server or executing the cacheoff and cacheon commands. In such cases, manually delete the remaining files.

6.19 Notes on the high-speed parse support function

The following subsections provide notes on the high-speed parse support function:

Organization of this section

6.19.1 Notes on setting up the preparsed object

6.19.2 Notes on the XML parser using the preparsed object

6.19.3 Notes on XML1.1

6.19.4 Notes on XInclude (high-speed parse support function)

6.19.5 Notes on how to specify an absolute path

6.19.6 Notes on the Pre-Parse XML document

6.19.7 Notes on tuning information

6.19.8 Notes on parse performance

6.19.1 Notes on setting up the preparsed object

Table 6-36 Notes on the high-speed parse support function (setting up the preparsed object)

No. | Notes
1 | The enabling or disabling of the namespace when pre-parsing must match the enabling or disabling of the namespace when parsing. If these differ, the preparsing might be invalid.
2 | When resolving an entity reference, the results of resolving by the entity resolver when pre-parsing must match the results of resolving by the entity resolver when parsing. If these results differ, the high speed effect might not be achieved.

6.19.2 Notes on the XML parser using the preparsed object

Table 6-37 Notes on the high-speed parse support function (XML parser using the preparsed object)

No.
Notes

1
The high speed effect might not be achieved when the following features of the parser that use the preparsed object are set up as false:

http://xml.org/sax/features/external-general-entities

http://xml.org/sax/features/external-parameter-entities

6.19.3 Notes on XML1.1

Table 6-38 Notes on the high-speed parse support function (XML1.1)

No. | Notes
1 | The high-speed parse support function does not support XML1.1. Therefore, an error occurs if pre-parsing for an XML1.1 document. The high-speed parse support function is not applicable even if an XML1.1 document is set up as a target for performing the high-speed parse support function.

6.19.4 Notes on XInclude (high-speed parse support function)

Table 6-39 Notes on the high-speed parse support function (XInclude)

No. | Notes
1 | The high-speed parse support function is not used to pre-parse a file fetched by XInclude.

6.19.5 Notes on how to specify an absolute path

Table 6-40 Notes on the high-speed parse support function (how to specify an absolute path)

No.
Notes

1
Use a forward slash "/" as a delimiter in the path to specify an absolute path.

2
In Windows, include the drive name in the absolute path.
The specification examples of the absolute path in Windows and UNIX are as follows:

In Windows

D:/home/xml/training/training1.xml

In UNIX

/home/xml/training/training1.xml

6.19.6 Notes on the Pre-Parse XML document

Table 6-41 Notes on the high-speed parse support function (Pre-Parse XML document)

No.
Notes

1
There is an upper limit for the length of the element names and attribute names that can be coded in the Pre-Parse XML document. If the length# obtained by adding the number of characters of the longest element name and attribute name coded in the Pre-Parse XML document, exceeds 21,000 characters, the KECX09607-E error occurs, and the process might be interrupted. For details about the message, see 11. KECX (Messages Output by Cosminexus XML Processor) in the manual uCosminexus Application Server Messages.

#

For example, in the following XML document, the number of characters of the longest element name (element or content) is 7, and the number of characters of the longest attribute name (index) is 5. Therefore, the number of characters obtained by adding these will be 12.

6.19.7 Notes on tuning information

Table 6-42 Notes on the high-speed parse support function (tuning information)

No.
Notes

1
Use a forward slash "/" as a delimiter in the path of the system identifier of the XML document to be parsed.

2
If the File object created by specifying a relative path in the constructor argument, is specified in the newPreparsedObject method of the PreparsedObjectFactory class, the path delimiting characters of the file name of Pre-Parse XML document that are output to the tuning summary file and details file, are duplicated and output as follows:

Preparsed XML: C:\\a.xml

6.19.8 Notes on parse performance

Table 6-43 Notes on the high-speed parse support function (Parse performance)

No.
Notes

1
If you apply the high-speed parse support function to an XML document containing an external entity reference, the parse performance might not improve as compared to the regular parsing. Evaluate the performance beforehand to apply the high-speed parse support function to an XML document containing an external entity reference.

6.20 Notes on JAXB

The following subsections give cautionary notes on JAXB:

Organization of this section

6.20.1 Common notes

6.20.2 Notes on schema compiler

6.20.3 Notes on schema generator

6.20.4 Notes on runtime

6.20.1 Common notes

The following table describes the common notes.

Table 6-44 Notes on JAXB (common)

No.
Notes

1
If you apply the getMessage method to the exception object thrown by the method provided in the JAXB specifications, the return value will become null, and you might not be able to acquire the detailed message. In this case, if you obtain the wrapped exception object by applying the getCause method to the exception object and then apply the getMessage method, you may obtain the detailed message. You can obtain the detailed message by applying the toString method for JAXBException exception and its subclass.

2
In the JAXB specifications, the operation of the methods, schema compiler, and schema generator might not be defined clearly at some locations. In such cases, the operations depend on the implementation. Also, if null is specified in the argument, and Javadoc describes that an exception other than the NullpointerException exception will occur, but in some cases the NullPointerException exception might occur. Make sure that there is no such situation where the operations that are not regulated are executed by prior checking of arguments.
(Example 1) An exception of a type that is not specified in the exception column of Javadoc (The operation when null is specified in the argument is not regulated and hence NullPointerException occurs) occurs.
(Example 2) The operations are not regulated when marshal or unmarshal is performed using the Java source generated when the operations of the schema compiler are not regulated.

3
You cannot use the ISO-10646-UCS-4 encoding.

4
You cannot use an XML document of version 1.1.

5
You cannot use Unicode supplementary characters.

6
Java SE 6 does not support JAXB 2.2 by default. Therefore, if you want to use JAXB 2.2 functions on a non-Hitachi JavaVM, specify Cosminexus-installation-destination/jaxp/lib/csmjaxb-api.jar using the Java endorsed standards override mechanism.
For details on how to specify the settings, see the following Oracle website:
http://download.oracle.com/javase/6/docs/technotes/guides/standards/

6.20.2 Notes on schema compiler

The following subsections give cautionary notes on schema compiler.

Do not process the schema corresponding to the notes described in item no. 1 to item no. 28 by the schema compiler. For item no. 29 to item no. 44, use the schema compiler after considering the notes.

Table 6-45 Notes on JAXB (schema compiler)

No.
Notes

1
[Conditions]
When all of the following conditions are applicable to contents model with iterative specifications:

An element definition in which nillable="true" is specified exists.

The contents model is not mixed and does not include a wildcard.

The element definition of the contents model does not include an xml data type of xs:list and xs:IDREF, or a data type derived from xs:list and xs:IDREF.

Two different element definitions bound to the same Java data type do not exist for all element definitions of the contents model.

(Example)
<xs:complexType>
<xs:sequence maxOccurs="unbounded">
<xs:element name="A" type="xs:string" />
<xs:element name="B" type="xs:int" nillable="true" />
<xs:element name="C" type="xs:float" nillable="true"/>
<xs:element name="D" type="xs:double" />
</xs:sequence>
</xs:complexType>

[Operation of Cosminexus XML Processor]
A collection is optimized. The collection annotated with @XmlElements/@XmlElement instead of @XmlElementRefs/@XmlElementRef is output. An invalid operation might be performed when unmarshal and marshal is executed using the java source that is output.

2
[Conditions]
When all of the following conditions are applicable:

A reserved device name of Windows, such as www.com1.hitachi is included in the targetNamespace attribute of the xs:schema element.

The schema compiler is executed on Windows.

Operations of Cosminexus XML Processor
Error occurs.
(Example)
[ERROR] .\hitachi\com1\ObjectFactory.java (The specified path is not found. [errno=3, syscall=CreateFileW])

3
[Conditions]
When all of the following conditions are applicable to the first character of the character string that separates the URI specified in the targetNamespace attribute of the xs:schema element by a colon ":" or forward slash "/":

The return value of Character.isJavaIdentifierStart becomes false.

The return value of Character.isJavaIdentifierPart becomes false.

Operations of Cosminexus XML Processor
An error indicating an invalid package name occurs.
(Example)
[ERROR] The package name 'publicid.__-.w3c.dtd_html_4_01.en' used for this schema is not a valid package name.

4
[Conditions]
When the URI specified in the targetNamespace attribute and xmlns attribute of the xs:schema element is configured only from the following characters:

Periods (.)

Forward slashes (/)

Character string "www"

Operations of Cosminexus XML Processor
Exceptions that are not provided such as java.lang.ArrayIndexOutOfBoundsException might occur.

5
[Conditions]
When any of the following conditions are satisfied:

When multiple xs:any elements exist in the contents model without iterative specification.

Using the complex type extension, both the base type and extension type include the xs:any type as the element contents.

Operations of Cosminexus XML Processor
An error occurs by trying to generate multiple properties and not a single general contents property. For details about the general contents properties, see the subsection 6.12.3 of JSR 222 The Java Architecture for XML Binding 2.1.
(Example)
[ERROR] Property "Any" is already defined. Use &lt;jaxb:property> to resolve this conflict.
Note that if you specify jaxb:property custom binding and execute unmarshalling or marshalling using the java source with multiple @XmlAnyElement annotated properties that are output, some invalid operations might be performed.

6
[Conditions]
When any of the following conditions are satisfied:

When the format is derived, true is specified for the value of the mixed attribute in a complexType element having the derived type.

When the format is derived, true is specified for the value of the mixed attribute having the base type.

Operations of Cosminexus XML Processor
The method for acquiring a child element of the derived format will not be generated.

7
[Conditions]
When all of the following conditions are applicable:

The jaxb:typesafeEnumClass custom binding that has jaxb:typesafeEnumMember as a child element for the xs:simpleType element. Also, the name attribute is specified in jaxb:typesafeEnumMember.

The jaxb:typesafeEnumMember custom binding is specified for the xs:enumeration element that is a lower element of xs:simpleType specified in condition 1, and the name attribute is also specified.

The attribute values of the name attribute specified in condition 1. and 2. differ.

Operations of Cosminexus XML Processor
The enumeration constant name of the Java class is generated based on the name attribute specified in condition 1.

8
[Conditions]
When custom binding is specified in any of the following XML schema elements:

jaxb:typesafeEnumClass is specified in the xs:attributeGroup element.

jaxb:typesafeEnumClass is specified in the xs:extension element that is the child element of the xs:complexContent element.

jaxb:typesafeEnumClass/jaxb:typesafeEnumMember/jaxb:property is specified in the xs:restriction element that is the child element of the xs:simpleType element or in the xs:maxExclusive/xs:maxInclusive/xs:minExclusive/xs:maxLength/xs:pattern facet of the child element.

jaxb:schemaBindings is specified in the xs:totalDigits/xs:whiteSpace facet of the child element of xs:restriction element.

Operations of Cosminexus XML Processor
The operations during the execution of JAXB when such a schema document is used are not regulated.

9
[Conditions]
When all of the following conditions are applicable:

The jaxb:schemaBindings custom binding in which the map attribute is false exists.

The jaxb:class or jaxb:typesafeEnumClass custom binding exists.

Operations of Cosminexus XML Processor
An error indicating invalid custom binding is output.
(Example)
[ERROR] compiler was unable to honor this class customization. It is attached to a wrong place, or its inconsistent with other bindings.

10
[Conditions]
When the jaxb:class custom binding is specified for the local element definition (xs:element containing =xs:complexType as the child element) whose type is defined as an anonymous complex type.
Operations of Cosminexus XML Processor
An error is output.
(Example)
Exception in thread "main" java.lang.IllegalArgumentException: Illegal class inheritance loop. Outer class element-name may not subclass from inner class: element-name

11
[Conditions]
When the jaxb:property custom binding is specified for xs:choice, xs:sequence, or xs:all specified in the complex type definition xs:restriction.
Operations of Cosminexus XML Processor
An error is output.
(Example)
[ERROR] compiler was unable to honor this property customization. It is attached to a wrong place, or its inconsistent with other bindings.

12
[Conditions]
When all of the following conditions are applicable:

The jaxb:typesafeEnumClass custom binding is specified in the xs:complexType element.

true, 1, or 0 is specified in the map attribute specified in the custom binding of condition 1.

[Operation of Cosminexus XML Processor]
The message KECX06051-E cvc-enumeration-valid: Value 'true' is not facet-valid with respect to enumeration '[false]'. It must be a value from the enumeration. occurs.
The value true specified in the map attribute is correct, but the specification of the jaxb:typesafeEnumClass custom binding in the xs:complexType element itself is invalid.

13
[Conditions]
When any of the following conditions are satisfied:

When any the following is specified in the collectionType attribute of jaxb:property:
- An empty character string
- A class in which java.util.List is not implemented
- A class in which java.util.List is implemented, but not a completely modified class

When any the following is specified in the collectionType attribute of jaxb:globalBindings
- A class in which java.util.List is not implemented
- A class in which java.util.List is implemented, but the class is not completely modified

Operations of Cosminexus XML Processor
The java class is generated without an error occurrence.

14
[Conditions]
When specifying an empty character string is specified in the collectionType attribute of jaxb:globalBindings.
Operations of Cosminexus XML Processor
Throws the exception java.lang.StringIndexOutOfBoundsException.

15
[Conditions]
When any of the following conditions are satisfied:

Specify the following two attributes in the jaxb:class custom binding:
- ref attribute
- exclusive name attribute

Specify the following two attributes in the jaxb:class custom binding:
- ref attribute
- exclusive implClass attribute

Specify the following two attributes in the jaxb:typesafeEnumClass custom binding:
- ref attribute
- exclusive name attribute

Specify the following two attributes in the jaxb:typesafeEnumClass custom binding:
- ref attribute
- exclusive map attribute

Operations of Cosminexus XML Processor
An error does not occur. In such cases, the operations for executing JAXB are not defined.

16
[Conditions]
When all the following conditions are satisfied:

Specify the jaxb:class custom binding in the xs:element global element definition or the xs:element local element definition.

Specify the implClass attribute in the jaxb:class custom binding.

Operations of Cosminexus XML Processor
An error does not occur. In such cases, the operations for executing JAXB are not defined.

17
[Conditions]
When all the following condition are satisfied:

Specify the jaxb:typesafeEnumClass custom binding in the xs:simpleType definition of an enumerated facet.

Specify True, 1, or 0 in the map attribute of jaxb:typesafeEnumClass

Operations of Cosminexus XML Processor
An error does not occur. When the map attribute is not specified, the operations with the specified true or 1 will be executed by default.

18
[Conditions]
When all the following conditions are satisfied:

Specify the jaxb:property custom binding for a local or a global attribute declaration

Specify True, false, 1, or 0 in the generateElementProperty attribute.

Operations of Cosminexus XML Processor
An error does not occur. Java source including the property is output.

19
[Conditions]
When all the following conditions are satisfied:

Specify the jaxb:property custom binding for multiple element declarations with different name attributes in the same format.

Specify False in the generateElementProperty attribute

Operations of Cosminexus XML Processor
An error does not occur. Java source including JAXBElement is output.

20
[Conditions]
When any of the following conditions are satisfied:

Specify a class that does not exist in the same inheritance hierarchy as the default base type is specified, in the name attribute of the jaxb:baseType element.

Specify a class in which the Java class name is not fully modified, in the name attribute of the jaxb:baseType element.

Operations of Cosminexus XML Processor
An error does not occur. Java source is output.

21
[Conditions]
When the attachmentRef attribute of the jaxb:property custom binding is to be used.

Operations of Cosminexus XML Processor
The following error is output during the schema compilation:
[ERROR] KECX06031-E cvc-complex-type.3.2.2: Attribute 'attachmentRef' is not allowed to appear in element 'jaxb:property'.

22
[Conditions]
When specifying character strings other than asWordSeparator or asCharInWord, in the underscoreBinding attribute of the jaxb:globalBindings custom binding.

Operations of Cosminexus XML Processor
The NullPointerException exception is thrown.

23
[Conditions]
When specifying skipGeneration in the typesafeEnumMemberName attribute of the jaxb:globalBindings custom binding.

Operations of Cosminexus XML Processor
The following error is output:
KECX06051-E cvc-enumeration-valid: Value 'skipGeneration' is not facet-valid with respect to enumeration '[generateError, generateName]'. It must be a value from the enumeration.

Workaround
When the typesafeEnumMemberName attribute is not specified, the default operation changes to the skipGeneration operation.

24
[Conditions]
When specifying and customizing the jaxb:globalBindings custom bindings multiple times:

The xmlType attributes have different name attribute values, and the values of the xmlType attributes have same jaxb:javaType

jaxb:serializable with different uid attribute values

Operations of Cosminexus XML Processor
In such cases, the operations for executing JAXB are not defined.

25
[Conditions]
When all the following conditions are satisfied:

Specify primitive in the optionalProperty attribute of the jaxb:globalBindings custom binding.

Anyone of the following local element exists in the schema:
- Primitive type element with the specified minOccurs="0".
- Primitive type element defined in xs:choice

Operations of Cosminexus XML Processor
Output in wrapper class type and not the primitive type.

26
[Conditions]
When all the following conditions are satisfied:

Specify False in the generateElementProperty attribute of jaxb:globalBindings custom binding.

The specifications that become the property of the JAXBElement type, such as multiple elements with the same type and different names exist in the schema.

Operations of Cosminexus XML Processor
An error does not exist. In such case, the operations for executing JAXB are not defined.

27
[Conditions]
When specifying jaxb:inlineBinaryData in xs:complexType having simple contents of the binary type.

Operations of Cosminexus XML Processor
An invalid custom binding error is output.
Example:
[ERROR] compiler was unable to honor this inlineBinaryData customization. It is attached to a wrong place, or its inconsistent with other bindings.

28
[Conditions]
Anyone of the following conditions are satisfied:

Specify a non existing java data type in the name attribute of jaxb:javaType.

Specify the parseMethod attribute or the printMethod attribute of jaxb:javaType, and the primitive type in the name attribute.

In the name attribute of jaxb:javaType, specify the java data type for which a constructor with one argument of the String type is not defined.

Operations of Cosminexus XML Processor
An error does not occur.

29
The standard specifications provide the methods for customizing the contents of the documentation comments of Java classes generated using the jaxb:javadoc custom binding. Even when jaxb:javadoc is not specified, the default documentation comments are generated, but the contents are not provided in the standard specifications.

30
[Conditions]
When there is a simple type definition where the range specified in any of the xs:totalDigits, xs:maxExclusive, xs:maxInclusive, xs:minExclusive, or xs:minInclusive facets is within the int or long range.
Operations of Cosminexus XML Processor
java.math.BigInteger is generated always when the xs:totalDigits facet is used.
When the xs:maxExclusive, xs:maxInclusive, xs:minExclusive, or xs:minInclusive facet is used, the Java type is generated according to the algorithm specified in the subsection 6.2.2 of JSR 222 The Java Architecture for XML Binding 2.1.

31
[Conditions]
When a model group definition containing any of the following exists:

An anonymous complex type definition

xs:enumeration facet definition mapped in enum type

The contents model mapped in the element class

Operations of Cosminexus XML Processor
The model group name is not added to the created class name.

32
[Conditions]
When the jaxb:class custom binding is specified in the xs:element local element definition.
Operations of Cosminexus XML Processor
Inherits JAXBElement<T> and creates element factory method that returns the created classes.
(Example)
public class ObjectFactory {
public Base.Bar createBaseBar(String value) {
return new Base.Bar(value);
}
....
}
Note
Base.Bar is the class inheriting JAXBElement<T>.

33
[Conditions]
When all of the following conditions are applicable:

The xs:element global element definition exists.

The value of the abstract attribute specified in condition 1. is true.

Operations of Cosminexus XML Processor
The element factory method corresponding to the element definition is generated, but instances cannot be generated using the factory method.

34
[Conditions]
When either of the following is applicable to the schema document:

Element definitions with the same element name and different name space are specified in the contents model.

Two element definitions with element names class or Class and clazz or Clazz are specified in the contents model.

Operations of Cosminexus XML Processor
The name conflicting error does not occur, and the process is performed as a general contents list annotated by @XmlElementRef/@XmlElementRefs. For details about the contents list, see the subsection 6.12.3 of JSR 222 The Java Architecture for XML Binding 2.1.

35
[Conditions]
When either lax or skip is specified in the processContents attribute of xs:any.
Operations of Cosminexus XML Processor
The data type of the bind property will be the java.lang.Object type when the processContents attribute is lax, and the org.w3c.dom.Element type when the processContents attribute is skip.

36
[Conditions]
When the fixed attribute of the xs:element element is specified.
Operations of Cosminexus XML Processor
The value of the specified fixed attribute is not applied to the defaultValue element of @XmlElement and @XmlElementDecl of the Java source that is generated.
[Corrective action]
To apply the value of the fixed attribute as a default value, specify the default attribute instead of the fixed attribute.

37
[Conditions]
When a character string is specified in the value attribute of the xs:enumeration element in such a way so that there are conflicts in the generated java constant identifier.
(Example)
name-with-dashes and name_with_dashes
Operations of Cosminexus XML Processor
The enumeration definition is not output. No error occurs.

38
[Conditions]
When all of the following conditions are applicable to the URI specified in the targetNamespace attribute of the xs:schema element:

Top-level domains (such as com, gov, net, org, and edu) are not included.

The country code is not included.

Operations of Cosminexus XML Processor
The domain name of the package name of generated java source will be in the reverse order, and www. will be deleted.

39
[Conditions]
When any of the following is specified in the element name and attribute name:

java keyword

java literal (true, false, or null)

Method names defined in the java.lang.Object class

Method names defined in the javax.xml.bind class

Operations of Cosminexus XML Processor
The field and method name will be generated without the occurrence of a name conflicting error. A field name with an underscore"_" will be created for java keyword and java literal.

40
[Conditions]
When a redefined complex type definition exists.

Operations of Cosminexus XML Processor
For a redefined complex type definition, a class name with the prefix Original is generated instead of a class name with attached _.

41
[Conditions]
When all the following conditions are satisfied:

A model group definition exists.

Specify the suffix attribute or the prefix attribute of jaxb:modelGroupName in the jaxb:schemaBindings custom binding.

Operations of Cosminexus XML Processor
The model group definitions are not mapped in a class, so the specification of jaxb:modelGroupName is not applied to the generated source.

42
[Conditions]
When all the following conditions are satisfied:

Specify asCharInWord in the underscoreBinding attribute of jaxb:globalBindings custom binding.

Underline is included in the name attribute of xs:element or in the name attribute xs:attribute with the specified fixed attribute.

For the name attribute of xs:attribute in step 2, True is specified in the fixedAttributeAsConstantProperty attribute of jaxb:globalBindings.

Operations of Cosminexus XML Processor
A Java identifier different from the specifications is generated.
Example:

For the name attribute of xs:element:
child_element => getChild_Element (correct is getChild_element)

For the name attribute of xs:attribute:
child_attribute => CHILD___ATTRIBUTE (correct is CHILD_ATTRIBUTE)

43
[Conditions]
When all the following conditions are satisfied:

In the enableJavaNamingConventions attribute of the jaxb:globalBindings custom binding, specify true or do not specify the attribute.

In the name attribute of jaxb:package that is the child element of jaxb:schemaBindings, specify an invalid value as a java identifier.

Operations of Cosminexus XML Processor
The conversion into an appropriate java identifier is not executed.

44
[Conditions]
When specifying jaxb:serializable without the uid attribute, in the jaxb:globalBindings custom binding.

Operations of Cosminexus XML Processor
An error does not occur. In such cases, the operations for executing JAXB are not defined.

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

1
The 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:

@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.

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:

@XmlElements is specified in the field or JavaBean property of collection type with parameters.

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:

A value other than a null character string is specified in the namespace element of @XmlSchema.

@XmlNs is specified in the xmlns element of @XmlSchema.

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:

@XmlAttribute is added to a field or JavaBean property of primitive type.

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:

A class mapped to the simple type list exists.

@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:

The @XmlRootElement annotation, and @XmlType annotation in which the name element is an empty character string, are added to the class.

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:

An abstract modifier is specified in a class mapped in complex type.

@XmlValue is added to the field or JavaBean property of the class specified in condition 1.

@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:

The @XmlRootElement annotation, and the @XmlType annotation in which the name element is an empty character string, are added to the class.

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.

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:

The @XmlRootElement annotation, and the @XmlType annotation in which the name element is an empty character string, are added to the class.

A class with the type of the field or JavaBean property, same as in the class specified in condition 1 exists.

An element name mapped to the field or JavaBean property specified in condition 2. is same as the element name mapped to condition 1.

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:

The name space URI is specified in the namespace element of @XmlSchema.

@XmlNs is specified in the xmlns element of @XmlSchema, and the name space URI is specified in the namespaceURI element.

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.

42
The 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.

56
Condition
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.

57
Condition
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.

58
Condition
When all the following conditions are satisfied:

@XmlElementRef is added to multiple field values or JavaBean properties.

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.

59
Condition
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.

60
Condition
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.

61
Condition
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.

6.20.4 Notes on runtime

The following table describes the notes on runtime.

Table 6-47 Notes related to JAXB (Runtime)

No.
Notes

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:

@XmlJavaTypeAdapter is specified at the package level.

@XmlJavaTypeAdapter is specified for the class or enumeration type.

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

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:

Marshal is executed.

An argument jaxbElement of the marshal method is JAXBElement object.

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:

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

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

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:

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

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:

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

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

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:

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

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

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:

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

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

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:

The jaxb:typesafeEnumClass custom binding is specified.

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

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:

Specify the xsi:type attribute in an XML document.

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

Unmarshal the XML document of step 1.

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:

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

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

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.

6.21 General XML Processor related notes

This section describes other notes related to general usage of the XML Processor.

Table 6-48 Notes related to general usage of the XML Processor

No.
Notes

1
When an XML Schema is used for validation processing, exceptions or errors that are not defined in the API specifications might occur due to some factors. With Java programs that use an XML Schema for validation processing, implement exception processing that can catch java.lang.Throwable and take appropriate action, on condition that such exceptions or errors are thrown.

Appendixes

Organization of the appendixes

A. Differences Between Versions

B. Support Range of JAXB Specifications

C. Efficiently using XML Processor

D. Glossary

Appendix A. Differences Between Versions

This appendix describes the behaviors that differ from the previous version of Cosminexus XML Processor.

Organization of this section

A.1 Differences in Behaviors Between DOM and SAX Parser Versions

A.2 Differences in Behaviors Between DOM Parser Versions

A.3 Differences in Behaviors Between SAX Parser Versions

A.4 Differences in Behaviors of Schema Validation Between Versions

A.5 Differences in Behaviors of XSLT Between Versions

A.6 Differences in the JAXB operation

A.7 Differences in the operation of the javax.xml.datatype package

A.8 Differences in the operation of the high-speed parse functionality

A.9 Differences in the operation of StAX

A.10 Differences in the operations of the Apache-specific functionality

Appendix A.1 Differences in Behaviors Between DOM and SAX Parser Versions

The following table describes the differences in behaviors between DOM and SAX parser versions.

Table A-1 Differences in behaviors between DOM and SAX parser versions

No.
Condition
Cosminexus XML Processor operations

In version 06-00
In version 07-00 and later versions

1
When a parser uses the InputSource object to read a byte stream
Automatically detects the character encoding by using the algorithm of the XML specifications.
The encoding specified in the setEncoding method takes precedence.

2
If parsing is performed with incorrect encoding (for example an XML document saved in EUC but for which encoding is not specified in the XML declaration)
IOException occurs.
SAXException occurs.

3
If you specify an empty string for the uri or systemId argument of the parse method
IOException occurs.
SAXException occurs.

4
If you specify an empty string for the system identifier of the DOCTYPE declaration in the XML document
IOException occurs.
SAXException occurs.

5
If an element that was declared EMPTY in the DTD contains comments only
An error does not occur when checking validation.
An error occurs during validation.

6
If an XML document that cannot be specified in attribute values or text, including U+D800 to U+DFFF, is parsed (however, this does not include surrogate pairs)
An error occurs.

In J2SE 5.0

An error occurs.

In Java SE 6

Normal termination.

However, take note that the processing result becomes invalid.

7
If an element that was not defined in the child element is specified during validation by DTD
The KECX01165-E error is reported.
The KECX01164-E error is reported.

8
If UTF-16 is specified as the encoding attribute value of the XML declaration in an XML document coded in UTF-8
The KECX01083-E error is reported.
The KECX01024-E error is reported.

Appendix A.2 Differences in Behaviors Between DOM Parser Versions

The following table lists and describes the differences in behaviors between DOM parser versions.

Table A-2 Differences in behaviors between DOM parser versions

No. | Condition | Cosminexus XML Processor operations
In version 06-00 | In version 07-00 and later versions
1 | If a NOTATION declaration with the same name exists and the validation is enabled | The duplicate NOTATION declaration is discarded. | The duplicate NOTATION declaration is discarded and an error occurs.
2 | If you execute the appendChild or insertBefore method specifying the node or its ancestor node for the newChild argument for a node | The DOMException exception code is WRONG_DOCUMENT_ERR. | The DOMException exception code is HIERARCHY_REQUEST_ERR.
3 | If you specify null for the qualifiedName argument of the createElementNS(String namespaceURI, String qualifiedName) method for the Document interface | The DOMException exception code is INVALID_CHARACTER_ERR. | The DOMException exception code is NAMESPACE_ERR.
4 | If the http://java.sun.com/xml/jaxp/properties/schemaSource property is specified in the setAttribute() method of the DocumentBuilderFactory class rather than the http://java.sun.com/xml/jaxp/properties/schemaLanguage property | The KECX01603-E error is reported. | The KECX01338-E error is reported.

Appendix A.3 Differences in Behaviors Between SAX Parser Versions

The following table lists and describes the differences in behaviors between SAX parser versions.

Table A-3 Differences in behaviors between SAX parser versions

No.
Condition
Cosminexus XML Processor operations

In version 06-00
In version 07-00 and later versions

1
When the createXMLReader() method of the XMLReaderFactory class is used
Attempts to generate the XMLReader instance by using the value of the org.xml.sax.driver system property.
Attempts to generate the XMLReader instance in the following order:

Class name indicated by the org.xml.sax.driver system property

Class name indicated by the META-INF/services/org.xml.sax.driver of the jar file

Default XMLReader class name

Class that wrapped the return value of the makeParser() method of the ParserFactory class by using the ParserAdapter

2
When you specify the ContentHandler object for the XMLReader object
Even if an entity is skipped, the skippedEntity method for the ContentHandler object is not called.
If an entity is skipped, the skippedEntity method for the ContentHandler object is called.

3
If the systemId argument of the externalEntityDecl(String name, String publicId, String systemId) method of the DeclHandler class and the notationDecl(String name, String publicId, String systemId) method of the DTDHandler interface is a URL
The URL might not be resolved completely.
URL is resolved completely.

4
If you specify null for the argument of the setEntityResolver method, setDTDHandler method, setContentHandler method, and setErrorHandler method in the XMLReader class
NullPointerException occurs.
The resolver and handler are cleared.

5
If you specify null for the argument of the setEntityResolver method, setDTDHandler method, setContentHandler method, and setErrorHandler method in the ParserAdapter class
NullPointerException occurs.
The resolver and handler are cleared.

6
If you specify null for the argument of the setEntityResolver method, setDTDHandler method, setContentHandler method, setErrorHandler method, and setParent method in the XMLFilterImpl class
NullPointerException occurs.
The resolver, handler, and parent reader are cleared.

7
If you set the feature http://xml.org/sax/features/namespaces for SAX parser to false and the feature http://xml.org/sax/features/namespace-prefixes to true
The startPrefixMapping and the endPrefixMapping methods are invoked for the prefix xml and xmlns.
The startPrefixMapping and the endPrefixMapping methods are not invoked for the prefix xml and xmlns.

8
If an exception class that has inherited SAXException in the implementation class of the fatalError method of the ErrorHandler interface is thrown
The parser throws SAXException during the execution of parse.
The parser as it is throws the exception that is thrown by the fatalError method of the implementation class of the ErrorHandler interface.

9
If you specify an inappropriate character string in the http://java.sun.com/xml/jaxp/properties/schemaLanguage property using the setProperty() method of the SAXParser class
The KECX01602-E error is reported.
The KECX01903-E error is reported.

10
If you specify the http://java.sun.com/xml/jaxp/properties/schemaSource property before specifying the http://java.sun.com/xml/jaxp/properties/schemaLanguage property using the setProperty() method of the SAXParser class
The KECX01603-E error is reported.
The KECX01904-E error is reported.

Appendix A.4 Differences in Behaviors of Schema Validation Between Versions

The following table lists and describes the differences in behaviors of schema validation between versions.

Table A-4 Differences in behaviors of schema validation between versions

No.
Condition
Cosminexus XML Processor operations

In version 06-00
In version 07-00 and later versions

1
If xsd:key element exists in a schema document and the text corresponding to the key does not exist in the instance document
An error might not occur.
An error occurs.

2
If you specify a combination of an xsd:key element and an xsd:keyref element for a schema document, and the order and type of the field elements of both xsd:key element and the xsd:keyref element do not match
An error might not occur.
An error occurs.

3
If the xpath attribute for the xsd:field element is an XPath expression that includes the child axis
An error does not occur.
An error indicating that the child axis cannot be specified occurs.

4
If an xpath attribute for an xsd:selector element is an XPath expression that includes an incorrect | operator such as | ns1:element
An error does not occur or an error associated with the validation for an XML document occurs.
An error associated with a schema document occurs.

5
If you specify an empty string for the schemaLocation attribute of the xsd:redefine or xsd:import element
An error does not occur.
An error occurs.

6
If http://www.w3.org/2001/XMLSchema-instance is specified in the targetNamespace attribute of an xsd:schema element
-- (Not applicable)

In 08-00, the error KECX06509-E will be reported.

In 08-50 or later versions, error will not be reported. However, if an extended attribute exists, the error KECX06198-E will be reported.

7
When all the following conditions are satisfied:

The anyURI type or its derived types are used in the XML schema document

Data corresponding to the definition in 1. includes characters violating the provisions in RFC2396 and RFC2732

The KECX06036-E error is reported.
Processed as a value suitable for the data type declaration.

8
When all the following conditions are satisfied:

The time or dateTime types are used in the XML schema document

60 is specified as the seconds value in data corresponding to the definition in 1.

Processed as a value suitable for the data type declaration.
The value is considered to be outside the scope of the data type declaration, and the KECX06036-E error is reported.

9
When all the following conditions are satisfied:

The time or dateTime types are used in the XML schema document

A value in the range from -14:01 to -14:59 or from +14:01 to +14:59 is specified as the time zone offset in data corresponding to the definition in 1.

Processed as a value suitable for the data type declaration.
The value is considered to be outside the scope of the data type declaration, and the KECX06036-E error is reported.

10
When minLength or maxLength is specified in the derivation by the restriction based on a simple type in which the length facet is specified
An error occurs.
An error does not occur.

11
When all of the following conditions are satisfied:

An error handler is set during validation parsing

During validation parsing, the error or fatalError method of the error handler described in step 1 above is invoked

An exception is not thrown in the method described in step 2 above

The validation errors reported in version 06-00 and version 07-00 or later versions might be different.

12
When both the following conditions are satisfied:

The type of element specified in the selector of the xsd:unique element is xsd:anyType

The type of element described in step 1 above is changed to a simple type using the xsi:type global attribute in the instance document

An error occurs.
An error does not occur.

13
When a blank exists in the instance data of the xsd:anyURI type
An error occurs.
An error does not occur.

14
When the final attribute of the xsd:simpleType element is only a null character string or a blank
An error occurs.
An error does not occur.

15
When the public attribute of the xsd:notation element does not exist
The KECX06230-E error is reported.
The KECX06256-E error is reported.

16
When [- and -] are specified in the regular expression of the value attribute of the xsd:pattern element
An error occurs.
An error does not occur.

17
When all of the following conditions are satisfied:

Uniqueness is specified for the elements with xsd:unique

The type of element described in step 1 above is not a simple type

The type of element described in step 1 above is replaced by a simple type in the xsi:type global attribute in the instance document

Validation parsing is performed

An error occurs.
An error does not occur.

18
When an inappropriate xpath attribute is specified in the xsd:selector element
The KECX06243-E error is reported.
The KECX06241-E error is reported.

19
When a path format called element-name/ is specified in the xpath attribute of the field (xsd:field element) of the xsd:key element
An error occurs.
An error does not occur.

20
When multiple elements with different types are specified in the selector (xsd:selector element) of the xsd:key element, and the same value is applied to the key element in the instance document
An error occurs.
An error does not occur.

21
When a long URI character string (63 bytes or more) is specified for an element of the xsd:anyURI type
An error occurs.
An error does not occur.

22
When a list demarcated by blanks, such as list restriction union is specified in the final attribute of the xsd:simpleType element
An error occurs.
An error does not occur.

23
When a URI including double-byte characters is inserted in an element for which derivation by the restriction is performed based on xsd:anyURI
An error occurs.
An error does not occur.

24
When the value of seconds is given in 10 or more digits after the decimal point in the element for which derivation by the restriction is performed with xsd:time as the base type (example: 13:20:15.2147483648​)
An error occurs.
An error does not occur.

25
When xsd:length is fixed at 2 or more in the derivation by the restriction performed with xsd:IDREF as the base
An error occurs.
An error does not occur.

26
When validation parsing is performed for an XML document that satisfies the following condition:

A schema document that either does not exist or cannot be read in the xsi:schemaLocation attribute or the xsi:noNamespaceSchemaLocation attribute of the input XML document is specified

A warning does not occur.
The KECX06069-E warning is reported.

27
When validation parsing of an XML document is performed by using a schema document that satisfies the following conditions:

A schema document that either does not exist or cannot be read in the schemaLocation attribute of xs:import and xs:include is specified

The xs:redefine element satisfies either of the following points (i) or (ii), and a schema document that either does not exist or cannot be read in the schemaLocation attribute is specified
(i) The child element of the xs:redefine element is only the xs:annotation element
(ii) A child element does not exist in the xs:redefine element

An error does not occur.
The KECX06069-E warning is reported.

28
When a URI with an invalid syntax is specified in either of the following locations:

xsi:schemaLocation attribute or xsi:noNamespaceSchemaLocation attribute of the instance document

schemaLocation attribute of the include element, import element, or redefine element

The operation is different in 06-00 and 07-00 or later versions depending on the combination of the URI specification location and the URI with an invalid syntax. For example, the error to be reported might be different, or an exception that did not occur in version 06-00 might occur in version 07-00 or later.

29
When a URI with an invalid syntax is specified in one of the following locations:

namespace attribute of the anyAttribute element

namespace attribute of the any element

system attribute of the notation element

source attribute of the appinfo element

source attribute of the documentation element

namespace attribute of the import element

The KECX06229-E error is reported.
An error does not occur.

30
When a URI with an invalid syntax is specified in either of the following locations:

targetNamespace of the schema element

schemaLocation attribute of the redefine element

The KECX06229-E error is reported.
The KECX06039-E or the KECX06069-E error is reported.

Note:

For details on the messages, see 11. KECX (Messages Output by Cosminexus XML Processor) in the manual uCosminexus Application Server Messages.

Appendix A.5 Differences in Behaviors of XSLT Between Versions

The following table lists and describes the differences in behaviors of XSLT between versions.

Table A-5 Differences in behaviors of XSLT (Comparing version 06-00 and version 07-00 and later versions)

No.
Condition
Cosminexus XML Processor operations

In version 06-00
In version 07-00 and later versions

1
When the default error listener in the Transform and TransformerFactory classes is used
Throws an exception when an error occurs.
Does not throw an exception when an error occurs.

2
When you execute the newTransformer(Source source) and newTemplates methods in the TransformerFactory class
There is no difference between the versions.
If there are errors in the stylesheet from which these methods are read, an error is reported to the fatalError method for the ErrorListener. In such a case, note that the return value from the newTransformer(Source source) and newTemplates methods might be null if the fatalError method implementation for the ErrorListener does not throw the TransformerException.
The default ErrorListener does not throw the TransformerException. Therefore, to maintain normal behavior when an unrecoverable error occurs, Hitachi strongly recommends that you register the ErrorListener to throw the TransformerException from within the fatalError method.

3
When XML is output to a file, if indent="yes" is not specified for the xsl:output element or the setOutputProperty(OutputKeys.INDENT, "yes") method of the Transform class is not executed
A linefeed is output immediately after the XML declaration.
Linefeed is not output.

4
When the transformation result is output in HTML format
The linefeed output between elements differs, however, as the linefeed between elements has no meaning in the HTML document, there is no problem.

5
When you execute the system-property('xsl:version') function
The result is 1.
The result is 1.0.

6
If the content of the xsl:attribute element is a string including a tab
The attribute value of the result is a tab character itself.
The attribute value of the result is a character reference (&#9;).

7
If you use the generate-id() function for the value attribute of the xsl:number element
0 is output.
NaN is output.

8
If the prefix defined in the namespace declaration for the xsl:stylesheet element is not used in the elements created by the xsl:element element
The namespace declaration is output to the xsl:element element.
The namespace declaration is not output to the xsl:element element.

9
If you describe a top-level element in the simplified stylesheet where you specify 1.1 for the xsl:version attribute
In the forward compatible processing, the top-level element is instantiated and then transformed.
The forward compatible processing of the top-level element is ignored.

10
If you specify a non-existent attribute set name for the use-attribute-sets attribute of the xsl:attribute-set element
An error does not occur.
An error occurs indicating that the attribute set does not exist.

11
If neither the name attribute nor the match attribute is specified for the xsl:template element
An error does not occur.
An error occurs indicating that either the name or the match attribute is necessary.

12
If the excluded namespace prefixes that are specified in the exclude-result-prefixes attribute are not defined in the namespace declaration for the xsl:stylesheet element
An error does not occur.
An error occurs.

13
If you specify a value other than a number for the version attribute of the xsl:stylesheet element
An error does not occur.
An error occurs.

14
If you specify xml for the method attribute and a value other than 1.0 and 1.1 for the version attribute of the xsl:output element
A warning is not issued.
A warning is issued indicating that 1.0 is assumed.

15
When a character, which cannot be represented in the encoding used for output, is output in text output
The character is unreadable.
A warning is output to the standard error output and the corresponding character is output as a character reference.

16
If you specify an empty Source for the xmlSource argument of the transform(Source xmlSource, Result outputTarget) method in the Transform class
An error occurs.
The empty document generated with the newDocument method of the DocumentBuilder class is used.

17
If you specify null for the argument of the getFeature method in the TransformerFactory class
false is returned.
NullPointerException occurs.

18
When there is a prefix without a namespace declaration
The TransformerException exception occurs.
The XPathStylesheetDOM3Exception exception might occur. This exception is a subclass of the TransformerException exception and can be caught by TransformerException.

19
If you specify null for the f argument of the StreamResult(File f) constructor in the StreamResult class and the setSystemId(File f) method
The NullPointerException exception occurs.
The RuntimeException exception occurs.
However, the NullPointerException exception occurs in Java SE 6.

20
If the named template specified in the name attribute for the xsl:call-template element does not exist
(For details on the messages, see 11. KECX (Messages Output by Cosminexus XML Processor) in the manual uCosminexus Application Server Messages)
The KECX02019-E error is reported.
The KECX02019-E and KECX02015-E errors are reported.

21
Result of evaluation for an XPath expression that includes namespace::local-name
The namespace URI is resolved by considering the local name a prefix, and then the result of evaluation is the namespace node that has the string value matching with the namespace URI.
The result of the evaluation is the namespace node that has the specified local name.

22
When an inappropriate value is specified in the encoding attribute of the xsl:output element
The KECX02322-W warning is reported.
The KECX04196-W and KECX02322-W warnings are reported.

23
When the xsl:variable element contains both the select attribute and the element details
The KECX02288-E error is reported.
The KECX02019-E and KECX02288-E errors are reported.

24
When the value of the version attribute of the xsl:stylesheet element is 1.1 or more, and an inappropriate attribute is specified in the style sheet
An error occurs.
An error does not occur.

25
When the node specified in the name attribute does not exist during the generation of the processing command
The StringIndexOutOfBoundsException exception occurs.
An exception does not occur.

26
When the following sources are specified in the Source specification of the transform method:

DOMSource
- When Node is not set with the setNode method in the DOMSource generated by a constructor without an argument
- When Node specified in the constructor argument is null

SAXSource
- When InputSource is not set with the setInputSource method in the SAXSource generated by a constructor without an argument
- When the InputSource specified in the constructor argument is null

The NullPointerException exception occurs.
An exception does not occur.

27
When a style sheet with an invalid XSLT namespace declaration is entered as described below:

Example

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/2199/XSL/Transform">

The KECX02009-E error is reported.
The KECX02518-E error is reported.

28
When both the following conditions are satisfied:

OutputKeys.DOCTYPE_SYSTEM is specified with the setOutputProperty method of the Transformer class

html is specified in OutputKeys.METHOD with the setOutputProperty method of the Transformer class

HTML is specified in upper case in the generated DOCTYPE declaration.
html is specified in lower case in the generated DOCTYPE declaration.

29
When the method attribute of the xsl:output element is xml, and 1.1 is specified in the version attribute
Version="1.0" is output in the XML declaration of the output XML document
version="1.1" is output.

30
When <xsl:namespace-alias stylesheet-prefix="axsl" result-prefix="#default"> is defined in the style sheet, and the default namespace is not specified
error is invoked, and NullPointerException occurs as an exception resulting in the TransformerException exception.
error and fatalError are invoked, and the KECX02257-E error is reported.

Table A-6 Differences in XSLT operations (Comparing version 08-50 and version 08-70)

No.
Condition
Cosminexus XML Processor operations

In version 08-50
In version 08-70 and later versions

1
If XMLEventReader acquired by using the XMLInputFactory.createXMLEventReader() method is specified in the StAXSource constructor argument, and is used as an input source for the Transformer.transform() method
The processing command outside the root element of the input XML document is ignored.
The processing command outside the root element of the input XML document is also transformed.

2
When both of the following conditions are satisfied:

The elements in the input XML document for transformers belong to a non-XSLT namespace

Transformation is performed by using StAXResult created from XMLEventWriter

An error occurs during transformation or the transformation results are invalid.
Processed normally.

3
When both the following conditions are satisfied:

Transformation is performed by using xsl:sort in the style sheet of the transformer

Japanese language is specified in the sort key of the style sheet of the transformer

The output results of sorting are different in J2SE 5.0 and Java SE 6.

In version 08-70 or earlier versions

Output results of sorting are different in J2SE 5.0 and Java SE 6.

In version 09-00 and later versions

There is no difference as only Java SE 6 is used.

4
When the output method is xml, and the characters that cannot be expressed with the specified output encoding are output
The output results might differ in J2SE 5.0 and Java SE 6.

In versions up to 08-70

The output results might differ in J2SE 5.0 and Java SE 6.

In version 09-00 or later

There are no differences because only Java SE 6 is used.

Appendix A.6 Differences in the JAXB operation

The following table lists and describes the status-wise differences in JAXB operations.

Table A-7 Differences in JAXB operations (csmxjc command )

No.
Condition
Cosminexus XML Processor operations

In version 08-50
In version 08-70 and later versions

1
If the typesafeEnumClass custom binding exists in a simple XML schema document in which the enumeration facet does not exist
The csmxjc command terminates normally.
An error occurs indicating that the specification of the typesafeEnumClass custom binding is invalid.

2
When one of the following is satisfied:

If generateElementClass="true" or generateElementClass="1" is specified in the globalBindings custom binding

If class custom binding is specified in the element element of the XML schema document

The reference property of the element class is annotated by using a data type of the element (@XmlElement or @XmlElements).
Note that the default constructor is not output to the source corresponding to that element.
The reference property of the element class is annotated by using a class type of the element (@XmlElementRef or @XmlElementRefs).
The default constructor is output.

3
If the class custom binding is specified for the element element in a group element and that group element is referenced from other multiple types
Among the element elements in the group element, the factory method that creates the objects of the elements not specifying the class custom binding is not generated.
Among the element elements in the group element, the factory method that creates the objects of the elements not specifying the class custom binding is generated.

4
If collectionType="indexed" is specified for globalBindings or property custom binding
The type for the element element of the source generated by the csmxjc command is java.util.List.
The type for the element element of the source generated by the csmxjc command is an array.

5
If the csmxjc command is executed when the factoryMethod custom binding is specified in the type definition or the anonymous type element definition
An error occurs.
Terminates normally.

6
If the source generated by the csmxjc command includes the @XmlElementRef annotation type#
The required element is not output.
The required element is output.

7
If the name element of the @XmlAttribute annotation type is the same as the field name to be generated
The name element is not output.
The name element is output.

#

The required element of the @XmlElementRef annotation type is now supported in JAXB 2.2.

Table A-8 Differences in JAXB operations (csmschemagen command)

No. | Condition | Cosminexus XML Processor operations
In version 08-50 | In version 08-70 and later versions
1 | If @XmlAccessorOrder or @XmlAccessorOrder(XmlAccessOrder.UNDEFINED) is specified in the Java source | The XML schema document created by the csmschemagen command becomes the sequence element. | The XML schema document created by the csmschemagen command becomes the all element.
2 | If @XmlElementDecl is specified in the Java source | The nillable="true" attribute is output to the element element of the global definition for the XML schema document generated by the csmschemagen command. | The nillable="true" attribute is not output to the element element of the global definition for the XML schema document generated by the csmschemagen command.

Table A-9 Differences in JAXB operations (Runtime)

No. | Condition | Cosminexus XML Processor operations
In version 08-50 | In version 08-70 and later versions
1 | If a class containing variables of the java.lang.Object type annotated by the @XmlAttribute or @XmlValue annotation types, or a package name containing that class, is specified in the newInstance method for the JAXBContext class | An IllegalAnnotationsException is thrown. | A NullPointerException is thrown.
2 | If the package-info class exists in the package specified in the newInstance method for the JAXBContext class, and if the namespace is specified by using the XmlNs annotation type | The namespace declaration is not output to the XML document that is output with marshal. | The namespace declaration is output to the XML document that is output with marshal.
3 | If an XML document that only contains blank text in the JavaBean property annotated by the @XmlMixed annotation type, is un-marshaled | The text object is not generated in the object generated by un-marshal. | A blank text object is generated.
4 | In a schema validation or event handler, if an Unmarshaller that does not check errors is used to un-marshal a character string for a JavaBean property with a primitive type numeric value | An IllegalAccessError occurs. | Un-marshal processing terminates normally.
5 | If the beforeUnmarshal method or afterUnmarshal method is implemented for the classes mapped to JAXB and if that method throws an exception during un-marshal | Un-marshal processing is interrupted. | An UnmarshalException is thrown and un-marshal processing is interrupted.
6 | If null is specified in the first parameter of the newInstance(Class[], Map<String, ?>) method and newInstance(Class[]) method for the JAXBContext class | A NullPointerException is thrown. | An IllegalArgumentException is thrown.
7 | If a value other than 0, 1, false, and true is specified in the parseBoolean method for the DatatypeConverter class | false is returned. | An IllegalArgumentException is thrown.
8 | If you specify only a space in the parseDecimal method for the DatatypeConverter class | java.lang.NumberFormatException is thrown. | An exception is thrown.
9 | If the value to be un-marshaled in the enum class contains a linefeed or a space | The processing result is invalid. | The value is un-marshaled correctly.

Appendix A.7 Differences in the operation of the javax.xml.datatype package

The following table describes the differences in the operation of the javax.xml.datatype package:

Table A-10 Differences in the operation of the javax.xml.datatype package (Comparison of cases when JAXP1.3 is used on J2SE 5.0 and JAXP1.4 is used on Java SE 6)

No.
Condition
Execution result

In J2SE 5.0
In Java SE 6

1
Content of the Duration object returned by the newDurationYearMonth(long) method of the javax.xml.datatype.DatatypeFactory class
Data other than year and month is also maintained.
Data other than year and month is not maintained.

2
When null is specified in the parameter of the equals method of the javax.xml.datatype.Duration class
NullPointerException occurs.
false is returned.
NullPointerException does not occur.

Appendix A.8 Differences in the operation of the high-speed parse functionality

The following table describes the differences in the operation of the high-speed parse functionality:

Table A-11 Differences in the operation of the high-speed parse functionality (comparison of cases when JAXP1.3 is used on J2SE 5.0 and JAXP1.4 is used on Java SE 6)

No.
Condition
Execution result

In J2SE 5.0
In Java SE 6

1
When a File object including a character (such as a Japanese character or a blank) that is not allowed as the XML document name by RFC2396 is specified in the following methods:

parse(File) method of the DocumentBuilder class

parse(File, DefaultHandler) method of the SAXParser class

The following file names will be as specified in the File object:

XML document name of the tuning summary file that is to be analyzed

File name of the tuning details file

XML document name of the tuning details file that is to be analyzed

The following file names are encoded with %xx:

XML document name of the tuning summary file that is to be analyzed

File name of the tuning details file

XML document name of the tuning details file that is to be analyzed

Appendix A.9 Differences in the operation of StAX

The following table describes the differences in the operation of StAX:

Table A-12 Differences in the operation of StAX (comparison of cases when JAXP1.3 is used on J2SE 5.0 and JAXP1.4 is used on Java SE 6)

No. | Condition | Execution result
In J2SE 5.0 | In Java SE 6
1 | When the getCause method is executed in the object generated in the javax.xml.stream.XMLStreamException(Throwable) constructor | null is returned. | The Throwable object specified in the constructor is returned.

Appendix A.10 Differences in the operations of the Apache-specific functionality

Depending on the Apache-specific functionality supported in 08-70, the operations of the XML parser and XSLT/XSLTC might differ from the operations in versions 08-50 or earlier. For details on the Apache-specific functionality, see 3.5 Apache-specific functions.

Appendix B. Support Range of JAXB Specifications

This appendix describes the support range of JAXB specifications. For details about the functions, see the manual of each product.

Organization of this section

B.1 Support range of the JAXB functions

B.2 Support range for JAXB characters

B.3 Support range of functions assumed as vendor-specific according to JAXB specifications

Appendix B.1 Support range of the JAXB functions

The following table describes the support range of the JAXB functions:

Table B-1 Support range of JAXB functions

JAXB function
Overview
Supported or not

Schema compiler
Default binding
Performs default conversion.
Y

Custom binding
Customizes the conversion on the basis of binding declaration.
Y

Schema with inline annotation
Describes the binding declaration in the schema document.
Y

External binding declaration
Describes the binding declaration in the external file.
Y

Extending the binding language
Defines the vendor-specific extended binding declaration.
N

Schema generator
Default mapping
Performs default conversion.
Y

Custom mapping
Customizes the conversion on the basis of the Java annotations.
Y

Binding framework
Marshal
Outputs the Java objects as XML documents.
Y

Event callback
This is the callback method of the event generated during marshalling.
Y

Class-defined callback method
This is the callback method within the class mapped by JAXB invoked before and after marshalling.
Y

External listener
This is an external callback method invoked by the event that occurs during marshalling.
Y

Marshalling properties
Various properties for controlling marshalling.
Y

Validation
Performs validation during marshalling.
Y

Unmarshal
Reads XML document as a Java object.
Y

Event callback
This is the callback method of the event generated during un-marshalling.
Y

Class-defined callback method
This is the callback method that exists within the class mapped by JAXB invoked before and after un-marshalling.
Y

External listener
This is an external callback method invoked by the event that occurs during un-marshalling.
Y

Validation
Performs validation during un-marshalling.
Y

Introspector
This is a function for accessing information about mapping of the Java object that is mapped by JAXB.
Y

Binder
This is a function for achieving synchronization of the Java object mapped by JAXB, and the XML information set.
Y

Legend:

Y: All functions are supported.

N: Not supported

Appendix B.2 Support range for JAXB characters

You can specify any character string in the schema document that is the input for schema compiler and in the Java class that is the input for schema generator. Table B-2 describes the support range of the characters of java source input into the schema generator handled in JAXB, and Table B-3 describes the support range of characters of the schema document input into the schema compiler.

Table B-2 Support range of characters of java source input into the schema generator

No.
Specification location of any character string
Support range of the character

1
Class name
Method name
Field name
All of the following conditions must be fulfilled:

Must comprise of alphanumeric characters and underlines.

Must conform to the syntax rules for the NCName of XML.

2
Enumeration constant
The following condition must be fulfilled:

Must comprise of alphanumeric characters and underlines.

3
prefix element of @XmlNs
All of the following conditions must be fulfilled:

Must comprise of alphanumeric characters and underlines.

Must conform to the syntax rules for the NCName of XML.

4
Elements of @XmlEnumValue
defaultValue element of @XmlElement or @XmlElementDecl
The following condition must be fulfilled:

Must comprise of Unicode Basic Latin and Japanese#1.

5
name element of the JAXB mapping annotation
All of the following conditions must be fulfilled:

Must comprise of alphanumeric characters, underlines, and Japanese#1.

Must conform to the syntax rules for the NCName of XML.

6
namespace element of the JAXB mapping annotation
The following condition must be fulfilled:

Must be an URI character string provided in RFC 2396.#2

7
factoryMethod element of @XmlType
All of the following conditions must be fulfilled:

Must comprise of alphanumeric characters and underlines.

Must conform to the syntax rules for the Java identifier.

8
value element of @XmlMimeType
The following condition must be fulfilled:

Must be a MIME-type text expression.

#1

Characters included in the Unicode Hiragana, Katakana, and CJK Unified Ideographs category.

#2

RFC2732 is not supported (IPv6 not supported).

Table B-3 Support range of characters of the schema document input into the schema compiler

No.
Specification location of any character string
Support range of character

1
Attributes of the schema element that specifies the xs:anyURI type (such as the targetNamespace attribute of the xs:schema element)
The following condition must be fulfilled:

Must be an URI character string provided in RFC 2396.#1

2
Attributes of the schema element that specifies the xs:NCName type (such as the name attribute of the xs:element element)
All of the following conditions must be fulfilled when the output name is not changed with the custom binding declaration:

Must comprise of alphanumeric characters and underlines.

Must conform to the syntax rules for the NCName of XML.

All of the following conditions must be fulfilled when the output name is changed with the custom binding declaration:

Must comprise of alphanumeric characters, underlines, and Japanese#2.

Must conform to the syntax rules for the NCName of XML.

3
Attributes of the schema element that specifies the xs:QName type (such as the type attribute of the xs:element element)
All of the following conditions must be fulfilled:

Must be a character string of the QName format.

The local name must be within the range of item no. 2.

The prefix must comprise of alphanumeric characters and underlines.

4
Attribute of the schema element that specifies the xs:string type (such as the fixed or default attribute of the xs:element element, or the fixed or default attribute of the xs:attribute element)
value attribute of the jaxb:typesafeEnumMember element
The following condition must be fulfilled:

Must comprise of Unicode Basic Latin and Japanese#2.

5
value attribute of the xs:enumeration element
All of the following conditions must be fulfilled when the enumeration constant is not changed with the custom binding declaration:

Must comprise of alphanumeric characters and underlines.

Must conform to the syntax rules of the Java enumeration constant.

All of the following conditions must be fulfilled when the enumeration constant is changed with the custom binding declaration:

Must comprise of Unicode Basic Latin and Japanese#2.

6
name attribute of the JAXB element
suffix attribute of the JAXB element
prefix attribute of the JAXB element
parseMethod or printMethod attribute of the jaxb:javaType element
All of the following conditions must be fulfilled:

Must comprise of alphanumeric characters and underlines.

Must conform to the syntax rules for the Java identifier.

7
name attribute of the jaxb:package element
ref attribute of the JAXB element
collectionType attribute of the JAXB element
implClass attribute of the jaxb:class element
All of the following conditions must be fulfilled:

Must comprise of alphanumeric characters, underlines, and periods (.).

Must conform to the syntax rules for the Java package name.

8
Element contents of the jaxb:javadoc element
All of the following conditions must be satisfied:

Must be configured of Basic Latin of Unicode and Japanese language#2.

Must conform to the syntax rules of the Java command.

#1

RFC2732 is not supported (IPv6 not supported).

#2

Characters included in the category of Unicode Hiragana, Katakana, and CJK Unified Ideographs

Appendix B.3 Support range of functions assumed as vendor-specific according to JAXB specifications

The following table describes the support range of functions assumed as vendor-specific according to the JAXB specifications:

Table B-4 Support range of functions assumed as vendor-specific according to JAXB specifications

Corresponding location in JSR 222
Page number
Content of the vendor-specific function
Function support in Cosminexus XML Processor

4.3 General Validation Processing
35
Unmarshal-time validation
(Validation during unmarshal)
The functions for validation is supported during unmarshal.

On-demand validation
(On-demand validation)
The on-demand validation function is not supported.

Fail-first validation
(Fail-first validation)
The fail-first validation function is not supported.

4.5 Marshalling
41
Potentially properties
(Additional properties for marshal)
There are no Properties for marshaling that are specific to Cosminexus XML Processor.

5.2 Java Package
50
Property setter/getter
(Additional properties of the Java value class)
There are no Properties of the Java value class that are specific to Cosminexus XML Processor.

5.5.1 Simple Property
57
TypeConstraint validation
(Type constraint validation)
The type constraint validation function is not supported.

6.13 Modifying Schema-Derived Code
153
Distinguish between generated and user added code
(Identification of the auto-generated Java sources)
The identification of auto-generated Java sources is supported by -mark-generated of the csmxjc command.

7.1.1 Extending the Binding Language
159
Extending the Binding Language
(Extension of the binding declaration)
The binding declaration extension function is not supported.

7.5<globalBindings> Declaration
7.8<property> Declaration
167
189
enableFailFastCheck
(enableFailFastCheck attribute)
The enableFailFastCheck attribute is not supported.

Compatibility
294
non-default operating modes for binding schema languages
(Binding of other schema languages)
The schema compiler does not support schema languages other than the XML Schema.

Compatibility
294
non-default operating modes for mapping Java types to schema languages
(Mapping to other schema languages)
The schema generator does not support schema languages other than the XML Schema.

Appendix G
355
Validator for JAXB 1.0 schema-derived classes
(JAXB1.0 compatibility specification)
In Cosminexus XML Processor, you cannot handle classes created in JAXB 1.0.

Appendix C. Efficiently using XML Processor

This appendix describes the features and notes on the functionality that helps you to use XML Processor efficiently.

The following table describes the classification of the XML Processor functionality.

Table C-1 Classification of the XML Processor functionality

Classification of the functionality
Main Java packages related to the functionality
Overview of the functionality

JAXP
Basic functionality
DOM parser
javax.xml.parsers
org.w3c.dom
XML parsing

SAX parser
javax.xml.parsers
org.xml.sax

StAX parser
javax.xml.stream

Application functionality
XSLT
javax.xml.transform
XML document conversion and output

XPath
javax.xml.xpath
Selecting parts and acquiring information using the XPath expression

Validation
javax.xml.validation
Schema validation

JAXB
JAXB
javax.xml.bind
Data exchange

Organization of this section

C.1 Basic functionality of XML Processor

C.2 Application functionality of XML Processor

C.3 Know-how for efficiently using XML Processor

Appendix C.1 Basic functionality of XML Processor

The basic functionality of XML Processor implements the XML document parsing that is required for the processing of the XML document. This subsection describes three types of parsing functionality (parser) provided by the basic functionality of XML Processor and the features of each parser.

Organization of this subsection

(1) DOM parser

(2) SAX parser

(3) StAX parser

(4) Merits and demerits of each parser

(1) DOM parser

(a) Overview

The DOM parser parses all the elements, attributes, and text included in an XML document, and expands their contents as an object tree called the DOM tree in the memory. By using the DOM API, you can freely traverse the DOM tree and you can reference, update, or delete any data item.

(b) Optimum usage

To process an XML document extensively

To process XML document content that requires processing in a complicated order

To edit the contents of an XML document

(2) SAX parser

(a) Overview

The SAX parser is an event-driven parser that parses an XML document sequentially from the beginning, and invokes predefined processing (callback method) whenever parsing events such as starting or stopping of elements, text, or processing instructions, occur.

When parsing starts, a callback method is invoked every time according to the type of the parsing event, and the parsing data, such as the element name or text data, is passed as an argument to the callback method.

You can perform processing in accordance with the content of the XML document by defining the processing content of the callback method in advance.

(b) Optimum usage

To process an XML document with a simple structure

For read-only processing, when the XML document contents need not be edited

(3) StAX parser

(a) Overview

The StAX parser, like the SAX parser, is an event-driven parser that parses an XML document sequentially from the beginning.

In the case of a StAX parser, parsing advances when the user requests a parsing event to the parser, and therefore, if you use a StAX parser, you can easily move ahead and interrupt the parsing process at any time. Also, by requesting a parsing event to a StAX parser, and assigning the processing as per the type and content of the parsing data acquired by requesting the parsing event, you can execute the processing in accordance with the contents of the XML document.

(b) Optimum usage

To process the contents of a huge XML document partially

(4) Merits and demerits of each parser

The following table describes the merits and demerits of each parser.

Table C-2 Features of each parser

Parser type | Merit | Demerit
DOM parser | You can perform editing operations, such as addition or deletion, for an XML document. | Compared to the other parsers, the amount of memory consumed is large and the processing speed is slow.
SAX parser | Compared to the other parsers, the amount of memory consumed is small, and the processing speed is high. | You cannot perform editing operations, such as addition or deletion, for an XML document.
StAX parser | In addition to the above merits of the SAX parser, the user can control the execution or interruption of parsing. | The XML schema-based validation cannot be executed with the StAX parser alone.

Appendix C.2 Application functionality of XML Processor

The application functionality of XML Processor increases the convenience and maintainability by making the advanced and complex XML-related technology easily available.

The application functionality is implemented by using and integrating the basic functionality. Therefore, if the processing is simple, you can use the basic functionality instead of the application functionality.

For example, for a simple conversion processing such as renaming a specific element name in an XML document, you can implement the processing with the basic functionality of a parser such as a DOM parser, even if you do not use XSLT.

As a general tendency, the basic functionality has the advantage of a higher processing speed, but on the other hand, has the demerit that the basic functionality requires coding dependent on the XML document structure and that the coded code might be complicated. You must comprehensively determine which functionality is most appropriate for use based on the execution performance, memory performance, maintainability of the programs, and the features of the system and the data to be handled.

This subsection describes the application functionality of XML Processor.

Organization of this subsection

(1) XSLT functionality

(2) XPath functionality

(3) Validation functionality

(4) JAXB functionality

(1) XSLT functionality

The XSLT functionality converts an XML document into an XML document with a different structure, or into an HTML document or plain text.

The conversion rules are defined in an XML document called XSLT style sheet, so you need not code complicated conversion processing as programs, and the development and maintenance of programs becomes easy.

(2) XPath functionality

The XPath functionality uses the expression (XPath expression) that indicates a specific position in an XML document to extract specific parts from an XML document and acquire information related to the document content and document structure.

You can use a simple code to check whether a specific element or attribute exists in the XML document and to acquire a part of the XML document.

(3) Validation functionality

The Validation functionality makes the XML schema-based validation processing more efficient by converting the syntax rules defined in the XML schema into objects.

To use one XML schema document for multiple validation processing, if you use the basic functionality, the XML schema document is parsed to ensure that a syntax rule is generated for every parsing. If you use the Validation functionality, the syntax rules of the XML schema can be re-used as objects, so the schema document is parsed only once.

(4) JAXB functionality

The JAXB functionality is used to easily code the data exchange processing that reads the data included in an XML document into a Java class, and outputs the data from the Java class as an XML document.

This functionality, when used together with additional functionality that auto-generates an XML schema document from a Java class and a Java class from the XML schema, offers great flexibility in changing the data structure as well.

Appendix C.3 Know-how for efficiently using XML Processor

This subsection provides the know-how for efficiently using XML Processor.

The following methods exclusively control the threads internally. Therefore, if multiple threads invoke these methods concurrently, exclusive waiting might occur and the throughput might be affected:

The newInstance method of the factory classes of the following JAXP APIs:
javax.xml.datatype.DatatypeFactory
javax.xml.parsers.DocumentBuilderFactory
javax.xml.parsers.SAXParserFactory
javax.xml.transform.TransformerFactory
javax.xml.validation.SchemaFactory
javax.xml.xpath.XPathFactory

The newDocumentBuilder method of the javax.xml.parsers.DocumentBuilder class

The transform method of the javax.xml.transform.Transformer class

The evaluate method of the javax.xml.XPath class

Among these methods, the methods from 1 to 2 generate objects, so the processing is comparatively heavy. Therefore, re-use the generated objects and preferably do not invoke these methods frequently.

If you need to create multiple Transformers from the same style sheet with the XSLT functionality, instead of creating Transformer directly from TransformerFactory, creating one Templates object, and then creating multiple Transformers from this object is advantageous with respect to the execution performance.

To re-use the same XPath expression with the XPath functionality, using the compile method of the XPath class, and creating and re-using the XPathExpression object is advantageous with respect to the execution performance.

You can use the DOM API to implement the same processing as the XPath functionality. Using the DOM API is advantageous in terms of the execution speed, but you must code a complicated process depending on the structure of the input XML document, and furthermore, when the structure of the XML document is changed, you must re-write the processing, so this process is inferior to XPath in terms of maintainability.

Instead of the Validation functionality, you can also implement the validation processing using the XML schema with a DOM parser or SAX parser; however, when you repeat the validation processing by using the same schema document, the Validation functionality that can re-use the schema document parsing results as objects is advantageous with respect to the execution performance.

The generation of the JAXBContext object increases the load, so re-using the objects as much as possible is advantageous with respect to the execution performance.

Appendix D. Glossary

Terminology used in this manual

For the terms used in the manual, see the uCosminexus Application Server and BPM/ESB Platform Terminology Guide.

Index

[A][B][C][D][E][F][G][H][J][K][L][M][N][O][P][S][T][V][W][X]

(A)

application functionality

application functionality of XML Processor

attribute to use

type of the schema document to identify

(B)

basic functionality

basic functionality of XML Processor

(C)

case where XSLT does not report errors

note on XSLT

changes to program

XSLTC transformer function

class

high-speed parse support function

XSLTC transformer

common note

compatibility option functionality

correspondence between the encoding specification for XML document and the applicable character encoding

Cosminexus XML Processor

difference between version

JAXP function

note

overview

package name

positioning

product feature

range of features

SAX2 features

SAX2 properties

creating

Pre-Parse XML document

csmschemagen command (mapping Java to XML schema)

csmxjc command (binding XML schema to Java)

(D)

details

tuning details file

tuning summary file

difference between version

difference in JAXB operation

difference in JAXB operation

Difference in operation of high-speed parse functionality

Difference in operation of javax.xml.datatype package

Difference in operation of StAX

differences in behaviors

DOM and SAX parser

DOM parser

SAX parser

schema validation

XSLT

differences in operations of Apache-specific functionality

DOM and SAX parser

differences in behaviors

DOM parser

differences in behaviors

general procedure for creating a sample program

how to use Shift_JIS switch function

note

sample program

sample program

DOM parser

(E)

efficiently using XML Processor

encoding

processable

error message in XML schema

W3C specification

(F)

feature (Apache-specific)

features and properties

how to use

flow

converting XML document in JAXP

parsing XML document in JAXP

flow of processing

application for DOM parse

application for evaluating XPath expression

application for handling SAX event

application for loading and saving XML document

application for manipulating DOM tree

application for processing date and time format data

application for SAX parse

application for validating XML document by using class included in javax.xml.validation package

application for XSLT-based transformation

function

XML parser and XSLT transformer

functionality for validated parsing compatibility

(G)

general procedure for creating sample program

SAX parser

general XML Processor related notes

generating

preparsed object

(H)

high-speed parse support function

class

coding example

flow of operation

how to output tuning information

how to use tuning information

output destination

overview

parse method

system property

tuning Pre-Parse XML document

type of tuning information

how to create

program

how to set schema document

XML document

how to set the XML schema properties

DOM parser

how to set up preparsed object

DocumentBuilder

SAXParser

XMLReader

how to set XML schema properties

SAX parser

how to use

features and properties

SAX2 features

SAX2 features and properties

SAX2 properties

XML schema property

XSLTC transformer

XSLT features

how to use feature and property

XSLT

how to use features and properties

high-speed parse support function

Shift_JIS switch function

how to use property

StAX

how to use Shift_JIS switch function

DOM parser

SAX parser

XSLT transformer

how to use StAX property

(J)

javax.xml.datatype package

javax.xml.namespace package

javax.xml.parsers package

javax.xml.stream.events package

javax.xml.stream.util package

javax.xml.stream package

javax.xml.transform.dom package

javax.xml.transform.sax package

javax.xml.transform.stax package

javax.xml.transform.stream package

javax.xml.transform package

javax.xml.validation package

javax.xml.xpath package

javax.xml package

JAXB

JAXB commands

JAXB-defined package

API

JAXB functionality

JAXP

XSLT features

JAXP-defined package

API

javax.xml

javax.xml.datatype

javax.xml.namespace

javax.xml.parsers

javax.xml.sax

javax.xml.transform

javax.xml.transform.dom

javax.xml.transform.sax

javax.xml.transform.stream

javax.xml.validation

javax.xml.xpath

org.w3c.dom

org.w3c.dom.bootstrap

org.w3c.dom.events

org.w3c.dom.ls

org.xml.sax.ext

org.xml.sax.helpers

javax.xml.stream

javax.xml.stream.events

javax.xml.stream.util

javax.xml.transform.stax

(K)

know-how for efficiently using XML Processor

(L)

list of command

(M)

merits and demerits of each parser

MS932

(N)

namespace URI (Apache-specific)

note

Cosminexus XML Processor

DOM parser

high-speed parse support function

implementation-dependent specification

javax.xml.datatype package

javax.xml.validation package

javax.xml.xpath package

JAXB

org.w3c.dom.ls package

org.w3c.dom bootstrap package

org.w3c.dom package

org.xml.sax.ext package

parse performance

runtime

SAX parser

schema compiler

schema generator

schema validation

XInclude

XSLT

XSLT

XSLT and XSLTC

XSLTC

note on XSLTC

note on high-speed parse support function

how to specify an absolute path

Pre-Parse XML document

setting up preparsed object

tuning information

XInclude

XML1.1

XML parser using preparsed object

note on XSLT

case where XSLT does not report errors

note on XSLTC

case where XSLTC does not report errors

others

stylesheet size

transformation performance

XPath expression

XSLT element

notes

schema cache functionality

notes (General XML Processor)

Notes common to JAXP1.4 function

(O)

org.w3c.dom.bootstrap package

org.w3c.dom.events package

org.w3c.dom.ls package

org.w3c.dom package

org.xml.sax.ext package

org.xml.sax.helpers package

org.xml.sax package

overview

Cosminexus XML Processor

XSLTC transformer

overview of schema cache functionality

(P)

package name

Cosminexus XML Processor

parser switching functionality

parsing

XML document

positioning

Cosminexus XML Processor

Pre-Parse XML document

precautions related to schema cache functionality

precautions related to error output

precautions related to performance

precautions related to reset up and deletion of cache

precautions related to schema definition files

preparsed object

PreparsedObject class

PreparsedObjectFactory class

product feature

Cosminexus XML Processor

program creation procedure

program execution

troubleshooting

property (Apache-specific)

property value

(S)

sample program

DOM parser

DOM parser

flow of processing using XML schema

procedure for using DOM parser

procedure for using XSLT transformer

SAX parser

SAX parser

XML schema

XSLTC transformer

XSLT transformer

SAX2 features

Cosminexus XML Processor

how to use

SAX2 features and properties

how to use

SAX2 properties

Cosminexus XML Processor

how to use

SAX parser

differences in behaviors

general procedure for creating sample program

how to use Shift_JIS switch function

note

sample program

sample program

SAX parser

schema cache functionality

schema document

personalData.xsd

purchaseOrder.xsd

schema validation

differences in behaviors

note

setting up

preparsed object

Shift_JIS switch function

Shift_JIS switch function

SJIS

specification

JAXB

StAX parser

support range

function assumed as vendor-specific according to JAXB specification

JAXB function

JAXB specification

support range for JAXB characters

system development and operation

XSLTC transformer

(T)

TransformerFactoryXSLTC class

translet

troubleshooting

program execution

tuning details file

tuning summary file

type of schema document to identify

attribute to use

(V)

validation functionality

(W)

W3C specification

error message in XML schema

whitespace

(X)

XML document

how to set schema document

purchaseOrder-fail.xml

purchaseOrder.xml

XML parser and XSLT transformer

available function

XML schema

flow of processing for creating sample program

sample program

XML schema property

how to use

XPath functionality

XSLT

differences in behaviors

note

XSLT and XSLTC

note

XSLTC

note

XSLTC transformer

class

how to use

overview

sample program

system development and operation

XSLTC transformer function

changes to program

XSLT features

how to use

JAXP

XSLT functionality

XSLT transformer

general procedure for creating sample program

how to use Shift_JIS switch function

sample program

Trademarks

AIX is a trademark of International Business Machines Corporation in the United States, other countries, or both.
Microsoft is either a registered trademark or trademark of Microsoft Corporation in the United States and/or other countries.
Oracle and Java are registered trademarks of Oracle Corporation and/or its affiliates.
SOAP is an XML-based protocol for sending messages and making remote procedure calls in a distributed environment.
UNIX is a registered trademark of The Open Group in the United States and other countries.
W3C is a trademark (registered in numerous countries) of the World Wide Web Consortium.
Windows, Windows Server, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
Other product and company names mentioned in this document may be trademarks or registered trademarks of their respective owners.
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).
Throughout this document Hitachi has attempted to distinguish trademarks from descriptive terms by writing the name with the capitalization used by the manufacturer, or by writing the name with initial capital letters. Hitachi cannot attest to the accuracy of this information. Use of a trademark in this document should not be regarded as affecting the validity of the trademark.