jXTransformer

User’s Guide

March 2002
© 2002 DataDirect Technologies. All rights reserved. Printed in the U.S.A.

DataDirect, DataDirect Connect, and SequeLink are registered trademarks, and

Client/Server MiddleWare, DataDirect Connect ADO, DataDirect Connect Integrator,
DataDirect Connect JDBC, DataDirect Connect ODBC, DataDirect Connect OLE DB,
DataDirect Connect Premium, DataDirect Reflector, and DataDirect SequeLink
Integrator are trademarks of DataDirect Technologies. All other trademarks are the
property of their respective owners.

This product includes Xerces, developed by the Apache Software Foundation

(http://www.apache.org). Copyright (C) 1999-2000 The Apache Software Foundation.
All rights reserved.

This product includes Xalan, developed by the Apache Software Foundation

(http://www.apache.org). Copyright (C) 1999-2000 The Apache Software Foundation.
All rights reserved.

This product includes JDOM, developed by the JDOM Project (http://www.jdom.org).

Copyright (C) 2000 Brett McLaughlin & Jason Hunter. All rights reserved.

No part of this publication, with the exception of the software product user
documentation contained in electronic format, may be copied, photocopied,
reproduced, transmitted, transcribed, or reduced to any electronic medium or
machine-readable form without prior written consent of DataDirect Technologies.

Licensees may duplicate the software product user documentation contained on a

CD-ROM, but only to the extent necessary to support the users authorized access to
the software under the license agreement. Any reproduction of the documentation,
regardless of whether the documentation is reproduced in whole or in part, must be
accompanied by this copyright statement in its entirety, without modification.

U.S. GOVERNMENT RESTRICTED RIGHTS. It is acknowledged that the Software and

the Documentation were developed at private expense, that no part is in the public
domain, and that the Software and Documentation are Commercial Computer
Software provided with RESTRICTED RIGHTS under Federal Acquisition Regulations
and agency supplements to them. Use, duplication or disclosure by the U.S.
Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of The
Rights in Technical Data and Computer Software clause at DFAR 252.227-7013 et. seq.
or subparagraphs (c)(1) and (2) of the Commercial Computer Software Restricted
Rights at FAR 52.227-19, as applicable. Contractor is
DataDirect Technologies, 3202 Tower Oaks Blvd. Suite 300,
Rockville, Maryland 20852. Rights are reserved under copyright laws of the United
States with respect to unpublished portions of the Software.

DataDirect Technologies
3202 Tower Oaks Blvd. Suite 300
Rockville, Maryland 20852
 3

Table of Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
What Is DataDirect jXTransformer? . . . . . . . . . . . . . . . . . . . . . 9
Using This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Conventions Used in This Book. . . . . . . . . . . . . . . . . . . . . . . . . 11
About DataDirect Documentation . . . . . . . . . . . . . . . . . . . . . . 13
Contacting Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . 14

1 jXTransformer Overview . . . . . . . . . . . . . . . . . . . . . . 17
jXTransformer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Transforming Relational Data into XML . . . . . . . . . . . . . . . . . 18
jXTransformer Query Example . . . . . . . . . . . . . . . . . . . . . . 19
jXTransformer Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Using jXTransformer Queries in JDBC Applications . . . . . . 22
Updating Your Database With Data From XML . . . . . . . . . . . 23
jXTransformer Write Statement Example . . . . . . . . . . . . . 24
Using jXTransformer Write Statements in
JDBC Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

2 Understanding jXTransformer . . . . . . . . . . . . . . . . . 29
Using jXTransformer Queries . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Creating Hierarchical XML Documents. . . . . . . . . . . . . . . . 29
Using Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Hiding Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Creating ID/IDREFS Links . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Creating XML Document Fragments . . . . . . . . . . . . . . . . . 36
Generating DTDs and Schemas . . . . . . . . . . . . . . . . . . . . . . 38
Choosing an XML Document Structure . . . . . . . . . . . . . . . 39

jXTransformer User’s Guide

4 Table of Contents

Choosing an XML Output Format . . . . . . . . . . . . . . . . . . . 41

Choosing a jXTransformer Query Rewrite Algorithm . . . 42
Using jXTransformer Write Statements. . . . . . . . . . . . . . . . . . 44
jXTransformer Write Statement Processing Overview . . . 44
Choosing an XML Input Format. . . . . . . . . . . . . . . . . . . . . 45

3 Creating jXTransformer Queries Using the

jXTransformer Builder . . . . . . . . . . . . . . . . . . . . . . . . 47
Working with the jXTransformer Builder . . . . . . . . . . . . . . . . 48
Using Tree and Text Views . . . . . . . . . . . . . . . . . . . . . . . . . 48
Using Project Tree Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Working with Project Tree Nodes . . . . . . . . . . . . . . . . . . . 53
Using Base SQL Query Nodes . . . . . . . . . . . . . . . . . . . . . . . 53
Creating Complete XML Documents . . . . . . . . . . . . . . . . . 55
Starting the jXTransformer Builder . . . . . . . . . . . . . . . . . . . . . 55
Customizing the jXTransformer Builder . . . . . . . . . . . . . . . . . 56
Changing the General Appearance of the GUI . . . . . . . . 57
Changing the Text Editor . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Specifying Named Drivers . . . . . . . . . . . . . . . . . . . . . . . . . 61
Creating a New jXTransformer Builder Project . . . . . . . . . . . 63
Opening a jXTransformer Builder Project . . . . . . . . . . . . . . . . 64
Closing a jXTransformer Builder Project . . . . . . . . . . . . . . . . . 64
Creating and Modifying jXTransformer Queries in
Tree View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Turning on the Document Header . . . . . . . . . . . . . . . . . . 66
Specifying Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Specifying Processing Instructions . . . . . . . . . . . . . . . . . . . 67
Specifying an External DTD . . . . . . . . . . . . . . . . . . . . . . . . 69
Creating Base SQL Query Nodes . . . . . . . . . . . . . . . . . . . . 70
Creating XML Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Creating XML Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Specifying Hide Information . . . . . . . . . . . . . . . . . . . . . . . 76
Creating XML CDATA Sections. . . . . . . . . . . . . . . . . . . . . . 77

jXTransformer User’s Guide

 Table of Contents 5

Specifying XML Namespaces . . . . . . . . . . . . . . . . . . . . . . . . 79

Assigning Select Expression Values to
ELEMENT Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Assigning Constant Values to ELEMENT Nodes . . . . . . . . . 80
Modifying Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Moving Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Deleting Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Creating and Modifying jXTransformer Queries
in Text View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Checking jXTransformer Query Syntax. . . . . . . . . . . . . . . . . . . 84
Connecting to the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Connecting Using JDBC Connection URLs . . . . . . . . . . . . . 86
Connecting Using JDBC Data Sources. . . . . . . . . . . . . . . . . 87
Executing a jXTransformer Query. . . . . . . . . . . . . . . . . . . . . . . 89
Browsing the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Using the Database Browser . . . . . . . . . . . . . . . . . . . . . . . . 93
Customizing JDBC Filter Settings . . . . . . . . . . . . . . . . . . . . 95
Opening an XML DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Opening an XML Document . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Generating DTDs or XML Schemas From a
jXTransformer Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Generating a DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Generating an XML Schema . . . . . . . . . . . . . . . . . . . . . . . . 103

4 Syntax of jXTransformer Queries . . . . . . . . . . . . . . . 107

xml_document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
xml_document_info. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
xml_constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
xml_element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
xml_attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
xml_cdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
xml_namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

jXTransformer User’s Guide

6 Table of Contents

xml_hide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
select_expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
rest_of_sql99_select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Rules and Exceptions for jXTransformer Query Syntax . . . . . 127
Executing jXTransformer Queries . . . . . . . . . . . . . . . . . . . . . . 127

5 Syntax of jXTransformer Write Statements. . . . . . . 129

Insert Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Delete Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Executing jXTransformer Write Statements . . . . . . . . . . . . . . 145

6 Using the jXTransformer API . . . . . . . . . . . . . . . . . . 147

jXTransformer API Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
JXTRQuery and JXTRResultSetWrapper Classes . . . . . . . . 152
JXTRUpdate and JXTRSingleTableUpdate Classes . . . . . . 154
Coding jXTransformer Queries and Write Statements
in JDBC Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Example A: jXTransformer Query . . . . . . . . . . . . . . . . . . . 159
Example B: jXTransformer Write Statement . . . . . . . . . . . 162

7 Tutorial: Using jXTransformer Queries . . . . . . . . . . 167

Creating the jXTransformer Builder Project . . . . . . . . . . . . . . 170
Constructing the Parent Query . . . . . . . . . . . . . . . . . . . . . . . . 173
Constructing the Child Query . . . . . . . . . . . . . . . . . . . . . . . . . 180
Specifying Document-Level Constructs in
the jXTransformer Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Adding the Root Element . . . . . . . . . . . . . . . . . . . . . . . . . 188
Adding an Attribute to the Root Element . . . . . . . . . . . . 190
Add Namespaces to the Root Element . . . . . . . . . . . . . . . 191
Adding a Comment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

jXTransformer User’s Guide

 Table of Contents 7

Adding a Reference to an External DTD . . . . . . . . . . . . . . 194

Adding a Processing Instruction . . . . . . . . . . . . . . . . . . . . . 195
Executing the jXTransformer Query . . . . . . . . . . . . . . . . . . 196
Coding the jXTransformer Query in a JDBC Application. . . . . 200
Example A: Document-Level Constructs
in the jXTransformer Query . . . . . . . . . . . . . . . . . . . . . . . . 200
Example B: Document-Level Constructs
in the jXTransformer API . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

A JDBC Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

B jXTransformer Statement Processing . . . . . . . . . . . . 211

Handling of JDBC PreparedStatement Objects . . . . . . . . . . . . 211
Using Namespaces in XPath Expressions for
jXTransformer Write Statements . . . . . . . . . . . . . . . . . . . . . . . 212
Using NULL Replacement Values for jXTransformer Write
Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

jXTransformer User’s Guide

8 Table of Contents

jXTransformer User’s Guide

 9

Preface

This book is your guide to using the DataDirect® jXTransformer

product from DataDirect Technologies. Read on to find out more
about jXTransformer and how to use this book.

What Is DataDirect jXTransformer?

jXTransformer is a developer’s tool that works with the
DataDirect JDBC drivers to provide enhanced XML support.
jXTransformer defines and implements grammar that allows you
to perform the following tasks:

■ Read data from relational databases and transform that data

into complex XML structures. jXTransformer allows you to
structure that data any way to create XML documents for
data exchange—XML which can be transported to the Web
or used in a JDBC application. The jXTransformer Builder tool
makes it easy for you to build and test jXTransformer queries.
■ Write data stored in XML documents to relational databases,
so you can update data stored in relational databases with
changes made to XML documents through Web interfaces.

jXTransformer is packaged with DataDirect JDBC products.

jXTransformer User’s Guide

10 Preface

Using This Book

This book assumes that you are familiar with your operating
system and its commands; the concept of directories; the
management of user accounts and security access; and your
network protocol and its configuration.

This book contains the following information:

■ Chapter 1, “jXTransformer Overview” on page 17 provides an
overview of the jXTransformer product that is shipped with
the DataDirect JDBC drivers.
■ Chapter 2, “Understanding jXTransformer” on page 29
describes some of the key features of jXTransformer and
provides examples that will help you decide how to use them.
■ Chapter 3, “Creating jXTransformer Queries Using the
jXTransformer Builder” on page 47 explains how to create
jXTransformer queries using the jXTransformer Builder.
■ Chapter 4, “Syntax of jXTransformer Queries” on page 107
describes the grammar and syntax of jXTransformer queries.
■ Chapter 5, “Syntax of jXTransformer Write Statements” on
page 129 describes the grammar and syntax of jXTransformer
Insert, Update, and Delete statements.
■ Chapter 6, “Using the jXTransformer API” on page 147
describes the jXTransformer API classes and methods you can
use to execute jXTransformer queries and jXTransformer write
statements. It also provides information about coding
jXTransformer queries and write statements in JDBC
applications.

■ Chapter 7, “Tutorial: Using jXTransformer Queries” on

page 167 contains a step-by-step tutorial that shows you how
to create a jXTransformer query from scratch using the
jXTransformer Builder. It also shows you how to embed that
query in a JDBC application using the jXTransformer API.

jXTransformer User’s Guide

 Conventions Used in This Book 11

■ Appendix A, “JDBC Data Types” on page 209 lists the JDBC

data types supported by jXTransformer and the XML
representations to which they are converted by the
DataDirect JDBC driver.
■ Appendix B, “jXTransformer Statement Processing” on
page 211 provides additional information that you need to
know about how jXTransformer processes jXTransformer
query and write statements.

In addition, this book contains a “Glossary” on page 213 that

defines terms used in this book.

NOTE: This book refers the reader to Web URLs for more
information about specific topics, including Web URLs not
maintained by DataDirect Technologies. Because it is the nature
of Web content to change frequently, DataDirect Technologies
can guarantee only that the URLs referenced in this book were
correct at the time of publishing.

Conventions Used in This Book

This section describes the typography, terminology, and other
conventions used in this guide.

Typographical Conventions
This guide uses the following typographical conventions:

Convention Explanation
italics Introduces new terms that you may not be
familiar with, and is used occasionally for
emphasis.

jXTransformer User’s Guide

12 Preface

Convention Explanation
bold Emphasizes important information. Also
indicates button, menu, and icon names on
which you can act. For example, click Next.
UPPERCASE Indicates the name of a file. For operating
environments that use case-sensitive
filenames, the correct capitalization is used in
information specific to those environments.
Also indicates keys or key combinations that
you can use. For example, press the ENTER
key.
monospace Indicates syntax examples, values that you
specify, or results that you receive.
monospaced Indicates names that are placeholders for
italics values you specify; for example, filename.
forward slash / Separates menus and their associated
commands. For example, Select File / Copy
means to select Copy from the File menu.
vertical rule | Indicates an OR separator to delineate items.
brackets [ ] Indicates optional items. For example, in the
following statement: SELECT [DISTINCT],
DISTINCT is an optional keyword.
braces { } Indicates that you must select one item. For
example, {yes | no} means you must specify
either yes or no.
ellipsis . . . Indicates that the immediately preceding item
can be repeated any number of times in
succession. An ellipsis following a closing
bracket indicates that all information in that
unit can be repeated.

jXTransformer User’s Guide

 About DataDirect Documentation 13

Mouse Conventions
This action… Means to…
Click Point to an object with the mouse pointer
and press the left mouse button.
Double-click Click the left mouse button twice.
Right-click Click the right mouse button.
Drag Press and hold the left mouse button while
dragging item(s) to another part of the
screen.
SHIFT+Click Press and hold the SHIFT key; then click a
selection. This lets you select a series of
objects.
CTRL+Click Press and hold the CTRL key; then click a
selection. This lets you select objects
randomly.

Keyboard Conventions
Select menu items by using the mouse or pressing ALT+ the key
letter of the menu name or item.

About DataDirect Documentation

The DataDirect documentation is provided on your DataDirect
CD in PDF format, which allows you to view it online or print it.
You can view the online documentation using Adobe Acrobat
Reader. The DataDirect CD includes Acrobat Reader 4.x with
Search. DataDirect product documentation is also available on
the DataDirect Web site:

http://www.datadirect-technologies.com/download/docs/
dochome.asp

jXTransformer User’s Guide

14 Preface

HTML-based online help for the jXTransformer Builder is placed

on your system during the installation of your DataDirect
product. It is located in the help directory within the
jXTransformer installation directory.

To access help for the jXTransformer Builder, you must have

Internet Explorer 5.x or higher, or Netscape 4.x or higher
installed. Open the online help by selecting Help / Contents in the
jXTransformer Builder.

NOTE: Depending on your configuration, you may have to

configure the Web browser as described in “Changing the
General Appearance of the GUI” on page 57 before you can use
the jXTransformer help or the Web links in the Help menu.

Contacting Technical Support

DataDirect Technologies provides technical support for all
registered users of this product, including limited installation
support, for the first 30 days. You can register online for your
SupportLink user ID and password, which provide access to the
password-protected areas of the SupportLink web site, at
http://support.datadirect-technologies.com. Select Register on
the left toolbar, complete the information on the Register page,
and click Submit. Your user ID and password are issued to you by
email upon registration.

For support after 30 days, contact us using one of the following

methods or purchase further support by enrolling in the
SupportLink program. For more information about SupportLink,
contact your sales representative.

The DataDirect Technologies web site provides the latest support

information through SupportLink Online, our global service
network that provides access to support contact details, tools,
and valuable information. Our SupportLink users access

jXTransformer User’s Guide

 Contacting Technical Support 15

information using the web and automatic email notification.

SupportLink Online includes a knowledge base that allows you
to search on keywords for technical bulletins and other
information. You also can download product fixes and upgrades
for your DataDirect products.
World Wide Web
http://support.datadirect-technologies.com

E-Mail
USA, Canada, Mexico, [email protected]
Australia, and Asia
Pacific (except Japan)
Japan [email protected]
All other countries [email protected]

Local Telephone Support

Local phone numbers can be found at:
http://support.datadirect-technologies.com/websupport/supportnet/datadirect/
supportnetanswerline.asp
NOTE: You must have a SupportLink user ID and password to access this web
site. You can register online for your SupportLink user ID and password at
http://support.datadirect-technologies.com. Select Register on the left toolbar,
complete the information on the Register page, and click Submit. Your user ID
and password are issued immediately and confirmation is sent to you by email.
Answerline support is available 24 hours a day, seven days a week.

Fax Information
Fax US 1 919 461 4527
Fax International +32 (0) 15 32 09 19

When you contact us, please provide the following information:

■ The product serial number or a case number. If you do not

have a SupportLink contract, we will ask you to speak with a
sales representative.

jXTransformer User’s Guide

16 Preface

■ Your name and organization. For a first-time call, you may be

asked for full customer information, including location and
contact details.
■ The version number of your DataDirect product.
■ The type and version of your operating system.
■ Any third-party software or other environment information
required to understand the problem.
■ A brief description of the problem, including any error
messages that you have received, and the steps preceding the
occurrence of the problem. Depending on the complexity of
the problem, you may be asked to submit an example so that
we can recreate the problem.
■ An assessment of the severity level of the problem.

jXTransformer User’s Guide

 17

1 jXTransformer Overview

jXTransformer is a developer’s tool that works with the

DataDirect JDBC drivers to provide enhanced XML support.
jXTransformer defines and implements grammar that allows you
to perform the following tasks:

■ Read data from relational databases and transform that data

into complex XML structures. The jXTransformer grammar for
reading data is similar to the SQL99 database language. For
more information about transforming relational data into
XML using jXTransformer, see “Transforming Relational Data
into XML” on page 18.
■ Write data stored in XML documents to relational databases.
The jXTransformer grammar for writing data is similar to a
combination of the SQL99 database language and XML Path
Language (XPath). For more information about writing data
from XML to relational databases, see “Updating Your
Database With Data From XML” on page 23.

jXTransformer Support
jXTransformer supports the following features:
■ Read and write access to any relational database supported
by the DataDirect JDBC driver. Refer to your DataDirect
product README for details about which DataDirect JDBC
drivers support jXTransformer.
■ Creation of simple or complex hierarchical XML documents
and XML document fragments.

jXTransformer User’s Guide

18 Chapter 1 jXTransformer Overview

■ jXTransformer Builder GUI tool that allows you to quickly

create, modify, and test jXTransformer queries without having
to know the details of the jXTransformer query grammar.
■ JAXP 1.1, DOM level 2, JDOM 1.0 Beta 7, SAX-2, XPath 1.0,
and reader/writer object interfaces for use by JDBC
applications.
■ DTDs, XML schemas, namespaces, and CDATA.
■ Document-level constructs for jXTransformer queries that
provide specifications for XML root elements, external DTDs,
comments, and processing instructions.
■ Nested queries, parameter markers, SQL99 Select expressions,
and JDBC scalar functions within jXTransformer queries.

Transforming Relational Data into XML

To retrieve data from a relational database and transform it into
XML, you use a jXTransformer query using the jXTransformer
grammar. A jXTransformer query contains instructions that
control which data in the database is retrieved and how the
returned result set is transformed into XML.

jXTransformer is flexible, allowing you to define the relationships

and hierarchy of data that best fits your needs in the
jXTransformer query. When you create a jXTransformer query,
you choose which data to retrieve from the database and how
you want that data structured in the resulting XML.

For example, suppose your company uses data stored in an Oracle

database for billing purposes. You may want to make some of the
same data available over your company’s Intranet for project
planning purposes. Using jXTransformer, you can create
jXTransformer queries to structure that information any way you
want it in XML. You can create one jXTransformer query that lists

jXTransformer User’s Guide

 Transforming Relational Data into XML 19

each project by employee and their billable hours. You also can
create another jXTransformer query that lists each employee by
their project assignment and billable hours.

jXTransformer also provides powerful XML fine-tuning, allowing

you to create well-formed and valid XML documents for data
exchange that can contain robust XML constructs such as DTD
and schema references. For example, let us suppose your
company has defined several DTDs to which all company-wide
XML data must adhere. Using jXTransformer, you can construct a
jXTransformer query to return an XML document that can be
validated against a specified DTD.

jXTransformer Query Example

A jXTransformer query contains two types of instructions for the
jXTransformer API. The first type contains information about
which data in the database to retrieve, and the second type
provides information about how to transform the returned
result set into XML.

A jXTransformer query is similar to a SQL99 query. For example,

let us look at a simple SQL99 query:
select
e.EmployeeID,
e.FirstName,
e.LastName,
e.Title,
e.HireDate,
e.Salary
from Employees e where e.HireDate >= {d '2000-01-01'}

jXTransformer User’s Guide

20 Chapter 1 jXTransformer Overview

Now, let us compare the preceding query with a jXTransformer

query that uses the same Select statement and adds
jXTransformer grammar constructs about how to structure the
data the query retrieves in XML:
xml_document(xml_element(’result’,
select
xml_element(’Employees_Info’
xml_attribute(’ID’, e.EmployeeID),
xml_element(’name’,
xml_element(’first’, e.FirstName),
xml_element(’last’, e.LastName) ),
xml_element(’title’, e.Title),
xml_element(’hiredate’, e.HireDate),
xml_element(’salary’, e.Salary) )
from Employees e where e.HireDate >= {d ’2000-01-01’} )

Notice that in this example we used every column specified in the

SQL99 query and coded jXTransformer grammar constructs
around the columns. For example, the data contained in the
EmployeeID column becomes an attribute of the parent XML
element named Employees_Info, and the data retrieved from the
FirstName and LastName columns become subelements of the
XML element named name.

The resulting XML document for this jXTransformer query

example would look something like this:
<?xml version="1.0" encoding="UTF-8" ?>
<result>
<Employees_Info ID='456321'>
<name>
<first>Jane</first>
<last>Smith</last>
</name>
<title>Director</title>
<hiredate>2000-01-01</hiredate>
<salary>120000</salary>
</Employees_Info>

jXTransformer User’s Guide

 Transforming Relational Data into XML 21

<Employees_Info ID='456322'>
<name>
<first>Roger</first>
<last>Jones</last>
</name>
<title>Sales Representative</title>
<hiredate>2000-02-01</hiredate>
<salary>80000</salary>
</Employees_Info>
</result>

For more information about the jXTransformer grammar for

writing jXTransformer queries, see “Syntax of jXTransformer
Queries” on page 107.

jXTransformer Builder
The jXTransformer Builder is a graphical user interface tool that
helps you create and modify jXTransformer queries quickly
without having to know the syntax of the jXTransformer
grammar. You can also use the jXTransformer Builder to check
the syntax of your jXTransformer query before you use it in your
JDBC applications. You can save the jXTransformer query as a
jXTransformer Builder project file for future fine-tuning or reuse.

For more information about using the jXTransformer Builder to

create jXTransformer queries, see Chapter 3 “Creating
jXTransformer Queries Using the jXTransformer Builder” on
page 47.

For a tutorial on how to create jXTransformer queries, see

Chapter 7 “Tutorial: Using jXTransformer Queries” on page 167.

jXTransformer User’s Guide

22 Chapter 1 jXTransformer Overview

Using jXTransformer Queries in JDBC

Applications
Figure 1-1 shows the components involved when a jXTransformer
query is used in a JDBC application.

Figure 1-1. Using a jXTransformer Query in a JDBC Application

JDBC Application with

jXTransformer Query

1 2
5
jXTransformer
API
5
3 4
DataDirect XML
JDBC Driver Document

3 4

RDBMS

1 The JDBC application establishes a JDBC connection with the

database.
2 The JDBC application sends the jXTransformer query to the
jXTransformer API for processing.
3 The jXTransformer API processes the jXTransformer query and
sends one or multiple SQL99 statements through the
DataDirect JDBC driver to the database to retrieve the
result set.

jXTransformer User’s Guide

 Updating Your Database With Data From XML 23

4 The DataDirect JDBC driver returns the requested result set

to the jXTransformer API.
5 The jXTransformer API formats the data in the XML structure
specified by the jXTransformer query and returns it to the
application (for example, in a DOM or JDOM representation)
or writes it to a standalone XML document file.

You can use the jXTransformer Builder to create, modify, and test
jXTransformer queries. When you are satisfied with your query,
you can cut and paste the jXTransformer query from the
jXTransformer Query window of the Builder or from a text file
into a JDBC application. For more information about coding a
jXTransformer query within a JDBC application, see “Coding
jXTransformer Queries and Write Statements in JDBC
Applications” on page 158.

Updating Your Database With Data From XML

To write data stored in XML documents to relational databases,
you create jXTransformer write statements (Insert, Update, and
Delete statements). jXTransformer write statements allow you to
perform the following tasks:
■ jXTransformer Insert statements insert data from an XML
document into a relational database. New rows are created
with the new data.
■ jXTransformer Update statements update data in a relational
database with data from an XML document.
■ jXTransformer Delete statements delete data in a relational
database. The rows that are deleted are specified by a Where
clause in the jXTransformer Delete statement.

jXTransformer User’s Guide

24 Chapter 1 jXTransformer Overview

For example, suppose your company’s Human Resources (HR)

department uses a Web interface to enter and make changes to
employee information. When an HR representative adds a new
employee or changes an employee’s existing information using
the Web interface, the data is written to an XML document.
Because employee data is stored in an Oracle database for payroll
purposes, jXTransformer write statements are used in a JDBC
application that runs automatically at the end of each day to
change the employee data in the Oracle database.

jXTransformer Write Statement

Example
The following example inserts new rows into the following
database tables:
■ Employees table: EmpID, FirstName, LastName, Title,
StartDate, HourlyRate, and Resume columns
■ EmpBenefits table: BenefitId, EmpId, Amount, and StartDate
columns
■ Assignments table: ProjId, EmpId, and Task columns

The values for the columns are retrieved from the following XML
document named emp.xml:
<?xml version="1.0" encoding="UTF-8"?>
<insert>
<employee ID="21" FirstName="Anne" LastName="Dodsworth"
Title="Miss" StartDate="2001-10-24" HourlyRate="115">
<resume><![CDATA[
<a href=’http://www.xesdemo/resume/21.htm’>
A. Dodsworth</a>]]></resume>
<benefits>
<benefit ID="1" Amount="1"
<benefit ID="2" Amount="175" StartDate="2001-11-01"/>
</benefits>
<projects>

jXTransformer User’s Guide

 Updating Your Database With Data From XML 25

<project ID="8">
<task>Analysis</task>
<task>Development</task>
</project>
<project ID="9">
<task>Analysis</task>
</project>
</projects>
</employee>
</insert>

Insert statement:
insert xml_document(’emp.xml’, 1)
into Employees (EmpId, FirstName, LastName, Title,
StartDate, HourlyRate, Resume)
xml_row_pattern(’/insert/employee’)
values(xml_xpath(’@ID’, 0, ’Integer’),
xml_xpath(’@First’),
xml_xpath(’@LastName’),
xml_xpath(’@Title’),
xml_xpath(’@StartDate’, ’Timestamp’),
xml_xpath(’@HourlyRate’, ’Integer’),
xml_xpath(’resume[1]/text()’)
)
into EmpBenefits (BenefitId, EmpId, Amount, StartDate)
xml_row_pattern(’/insert/employee/benefits/benefit’)
values(xml_xpath(’@ID’, ’Integer’),
xml_xpath(’../../@ID’, ’Integer’),
xml_xpath(’@Amount’, ’Integer’),
xml_xpath(’@StartDate’, ’Timestamp’)
)
into Assignments (ProjId, EmpId, Task)

xml_row_pattern(’/insert/employee/projects/project/task’)
values(xml_xpath(’../@ID’, ’Integer’),
xml_xpath(’../../../@ID’, ’Integer’),
xml_xpath(’text()’)
)

jXTransformer User’s Guide

26 Chapter 1 jXTransformer Overview

Results:

One new row inserted into the Employees table:

EmpId LastName FirstName Title StartDate EndDate HourlyRate Resume
21 Dodsworth Anne Miss 2001-10-24 115 <a href=
’http://www.xesdemo/
resume21.htm>
A.Dodsworth</a>

Two new rows inserted into the EmpBenefits table:

EmpId BenefitId StartDate EndDate Amount
21 1 2001-10-24 1
21 2 2001-22-01 175

Three new rows inserted into the Assignments table:

EmpId ProjId Task StartDate EndDate TimeUsed EstimatedDuration
21 8 Analysis
21 8 Development
21 9 Analysis

For more information about the jXTransformer grammar for

writing jXTransformer write statements, see Chapter 5 “Syntax of
jXTransformer Write Statements” on page 129.

jXTransformer User’s Guide

 Updating Your Database With Data From XML 27

Using jXTransformer Write Statements

in JDBC Applications
Figure 1-2 shows the components involved when jXTransformer
write statements are used in a JDBC application.

Figure 1-2. Using a jXTransformer Write Statement in a JDBC

Application

JDBC Application with

jXTransformer Write
Statements

1 2 5

jXTransformer
API
3
4 5
DataDirect XML
JDBC Driver Document

4 5

RDBMS

1 The JDBC application establishes a JDBC connection with the

database.

2 The JDBC application sends the jXTransformer write

statement (Insert, Update, or Delete) to the jXTransformer
API for processing.
3 The jXTransformer API retrieves the data that is to be written
to the database from the XML document.

jXTransformer User’s Guide

28 Chapter 1 jXTransformer Overview

4 The jXTransformer API sends one or multiple SQL99

statements through the DataDirect JDBC driver to the
database and the database tables are updated.
5 The DataDirect JDBC driver returns the result of executing the
jXTransformer write statements to the jXTransformer API, and
the jXTransformer API returns update row count values to the
application.

For more information about coding a jXTransformer write

statement within a JDBC application, see “Coding jXTransformer
Queries and Write Statements in JDBC Applications” on
page 158.

jXTransformer User’s Guide

 29

2 Understanding jXTransformer

This chapter describes some key features of jXTransformer and

provides examples to help you decide how to use them.

Using jXTransformer Queries

This section provides information to help you use jXTransformer
queries to transform relational data into XML.

Creating Hierarchical XML Documents

jXTransformer allows you to create hierarchical XML documents
and define parent and child relationships for data from one or
multiple database tables using the jXTransformer query
grammar. Also, you can use nested jXTransformer queries to link
data from multiple database tables and hierarchically structure
that data.

Look at a simple jXTransformer query that retrieves data from

one database table and creates a hierarchical XML document
with one parent XML element named Employees_info, and with
one child element named name that is parent to two child
elements named first and last.
select
xml_element(’Employees_Info’,
xml_attribute(’Department’, e.Dept),
xml_element(’name’,
xml_element(’first’, e.FirstName),
xml_element(’last’, e.LastName) ) )
from Employees e WHERE e.Dept = ’QA’

jXTransformer User’s Guide

30 Chapter 2 Understanding jXTransformer

XML result:
<Employees_Info Department=’QA’>
<name>
<first>Paul</first>
<last>Steward</last>
</name>
</Employees_Info>
<Employees_Info Department=’QA’>
<name>
<first>John</first>
<last>Jenkins</last>
</name>
</Employees_Info>

Now, look at another query that uses nested jXTransformer

queries. In this example, the nested query uses the e.EmpId
column to link the rows selected in the parent query with the
rows selected in the nested, or child, query. Using
xml_attribute_key in the parent query creates an XML attribute
and specifies that the e.EmpId column in the database uniquely
identifies the rows retrieved from the first query. Also, it specifies
that the attribute value uniquely defines the parent element
named employee.
select
xml_element(’employee’,
xml_attribute_key(’ID’, e.EmpId),
xml_attribute(’name’,
{fn concat({fn concat(e.FirstName, ’ ’)},e.LastName)}),
(select
xml_element(’project’,
xml_attribute(’name’,p.Name),
xml_attribute(’task’,a.Task))
from Projects p, Assignments a
where p.ProjId=a.ProjId and a.EmpId=e.EmpId))
from Employees e where e.EmpId < 3

jXTransformer User’s Guide

 Using jXTransformer Queries 31

XML result:
<employee ID=’1’ name=’Marc Marshall’
<project name=’Medusa’ task=’Analysis’ />
<project name=’Phoenix’ task=’Analysis’ />
</employee>
<employee ID=’2’ name=’Brian Ayers’
<project name=’Medusa’ task=’Documentation’ />
<project name=’Phoenix’ task=’Documentation’ />
</employee>

NOTE: When you use nested queries, jXTransformer requires that

you use an explicit key, specified through one or a combination
of xml_attribute_key, xml_element_key, and xml_hide_key;
otherwise, jXTransformer creates an implicit key by making all
the columns specified in the top-level jXTransformer query part
of the key, in which case the query results could be incorrect.

For more information about choosing an XML document

structure, see “Choosing an XML Document Structure” on
page 39.

Using Keys
You can optimize processing of a jXTransformer query by
specifying key columns using the "key" keyword. If you do not
specify any key columns, jXTransformer automatically assumes
that all of the selected columns concatenated together compose
the key. Notice that the key columns are used to link parent rows
to child rows when you are using jXTransformer nested queries.
In jXTransformer queries that do not contain nested queries,
there is no need to specify key columns.

The following jXTransformer query constructors support the

"key" keyword:
■ xml_element_key
■ xml_attribute_key
■ xml_hide_key

jXTransformer User’s Guide

32 Chapter 2 Understanding jXTransformer

Look at a jXTransformer query that uses the jXTransformer

constructor xml_hide_key. In this example, xml_hide_key is used
to relate parent rows to child rows.
select
xml_element(’employee’,
xml_hide_key(’ID’, e.EmpId),
xml_attribute(’name’,
{fn concat({fn concat(e.FirstName, ’ ’)},e.LastName)}),
(select
xml_element(’project’,
xml_attribute(’name’,p.Name),
xml_attribute(’task’,a.Task))
from Projects p, Assignments a
where p.ProjId=a.ProjId and a.EmpId=e.EmpId))
from Employees e where e.EmpId < 3

XML result:
<employee name=’Marc Marshall’
<project name=’Medusa’ task=’Analysis’ />
<project name=’Phoenix’ task=’Analysis’ />
</employee>
<employee name=’Brian Ayers’
<project name=’Medusa’ task=’Documentation’ />
<project name=’Phoenix’ task=’Documentation’ />
</employee>

NOTE: When you use nested queries, jXTransformer requires an

explicit key, specified through one or a combination of
xml_attribute_key, xml_element_key, and xml_hide_key;
otherwise, jXTransformer creates an implicit key by making all
the columns specified in the top-level jXTransformer query part
of the key, in which case the query results could be incorrect.

jXTransformer User’s Guide

 Using jXTransformer Queries 33

Hiding Information
The jXTransformer query xml_hide[_key] constructor allows you
to select and "hide" database columns you do not want to
display in the resulting XML document. For example, suppose
you have a database table that contains the following employee
information:

SSN (primary key)

LastName
FirstName
JobTitle
Department
Salary
HireDate
ParentSSN

From this database table, you want to retrieve the names and
salaries of the employees in the "QA" department as well as list
dependents for those employees. In this case, to optimize
processing, you want to write a jXTransformer query that selects
the SSN column (a primary key), but you do not want to display
the SSN information in the XML document, so you use the
xml_hide_key construct to select the SSN data. The
jXTransformer query could look like:
select
xml_element(’QAemployees’,
xml_hide_key(e.SSN),
xml_element(’Salaries’,
xml_element(’first’, e.FirstName),
xml_element(’last’, e.LastName),
xml_element(’salary’, e.Salary) )
(select
xml_element(’children’,
xml_attribute(’first-name’, c.first),
xml_attribute(’last-name’, c.last) )
from Employees C where c.ParentSSN=e.SSN) )
from Employees e where e.Department=’QA’

jXTransformer User’s Guide

34 Chapter 2 Understanding jXTransformer

This query retrieves information about employees in the QA

department and lists the names of their dependents. In this
query, using xml_hide_key optimizes the processing of the query
by linking information about the parents with information about
their children through a common denominator, the SSN
information.

Creating ID/IDREFS Links

The jXTransformer query grammar allows you to create IDREFS as
values for XML attributes. IDREFS are references to unique
attribute ID values for XML elements in the same XML document.

You can use the jXTransformer query constructor xml_attribute to

create IDREFS using the following syntax:

xml_attribute (’xml_attribute_name’, sql99_select)

When you specify a SQL99 query, a space-separated

concatenation of the complete result set is created; these values
typically are IDREFS for an ID attribute of another XML element
in the same XML document.

Using the xml_attribute query constructor, in combination with

multiple top-level queries within a jXTransformer query, you can
create ID/IDREFS links in the resulting XML document. To specify
multiple top-level queries, separate the queries with a
semicolon (;). The result is a single XML document that contains
the concatenation of the results of the different top-level
queries.

jXTransformer User’s Guide

 Using jXTransformer Queries 35

Let us take a look at an example that creates ID/IDREFS links.

select
xml_element(’employees’,
xml_attribute_key(’emp-id’,
{fn concat(’e-’,{fn convert(e1.EmpId,VARCHAR)})}),
xml_attribute(’emp-name’,e1.LastName),
First query
xml_attribute(’emp-benefits’,
select
{fn concat(’b-’,
Creates IDREFS {fn convert(eb1.BenefitId,VARCHAR)})}
from EmpBenefits eb1 where eb1.EmpId=e1.EmpId))
from Employees e1 where exists
(select * from EmpBenefits eb2 where e1.EmpId=eb2.EmpId)
Semicolon separating ;
queries select
xml_element(’benefits’,
xml_attribute_key(’benefit-id’,
{fn concat(’b-’,
{fn convert(b2.BenefitId,VARCHAR)})}),
xml_attribute(’benefit-description’,b2.Description),
xml_attribute(’benefit-employees’,
Second query select
{fn concat(’e-’,
{fn convert(eb3.EmpId,VARCHAR)})}
Creates IDREFS from EmpBenefits eb3
where eb3.BenefitId=b2.BenefitId))
from Benefits b2
where exists
(select * from EmpBenefits eb4
where b2.BenefitId=eb4.BenefitId)

jXTransformer User’s Guide

36 Chapter 2 Understanding jXTransformer

XML result:
<employees emp-id="e-1" emp-name="Marshall"
emp-benefits="b-1 b-3" />
<employees emp-id="e-12" emp-name="Steward"
emp-benefits="b-3" />
<employees emp-id="e-2" emp-name="Allen"
emp-benefits="b-1 b-4" />
<benefits benefit-id="b-1" benefit-description="Bonus"
benefit-employees="e-1 e-2" />
<benefits benefit-id="b-3" benefit-description="Car"
benefit-employees="e-1 e-12" />
<benefits benefit-id="b-4" benefit-description="Commission"
benefit-employees="e-2" />

Creating XML Document Fragments

The jXTransformer query grammar allows you to create complete
XML documents and XML document fragments. A complete XML
document contains an XML root element; in addition, it can
contain processing instructions, a comment, and a reference to a
private or public external DTD.

Typically, you create XML document fragments to insert into an

existing DOM or JDOM document. For example, suppose your
company wants to produce an XML document that contains a
sales report. This sales report contains a message to all sales
representatives as well as sales data that is retrieved from a
relational database. In this scenario, you first create a DOM
document that contains the message. Then, you use
jXTransformer to retrieve the sales data from the database and to
place the XML results into the existing DOM document.

jXTransformer User’s Guide

 Using jXTransformer Queries 37

The JDBC application code required for this scenario might look
something like:
import java.io.OutputStreamWriter;
import java.sql.*;
import org.w3c.dom.*;
import javax.xml.parsers.*;

import com.ddtek.jxtr.*;
{
//Load properties from the resource
loadProperties();

//Create JDBC connection

jdbcConnect();

//Build jXTransformer query

StringBuffer jxtrQ = new StringBuffer();
jxtrQ.append ( "select ");
jxtrQ.append ( " xml_element(’Order-by-SalesID’, ");
jxtrQ.append ( " xml_attribute(’Salesperson’, o.SalesID), ");
jxtrQ.append ( " xml_attribute(’CustomerID’, o.CustomerID), ");
jxtrQ.append ( " xml_element(’Order Date’, o.OrderDate), ");
jxtrQ.append ( " xml_element(’Ship Date’, o.ShipDate), ");
jxtrQ.append ( " xml_element(’Order Amount’, o.OrderAmt) ) ");
jxtrQ.append ( "from Order o order by o.SalesID " );

//Construct new JXTRQuery object

JXTRQuery jxtrQuery = JXTRQuery (conn, new String ( jxtrQ ) )

// Create DOM Document through JAXP

DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance ();
DocumentBuilder db = dbf.newDocumentBuilder ();
Document doc = db.newDocument ();

// Create root node and place it in DOM document

domRoot = doc.createElementNS ( null, "sales-root" );
doc.appendChild ( domRoot );

jXTransformer User’s Guide

38 Chapter 2 Understanding jXTransformer

// Create a child node for the root node and append it

Node domS1 = doc.createElementNS ( null, "sales-query-result" );
domRoot.appendChild ( domS1 );

// Create text content for the subelement

domS1.appendChild ( doc.createTextNode ( "Text message. . ." ) );

// Execute and place the result into the previously created DOM node
jxtrQuery.executeDOM ( domS1 );

// Close JDBC connection

jdbcDisconnect();

Generating DTDs and Schemas

You can generate a DTD or schema that describes the structure of
the XML result of a jXTransformer query using the jXTransformer
API or the jXTransformer Builder. For example, you may want to
distribute a DTD or schema you have generated describing the
XML results of a jXTransformer query to a business partner.
The JXTRQuery class implements the methods you can use to
generate DTDs or schemas based on the XML result of a
jXTransformer query.
See “Generating DTDs or XML Schemas From a jXTransformer
Query” on page 101 for instructions on how to generate a DTD
or an XML schema using the jXTransformer Builder.

jXTransformer User’s Guide

 Using jXTransformer Queries 39

Choosing an XML Document Structure

jXTransformer queries provide the flexibility to define a complex
hierarchical structure for XML documents. jXTransformer also
allows you to generate XML documents from SQL99 queries, but
restricts the resulting XML structure to an attribute- or
element-centric formula.

Hierarchical XML
For hierarchical XML documents, all data retrieved from the
database is structured as defined by parent and child
relationships, and nested queries, using the jXTransformer query
grammar. The JXTRQuery class implements the methods to
transform a jXTransformer query into an XML structured
document. Refer to “Creating Hierarchical XML Documents” on
page 29 for more information about structured XML.

Attribute- and Element-Centric XML

The following XML documents are generated from executing a
SQL99 query, rather than a jXTransformer query:
■ For attribute-centric XML documents, all data retrieved from
the database is structured inside attributes, one attribute for
each column. One element is created for each row retrieved
and the column values are defined as its attributes. The
attribute names are derived from the database column
names.
■ For element-centric XML documents, all data retrieved from
the database is structured inside elements. One element is
created for each row retrieved and the column values are
defined as its subelements. The element names are derived
from the database column names.

jXTransformer User’s Guide

40 Chapter 2 Understanding jXTransformer

The JXTRResultSetWrapper class implements the methods

required to execute a SQL99 query to generate attribute- and
element-centric XML documents.

In the following example, data is retrieved from the FirstName

and LastName table columns and is placed in an attribute-centric
or element-centric XML document.
select e.FirstName, e.LastName
from Employees e
where e.EmpID < 3

An attribute-centric result looks like this:

<?xml version="1.0" encoding="UTF-8" ?>
<jxtr-result>
<row FirstName=’Marc’ LastName=’Marshall’/>
<row FirstName=’Brian’ LastName=’Ayers’/>
</jxtr-result>

An element-centric result looks like this:

<row>
<firstName>Marc</FirstName>
<LastName>Marshall</LastName>
</row>
<row>
<FirstName>Brian</FirstName>
<LastNameAyers</LastName>
</row>

jXTransformer User’s Guide

 Using jXTransformer Queries 41

Choosing an XML Output Format

The JXTRQuery and JXTRResultSetWrapper classes implement
the methods listed in Table 2-1 for generating XML documents.

Table 2-1. jXTransformer Query XML Output Options

XML Document Output Options Methods

Write the XML document as a executeWriter
character stream to a Writer object
Return the XML document as a DOM executeDOM
level 2 document object
Create the XML document under an executeDOM
existing DOM level 2 element node
Return the XML document as a executeJDOM
JDOM tree
Create the XML document under an executeJDOM
existing JDOM tree element node
Invoke SAX-2 callbacks as XML executeSAX
document results are being retrieved
from the database

jXTransformer User’s Guide

42 Chapter 2 Understanding jXTransformer

Choosing a jXTransformer Query

Rewrite Algorithm
A jXTransformer query cannot be passed to the underlying
database system; therefore, jXTransformer translates a
jXTransformer query to one or multiple SQL99 Select statements,
or, in the case of Microsoft SQL Server 2000, a For XML Explicit
Select statement. jXTransformer uses one of the following
jXTransformer rewrite algorithms to perform this translation:
■ Nested loop
■ Sorted outer union
■ Outer union
■ For XML explicit

For a complete description of each rewrite algorithm, refer to the

Javadoc shipped with this product.

In most cases, you do not need to know the rewrite algorithm

jXTransformer uses to translate a jXTransformer query; however,
you may find it helpful to know the following information about
the rewrite algorithms:

■ If a jXTransformer query does not contain nested queries, the

nested loop algorithm is used for the translation. When the
nested loop algorithm is used, the order of the data is
determined by the database system. If you want the data to
be sorted according to key columns specified in the
jXTransformer query, use the sorted outer union algorithm.
■ If a jXTransformer query contains Order By clauses, the nested
loop algorithm is used for the translation. To specify a rewrite
algorithm other than the nested loop algorithm when using
Order By clauses, use the following guidelines:

• You must use the nested loop rewrite algorithm when you
specify an Order By clause that sorts data based on a
column expression not selected from the database. For

jXTransformer User’s Guide

 Using jXTransformer Queries 43

example, the following code sorts on e.HireDate but does

not select e.HireDate from the database:
select
xml_element(’Seniority’,
xml_element(’Name’,
xml_attribute(’Dept’, e.Department),
xml_element(’first’, e.FirstName),
xml_element(’last’, e.LastName) ) )
from Employees e order by e.HireDate
• You may use the outer union algorithm when you select
the column expression used by the Order By clause, but
you must use an ordinal to specify the column expression
in the Order By clause. For example:
select
xml_element(’Seniority’,
xml_element(’Name’,
xml_attribute(’Dept’, e.Department),
xml_attribute(’HireDate’, e.HireDate),
xml_element(’first’, e.FirstName),
xml_element(’last’, e.LastName) ) )
from Employees e order by 2
NOTE: Typically, the outer union rewrite algorithm is
more efficient than the nested loop algorithm; however,
it does use more memory to create the resulting XML
document.
■ If your jXTransformer query contains nested queries where
both parent and child queries contain aggregate functions,
jXTransformer uses the nested loop algorithm for translation.
The nested loop algorithm must be used in this case.
■ Do not use the outer union algorithm if your jXTransformer
query contains Distinct clauses.

The JXTRQuery class contains methods that allow you to specify

which rewrite algorithm you want to use for the translation of
your jXTransformer query.

jXTransformer User’s Guide

44 Chapter 2 Understanding jXTransformer

Using jXTransformer Write Statements

This section provides information you need to know to use
jXTransformer write statements to write data from XML
documents into your relational database.

jXTransformer Write Statement

Processing Overview
When the jXTransformer API executes a jXTransformer write
statement (Insert, Update, or Delete statements) the following
events occur:
1 The jXTransformer API validates the jXTransformer write
statement grammar.
2 One or multiple SQL99 Insert, Update, or Delete statements
are parsed from the jXTransformer write statements.
3 For each of the SQL99 Insert, Update, or Delete statements
resulting from the previous action, the following tasks are
performed:
a A JDBC preparedStatement is created.
b The xml_row_pattern XPath expressions in the statements
are evaluated against the input XML document and the
nodes specified by the XPath expressions are returned.
c For each of the nodes returned from the xml_row_pattern
XPath expressions, the following tasks are performed:
• Each xml_xpath expression is evaluated and the
appropriate setXXX method is invoked on the JDBC
prepared statement using the result of the xml_xpath
expression.

jXTransformer User’s Guide

 Using jXTransformer Write Statements 45

• The java.sql.PreparedStatement.addBatch method is

invoked on the JDBC prepared statement.
• The JDBC prepared statement is executed.
For more information about jXTransformer write statement
processing, see Appendix B “jXTransformer Statement
Processing” on page 211.

Choosing an XML Input Format

The JXTRUpdate and JXTRSingleTableUpdate classes implement
the methods listed in Table 2-2 for writing data from an XML
document to a relational database.

Table 2-2. jXTransformer Write XML Document Options

XML Document Input Options Methods

Read the XML document input as a setReader
character stream to a Reader object
Read the XML document input as a setDOM
DOM level 2 document object
Read the XML document input from a setDOM
DOM level 2 element node
Read the XML document input as a setJDOM
JDOM tree
Read the XML document input from a setJDOM
JDOM tree element node
Read the XML document input from a setSAX
SAX-2 input source

jXTransformer User’s Guide

46 Chapter 2 Understanding jXTransformer

jXTransformer User’s Guide

 47

3 Creating jXTransformer Queries

Using the jXTransformer Builder

This chapter explains how to create jXTransformer queries using

the jXTransformer Builder (the "Builder"). For more information
about creating jXTransformer queries using the jXTransformer
query grammar, see Chapter 4 “Syntax of jXTransformer
Queries” on page 107.

NOTE: The Builder cannot be used to create or execute

jXTransformer write statements.

HTML-based online help for the jXTransformer Builder is placed

on your system during the installation of your DataDirect
product. To access help for the jXTransformer Builder, you must
have Internet Explorer 5.x or higher, or Netscape 4.x or higher
installed. Open the jXTransformer Builder help by selecting
Help / Contents.

NOTE: Depending on your configuration, you may have to

configure the Web browser as described in “Changing the
General Appearance of the GUI” on page 57 before you can use
the jXTransformer help or the Web links in the Help menu.

For installation requirements and installation instructions for

jXTransformer and the Builder, refer to the Installation Guide in
your DataDirect package.

jXTransformer User’s Guide

48 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

Working with the jXTransformer Builder

Using the Builder, you can create and store a jXTransformer query
in a jXTransformer Builder project file (.jxb). The Builder allows
you to create a jXTransformer query, execute the query, and view
the resulting XML document using the following types of views:
■ Tree view uses nodes in a project tree to represent
jXTransformer query constructs. To construct a jXTransformer
query, you can add, modify, delete, and move these nodes
using position-sensitive menu commands and drag-and-drop
functionality. Detailed knowledge of the jXTransformer query
grammar is not required to construct a jXTransformer query in
this view. To work in Tree view, select the Tree View tab at the
bottom of the jXTransformer Query window.
■ Text view allows you to construct a jXTransformer query using
jXTransformer query grammar. To work in Text view, select the
Text View tab at the bottom of the jXTransformer Query
window. For more information about the jXTransformer
query grammar, see Chapter 4 “Syntax of jXTransformer
Queries” on page 107.

Using Tree and Text Views

Using the Tree view, you can create and modify jXTransformer
queries without having to know the syntax of the jXTransformer
query grammar. The jXTransformer query constructs are
represented as nodes in a jXTransformer Builder project tree,
similar to a DOM tree, as shown in Figure 3-1. You can structure
the data you retrieve from the database any way you want it in
the resulting XML document by adding, modifying, deleting, and
moving nodes.

jXTransformer User’s Guide

 Working with the jXTransformer Builder 49

Figure 3-1. jXTransformer Query in Tree View

Each node in the jXTransformer Builder project tree indicates the

type of jXTransformer query construct that node represents. For
more information about the types of nodes you can use in a
jXTransformer Builder project tree, see “Using Project Tree
Nodes” on page 50.

When you create a jXTransformer query in Tree view, you can

easily see the jXTransformer query grammar used in the source
of the query by switching to Text view. The same query shown in
Tree view in Figure 3-1 is displayed in Text view in Figure 3-2.

jXTransformer User’s Guide

50 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

Figure 3-2. jXTransformer Query in Text View

Conversely, if you want to work in Text view and create a query

using the jXTransformer query grammar, you can view the
resulting changes in the jXTransformer Builder project tree by
switching to Tree view.

For more information about the jXTransformer query grammar,

see Chapter 4 “Syntax of jXTransformer Queries” on page 107.

NOTE: When you switch between Tree view and Text view, the
Builder checks the syntax of your query and generates a message
if an error is encountered. If an error is encountered, you cannot
switch views until you correct the error.

Using Project Tree Nodes

Table 3-1 lists the jXTransformer node types you can create in a
jXTransformer Builder project in Tree view and provides a
description of each node type. Notice that most of the node types
correspond to jXTransformer query grammar keywords as

jXTransformer User’s Guide

 Working with the jXTransformer Builder 51

described in Chapter 4 “Syntax of jXTransformer Queries” on

page 107.

Table 3-1. jXTransformer Builder Project Tree Nodes

jXTransformer Nodes Description

project node Specifies the parent node for the
jXTransformer query, which can contain
one or multiple sub-queries. This node is
required and is created when you create a
jXTransformer Builder project. It cannot be
modified, moved, or deleted. This node is
used only in the Tree view and does not
correspond to a jXTransformer keyword.
ROOT ELEMENT node Specifies the root element to be used for
the resulting XML document. When you
turn on the document header, a ROOT
ELEMENT node is inserted in the project
tree with the default root element name
jxtr-result. This node corresponds to the
xml_element keyword when the keyword is
used to specify a root element.
For more information about turning on the
document header, see “Creating Complete
XML Documents” on page 55.
COMMENT node Specifies comments in the XML document
header. This node corresponds to the
xml_comment keyword.
PROCESSING Specifies an XML processing instruction.
INSTRUCTION node This node corresponds to the xml_pi
keyword.
EXTERNAL DTD node Specifies an external public or private DTD.
This node corresponds to the
xml_external_dtd keyword.

jXTransformer User’s Guide

52 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

Table 3-1. jXTransformer Builder Project Tree Nodes

jXTransformer Nodes Description

Base SQL Query node Specifies a SQL99 query on which all or part
of the jXTransformer query is based. This
node is required. When specifying table
names, you must use unique table aliases.
This node is used only in Tree view and does
not correspond to a jXTransformer
keyword.
For more information about Base SQL
Query nodes, see “Using Base SQL Query
Nodes” on page 53.
ELEMENT node Specifies an XML element. This node can
have multiple values and mixed content.
This node corresponds to the xml_element
and xml_element_key keywords.
ATTRIBUTE node Specifies an XML attribute associated with
an ELEMENT node or a ROOT ELEMENT
node. This node corresponds to the
xml_attribute and xml_attribute_key
keywords.
HIDE node Specifies a node that allows you to retrieve
information from the database you do not
want to include in the resulting XML
document. This node corresponds to the
xml_hide and xml_hide_key keywords.
CDATA node Specifies an XML CDATA section. This node
corresponds to the xml_cdata keyword.
NAMESPACE node Specifies an XML namespace associated
with an ELEMENT node or a ROOT
ELEMENT node. This node corresponds to
the xml_namespace keyword.
SELECT EXPR node Specifies a value that is a Select expression
for an ELEMENT node.
CONSTANT node Specifies a value that is a constant for an
ELEMENT node.

jXTransformer User’s Guide

 Working with the jXTransformer Builder 53

For instructions on using these nodes to create jXTransformer

queries, see “Creating and Modifying jXTransformer Queries in
Tree View” on page 65.

Working with Project Tree Nodes

You can expand or collapse any node in the database tree by
double-clicking that node or by single-clicking the + (plus sign)
or - (minus sign) for that node. You can also expand or collapse
any node and its children nodes by right-clicking the node and
selecting Expand Branch or Collapse Branch.

Builder menu commands in the Tree view are position-sensitive.

When you create a node, the new node becomes a child of the
selected node. For example, if you have an ELEMENT node
selected when you select Insert / Attribute Node, the ATTRIBUTE
node will be created as a child of that ELEMENT node.

Also, to help you create a valid jXTransformer query that

complies with the jXTransformer query grammar, the Builder
menu commands that are available depend on the selected
node.

Using Base SQL Query Nodes

The Base SQL Query node is a SQL99 query that forms a base for
all or part of your jXTransformer query. It is a required node in
the jXTransformer Builder project tree. It allows you to decide
which data you want to retrieve from the database before you
create a jXTransformer query and facilitates the process of
constructing the query.

jXTransformer User’s Guide

54 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

In Figure 3-3, the Base SQL Query node contains the following
SQL92 query:
select
e.EmpId,
e.FirstName,
e.LastName,
e.StartDate,
e.EndDate,
e.Resume
from Employees e where e.EmpId in (12,14)

Notice that, in Figure 3-3, each Select expression specified in the

Base SQL Query node is referenced in the jXTransformer Builder
project tree by an ELEMENT node, an ATTRIBUTE node, or a
CDATA node.

Figure 3-3. Example: jXTransformer Builder Project Tree

jXTransformer User’s Guide

 Starting the jXTransformer Builder 55

Creating Complete XML Documents

When you turn on the document header by selecting Insert /
Document Header, the jXTransformer query will generate a
complete XML document instead of an XML document
fragment. When you turn on the document header, the ROOT
ELEMENT node is automatically inserted in the project tree with
the default root element name jxtr-result. You can change the
default root element name by editing the ROOT ELEMENT node.

NOTE: When you turn off the document header, the ROOT
ELEMENT node, and any COMMENT, PROCESSING INSTRUCTION,
and EXTERNAL DTD nodes are deleted.

Starting the jXTransformer Builder

How you start the Builder depends on your platform:
■ On Windows: Run the builder.bat file located in your Builder
installation directory.
■ On UNIX: Run the builder.sh shell script located in your
Builder installation directory.

The builder.bat file or builder.sh script must be customized at

installation to reflect your configuration. For instructions on
customizing the builder.bat file and the builder.sh script for the
Builder, refer to the Installation Guide in your DataDirect
package.

jXTransformer User’s Guide

56 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

Customizing the jXTransformer Builder

You can customize the following settings in the jXTransformer
Builder:
■ General appearance of the GUI, including:
• Java Look and Feel theme
• Font size of the text in the Builder menus and dialog
boxes
• Web browser used to display the online help and use the
Web links in the Help menu

NOTE: Depending on your configuration, you may have to

configure the Web browser before you can access the help
for the jXTransformer Builder and use the Web links in the
Help menu.
• Turn on and off debug logging
■ Editor in the Text view of the jXTransformer Query window
and the XML window. For example, you may want
jXTransformer query keywords to appear in a blue color or
bold type.
■ DataDirect JDBC drivers you want to be available for
connecting to the database. This option allows you to use
drivers that are not specified in the classpath.

jXTransformer User’s Guide

 Customizing the jXTransformer Builder 57

Changing the General Appearance of

the GUI
1 Select Tools / Options. The General tab appears.

2 In the Look and Feel group, complete the following

information:
Look and Feel: From the drop-down list, select the Java
theme you want to use. The default is Metal. The screenshots
in this book use the Windows Java theme.
Font Size: From the drop-down list, select the font size you
want the Builder to use for text in menus and dialog boxes.
The default is 12 points. The font size for the text and tree

jXTransformer User’s Guide

58 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

views in the jXTransformer Query window can be specified on

the Editor tab.
3 In the Other group, complete the following information:
Web Browser Command: Type the full path of the Web
browser executable to be used to display the online help and
access the Web links from the Help menu. Append a space
and %1 to the executable. For example:
C:\Program Files\Internet Explorer\iexplore.exe %1
Debug logging: Debug logging is used for troubleshooting
and dumps debug messages to your standard error stream. It
is turned off by default. Check the Debug logging check box
to turn debug logging on.

jXTransformer User’s Guide

 Customizing the jXTransformer Builder 59

Changing the Text Editor

1 Select Tools / Options. Then, select the Editor tab.

2 To change the appearance of the editor in the:

■ Text view of the jXTransformer Query window, in the
Category list, select JXTR Editor. Continue with the next
step.
■ XML window, in the Category list, select XML Window.
The selections that are not available for the XML window
become disabled. Continue with Step 4.

jXTransformer User’s Guide

60 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

3 To change the appearance of the editor in the Text view of

the jXTransformer Query window, complete the following
information:
Font: From the drop-down list, choose the font you want to
use in the text editor.
Size: From the drop-down list, choose the size of the font you
want to use in the text editor. The default is 12 points.
If you want to define a style for an item in the text editor,
which include jXTransformer keywords, SQL keywords, values,
and strings, select that item in the Style group. You can
distinguish any listed item by color, bold type, italic type, or
any combination of these characteristics.
NOTE: You can disable any style without deleting its
definition by selecting the Disable check box in the Style
group.
Select your choices, and click OK.
4 To change the appearance of the editor in the XML window,
complete the following information:
Font: From the drop-down list, choose the font you want to
use in the text editor.
Size: From the drop-down list, choose the size of the font you
want to use in the text editor. The default is 12 points.
Select your choices, and click OK.

jXTransformer User’s Guide

 Customizing the jXTransformer Builder 61

Specifying Named Drivers

1 Select Tools / Options. Then, select the Drivers tab.

2 To configure a new driver, in the Name group, click the New

button. The New Driver dialog box appears.

Type a name for the new driver, and click OK. The fields in
the Driver group on the Drivers tab become active.

jXTransformer User’s Guide

62 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

3 In the Driver group, complete the following information:

Class: Type the driver class name of the DataDirect JDBC
driver, for example,
com.ddtek.datadirect.jdbc.sqlserver.SQLServerDriver for the
Connect JDBC for SQL Server driver or
com.ddtek.sequelink.jdbc.SequeLinkDriver for the SequeLink
JDBC Driver.
Path: Type the path of the jar file containing the driver class as
well as necessary supporting jar files. You may type multiple
paths; each path creates a new entry. For example, if you are
specifying the:
■ Connect JDBC driver, in the Path field, type a separate
entry for each of the util.jar and base.jar files, in addition
to an entry for the jar file containing the driver class.
■ SequeLink JDBC driver, in the Path field, type a separate
entry for each of the sljc.jar, sljcx.jar, and the SSL
encryption jar files, in addition to an entry for the jar file
containing the driver class.
If you do not specify a path for this driver, the driver must be
specified in your classpath.
If you do not know the driver class name of the DataDirect
JDBC driver, type the path of the jar file containing the driver
class in the Path field or click the ... button to navigate to a jar
file and select it. Once you have typed or selected the path to
the jar file, click the Scan button. The Builder will scan the jar
file for the correct driver class name and will complete the
Class field for you.
When you are satisfied with your settings, click OK.

To delete a named driver, select the driver from the Name group,
and click the Delete button. Click OK to confirm the deletion.

jXTransformer User’s Guide

 Creating a New jXTransformer Builder Project 63

Creating a New jXTransformer Builder Project

From the main menu, select File / New Project. An untitled
project node appears in Tree view of the jXTransformer query
window.

When you save the jXTransformer Builder project to a file, the

project node is renamed to the name of the jXTransformer
Builder project file. You cannot modify, move, or delete this
node.

For instructions on creating and modifying jXTransformer

queries in Tree view, see “Creating and Modifying jXTransformer
Queries in Tree View” on page 65.

For more information about creating and modifying

jXTransformer Builder projects in Text view, see “Creating and
Modifying jXTransformer Queries in Text View” on page 83.

When you are ready to save your jXTransformer project, select

File / Save Project As.

jXTransformer User’s Guide

64 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

Opening a jXTransformer Builder Project

From the main menu, select File / Open Project. A dialog box
allows you to browse and select a project to open. Select the
project you want to open, and click OK. The jXTransformer query
appears in the Tree view or the Text view of the Builder,
depending on which view was active when the project was last
saved.

Closing a jXTransformer Builder Project

When you are ready to close a jXTransformer Builder project,
select File / Close Project. You are prompted to confirm whether
you want to save the project before it is closed. Click OK to save
the project. When this project is opened again in the Builder, it
will appear in the view that was active when the project was last
saved.

jXTransformer User’s Guide

 Creating and Modifying jXTransformer Queries in Tree View 65

Creating and Modifying jXTransformer

Queries in Tree View
This section describes how to create and modify jXTransformer
queries in Tree view and provides instructions on performing the
following tasks:
■ “Turning on the Document Header” on page 66
■ “Specifying Comments” on page 66
■ “Specifying Processing Instructions” on page 67
■ “Specifying an External DTD” on page 69
■ “Creating Base SQL Query Nodes” on page 70
■ “Creating XML Elements” on page 71
■ “Creating XML Attributes” on page 73
■ “Specifying Hide Information” on page 76
■ “Creating XML CDATA Sections” on page 77
■ “Specifying XML Namespaces” on page 79
■ “Assigning Select Expression Values to ELEMENT Nodes” on
page 80
■ “Assigning Constant Values to ELEMENT Nodes” on page 80
■ “Modifying Nodes” on page 81
■ “Moving Nodes” on page 82
■ “Deleting Nodes” on page 82

NOTE: Builder menu commands are position-sensitive. When

creating jXTransformer Builder project tree nodes, the resulting
hierarchy depends on the node you have selected when you
perform the menu command.

For instructions on creating and modifying jXTransformer

queries in Text view, see “Creating and Modifying jXTransformer
Queries in Text View” on page 83.

jXTransformer User’s Guide

66 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

Turning on the Document Header

To generate a complete XML document from a jXTransformer
query, you must turn on the document header by selecting
Insert / Document Header. If you do not turn on the document
header, an XML document fragment is generated when the query
is executed.

Turning on the document header automatically inserts a ROOT

ELEMENT node in the project tree with a default root element
name of jxtr-result. You can change the default root element
name by editing the ROOT ELEMENT node. For information on
modifying nodes, see “Modifying Nodes” on page 81. Only one
XML root element is allowed in each XML document.

NOTE: When you turn off the document header, the ROOT
ELEMENT node, and any COMMENT, PROCESSING INSTRUCTION,
and EXTERNAL DTD nodes are deleted.

Specifying Comments
You can specify one or multiple comments in the document
header only. Comments are specified in the Tree view of the
Builder by using COMMENT nodes, with the project node as the
parent. To specify multiple comments, create multiple COMMENT
nodes, one for each comment.

NOTE: To create a COMMENT node, you first must turn on the

document header as described in “Turning on the Document
Header” on page 66.

jXTransformer User’s Guide

 Creating and Modifying jXTransformer Queries in Tree View 67

To specify a comment:
1 Select the project node, and select Insert / Comment. The
Comment Node dialog box appears:

2 In the Comment field, type a comment.

3 Click OK. A COMMENT node with the specified comment
appears in the project tree.

Specifying Processing Instructions

You can create one or multiple processing instructions in the
resulting XML document. For example, if the generated XML
document will be viewed in a browser, you may want to specify a
processing instruction so that a specific XSL stylesheet is used
when the XML document is viewed. Processing instructions are
specified in the Tree view of the Builder using PROCESSING
INSTRUCTION nodes, with the project node as the parent. To
specify multiple processing instructions, create multiple
PROCESSING INSTRUCTION nodes, one node for each processing
instruction.

NOTE: To create a PROCESSING INSTRUCTION node, you first

must turn on the document header as described in “Turning on
the Document Header” on page 66.

jXTransformer User’s Guide

68 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

To specify a processing instruction:

1 Select the project node, and select Insert / Processing
Instruction. The Processing Instruction Node dialog box
appears.

2 In the Processing Instruction Target field, type the target of

the processing instruction. For example, if you are specifying a
processing instruction for an XSL stylesheet, you may want to
type xsl-stylesheet.
3 In the Processing Instruction field, type a valid XML processing
instruction. For example, if you are specifying a processing
instruction for an XSL stylesheet named common.xsl, you
would type:
type="text/xsl" href="file://common.xsl"
4 Click OK. A PROCESSING INSTRUCTION node with the
specified processing instruction appears in the project tree.

jXTransformer User’s Guide

 Creating and Modifying jXTransformer Queries in Tree View 69

Specifying an External DTD

You can specify an external private or public DTD in the
document header. External DTDs are specified in the Tree view of
the Builder using EXTERNAL DTD nodes, with the project node as
the parent.

NOTE: To create an EXTERNAL DTD node, you first must turn on

the document header as described in “Turning on the Document
Header” on page 66.

To view a DTD, you can open the DTD in the Open DTD window.
For information on opening DTDs, see “Opening an XML DTD”
on page 97.

To specify an external DTD:

1 Select the project node, and select Insert / External DTD. The
External DTD Node dialog box appears.

2 If specifying a public external DTD, in the Public Identifier

field, type the public identifier of the public external DTD.
Do not specify anything in this field if specifying a private
external DTD.
3 In the URI field, type the Uniform Resource Identifier that
identifies the external DTD.

4 Click OK. An EXTERNAL DTD node appears in the project

tree.

jXTransformer User’s Guide

70 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

Creating Base SQL Query Nodes

A Base SQL Query node contains the SQL99 query on which the
jXTransformer query is based. A Base SQL Query node is required
for each jXTransformer sub-query within a jXTransformer Builder
project. For more information about Base SQL Query nodes, see
“Using Base SQL Query Nodes” on page 53.

To create a Base SQL Query node:

1 Right-click the project node or a ROOT ELEMENT node, and
select Insert / Base SQL Query node. The Base SQL Query Node
dialog box appears.

2 Using a simple Select statement, type a SQL99 query or click

the From File button to navigate to a text file that contains a
SQL99 query.

3 Click OK.
The Builder checks the SQL99 query for syntax. If an error is
detected, a dialog box appears describing the error. If no
errors are detected, a Base SQL Query node appears in the
project tree.
Once a Base SQL Query node is created, you can construct the
jXTransformer query based on the Base SQL Query node,

jXTransformer User’s Guide

 Creating and Modifying jXTransformer Queries in Tree View 71

creating other types of nodes for jXTransformer elements,

attributes, and so on.

Creating XML Elements

You specify XML elements in the Tree view of the Builder using
ELEMENT nodes. Because ELEMENT nodes can have multiple
values and mixed content, values of ELEMENT nodes are shown
as child nodes. You can create an ELEMENT node with any of the
following values:
■ A Select expression. This can be any Select expression
specified in the Base SQL Query node (for example, a
database column like e.LastName).
■ A constant (for example, a character string literal like 8 or
TRUE).
■ Empty (no value). Use this value if you want the node to
contain only XML subelements such as other XML elements
or a nested jXTransformer query.

Select Expression
1 Right-click a Base SQL Query node or an ELEMENT node, and
select Insert / Element Node / as Select Expression. The
Element Node dialog box appears.

jXTransformer User’s Guide

72 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

2 In the Name field, type the name of the XML element.

3 From the Select Expression drop-down list, select an available
Select expression. This list is populated with the Select
expressions specified in the Base SQL Query node.

4 Select the Is Key? checkbox if the Select expression associated

with this node is the key or part of a multi-value key. Keys
uniquely identify each row selected by the base SQL99 query.
5 Click OK. The ELEMENT node appears in the project tree with
a Select expression node as its child.

Constant
1 Right-click a Base SQL Query node or an ELEMENT node, and
select Insert / Element Node / as Constant. The Element Node
dialog box appears.

2 In the Name field, type the name of the XML element.

3 In the Value field, type a constant value. This can be any
character string literal, such as 8 or TRUE.

jXTransformer User’s Guide

 Creating and Modifying jXTransformer Queries in Tree View 73

4 Click OK. The ELEMENT node appears in the project tree with
a CONSTANT node as its child.

Empty
1 Right-click a Base SQL Query node or an ELEMENT node, and
select Insert / Element Node / Empty. The Element Node
dialog box appears.

2 In the Name field, type the name of the XML element.

3 Click OK. The ELEMENT node appears in the project tree.

Creating XML Attributes

You specify XML attributes in the Tree View of the Builder using
ATTRIBUTE nodes. You can create an ATTRIBUTE node with any
of the following values:
■ A Select expression. This can be any Select expression
specified in the Base SQL Query node (for example, a
database column like e.LastName).
■ A constant (for example, a character string literal like 8 or
TRUE).
■ A SQL99 query (typically used to construct IDREF values for
an XML attribute). This query must select only one table
column.

jXTransformer User’s Guide

74 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

Select Expression
1 Right-click an ELEMENT node, and select Insert / Attribute
Node / as Select Expression. The Attribute Node dialog box
appears.

2 In the Name field, type the name of the XML attribute.

3 In the Select Expression drop-down list, select an available
Select expression. This list is populated with the Select
expressions specified in the Base SQL Query node.
4 Select the Is Key? checkbox if the Select expression associated
with this node is the key or part of a multi-value key in the
database. Keys uniquely identify each row selected by the
base SQL99 query.

5 Click OK. The ATTRIBUTE node appears in the project tree.

jXTransformer User’s Guide

 Creating and Modifying jXTransformer Queries in Tree View 75

Constant
1 Right-click an ELEMENT node and select Insert / Attribute
Node / as Constant. The Attribute Node dialog box appears.

2 In the Name field, type the name of the XML attribute.

3 In the Value field, type a constant value. This can be any
character string literal, such as 8 or TRUE.

4 Click OK. The ATTRIBUTE node appears in the project tree.

jXTransformer User’s Guide

76 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

SQL Query
1 Right-click an ELEMENT node and select Insert / Attribute
Node / as SQL Query. The Attribute Node dialog box appears.

2 In the Name field, type the name of the XML attribute.

3 In the Select Expression field, type a SQL99 query or click the
From File button to navigate to a text file that contains a
SQL99 query. This query must select only one table column.
4 Click OK. The ATTRIBUTE node appears in the project tree.

Specifying Hide Information

You can retrieve information from the database that you do not
want to include in the resulting XML document using HIDE
nodes. Hide information typically is used to select database
columns that are a key or part of a multi-value key that you do
not want to display in the resulting XML document.

jXTransformer User’s Guide

 Creating and Modifying jXTransformer Queries in Tree View 77

To specify hide information:

1 Right-click the Base SQL Query node or an ELEMENT node,
and select Insert / Hide Node. The Hide Node dialog box
appears.

2 From the Select Expression drop-down list box, select a Select

expression. This list is populated with the Select expressions
specified in the Base SQL Query node.
3 Select the Is Key? checkbox if the select expression associated
with this node is the key or part of a multi-value key. Keys
uniquely identify each row selected by the base SQL99 query.
4 Click OK. The HIDE node appears in the project tree.

Creating XML CDATA Sections

You can create CDATA sections in the Tree view of the Builder
using CDATA nodes. You can create a CDATA node with any of
the following values:
■ Select expression. This can be any Select expression specified
in the Base SQL Query node (for example, a database column
like e.LastName).
■ Constant (for example, a character string literal like 8 or
TRUE).

jXTransformer User’s Guide

78 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

Select Expression
1 Right-click the Base SQL Query node or an ELEMENT node,
and select Insert / CDATA Node / as Select Expression. The
CDATA Node dialog box appears.

2 From the Select Expression drop-down list box, select a Select

expression. This list is populated with the Select expressions
specified in the Base SQL Query node.
3 Click OK. The CDATA node appears in the project tree.

Constant
1 Right-click the Base SQL Query node or an ELEMENT node,
and select Insert / CDATA Node / as Constant. The CDATA
Node dialog box appears.

jXTransformer User’s Guide

 Creating and Modifying jXTransformer Queries in Tree View 79

2 In the Value field, type a constant value or click the From File
button to navigate to a file containing the constant value.
This can be any character string literal, such as 8 or TRUE.

3 Click OK. The CDATA node appears in the project tree.

Specifying XML Namespaces

An XML namespace allows you to create a namespace definition
for an XML element. You can create XML namespace definitions
in the Tree view of the Builder using NAMESPACE nodes.

To specify a namespace:
1 Right-click an ELEMENT node or a ROOT ELEMENT node, and
select Insert / Namespace Node. The Namespace Node dialog
box appears.

2 (Optional) In the Prefix field, type a prefix for the

namespace. If you do not specify a prefix, the default XML
namespace will be defined.

3 In the Namespace URI field, type a URI to identify the

namespace.
4 Click OK. The NAMESPACE node appears in the project tree.

jXTransformer User’s Guide

80 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

Assigning Select Expression Values to

ELEMENT Nodes
Because XML elements can have multiple values and mixed
content, you can assign a Select expression value to an empty
ELEMENT node.

To assign a Select expression value to an ELEMENT node:

1 Select Insert / Select Expression Node. The Select Expression
Node dialog box appears.

2 From the Select Expression drop-down list, select an available

Select expression. This list is populated with the Select
expressions specified in the Base SQL Query node.
3 Click OK. The SELECT EXPR node appears in the project tree as
a child of the selected ELEMENT node.

Assigning Constant Values to ELEMENT

Nodes
Because XML elements can have multiple values and mixed
content, you can assign a constant value to an empty ELEMENT
node.

jXTransformer User’s Guide

 Creating and Modifying jXTransformer Queries in Tree View 81

To assign a constant value to an ELEMENT node:

1 Select Insert / Constant Node. The Constant Node dialog box
appears.

2 In the Value field, type a constant value. This can be any

character string literal, such as 8 or TRUE.

3 Click OK. The CONSTANT node appears in the project tree as

a child of the selected ELEMENT node.

Modifying Nodes
Right-click the node you want to modify, and select Edit. Change
the information in the dialog box as necessary. When you are
satisfied with your changes, click OK.

NOTES:
■ You cannot modify a project node.
■ Changes to a validated Base SQL Query node may invalidate
nodes in the project tree.
■ For ELEMENT nodes, you can only change the name of the
node because ELEMENT nodes can contain multiple value
nodes.

jXTransformer User’s Guide

82 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

Moving Nodes
Select the node you want to move. Then, drag and drop the node
to the location you want it to appear in the project tree.

NOTES:
■ You cannot move a project node.
■ The Builder restricts moves to valid choices as defined by the
jXTransformer query grammar.

Deleting Nodes
Right-click the node you want to delete and select Delete. If the
selected node has children, a window appears asking you to
confirm the deletion of the node and all its children. To confirm,
click OK.

NOTES:
■ When you delete a parent node with children nodes, the
children nodes are deleted also.
■ You cannot delete a project node.

jXTransformer User’s Guide

 Creating and Modifying jXTransformer Queries in Text View 83

Creating and Modifying jXTransformer

Queries in Text View
To create and modify jXTransformer queries in Text view, you
must be familiar with the jXTransformer grammar. Using valid
jXTransformer grammar and syntax, you can type the
jXTransformer query in the Text view of the jXTransformer Query
window. You can also copy existing jXTransformer queries into
the Text view of the jXTransformer Query and modify them as
needed.

Figure 3-4 shows an example of a jXTransformer query in Text

view.

Figure 3-4. jXTransformer Query in Text View

For more information about the jXTransformer grammar, see

Chapter 4 “Syntax of jXTransformer Queries” on page 107.

jXTransformer User’s Guide

84 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

Checking jXTransformer Query Syntax

When you switch between the Tree and Text views, the Builder
automatically checks the syntax of your jXTransformer query. If
an error is encountered, a message is generated. You can also
check the syntax of a jXTransformer query by selecting Project /
Check Query Syntax.

Connecting to the Database

To browse the database or execute a jXTransformer query, a JDBC
connection to the database using a DataDirect JDBC driver is
required. The JDBC connection can be accomplished using a JDBC
connection URL or JDBC data source.

jXTransformer User’s Guide

 Connecting to the Database 85

To connect to the database:

Select Project / Connect to Database. The Open JDBC Connection

dialog box appears.

The Connection URL option is selected by default. If you want to

connect to the database using:
■ JDBC connection URL, continue with “Connecting Using JDBC
Connection URLs” on page 86
■ JDBC data source, continue with “Connecting Using JDBC
Data Sources” on page 87

jXTransformer User’s Guide

86 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

Connecting Using JDBC Connection

URLs
When you connect to the database, the Open JDBC Connection
dialog box appears with the Connection URL option selected by
default.

To connect using a JDBC connection URL:

1 In the Driver group, type or select the driver you want to use
for the connection from the drop-down list. You can enter
any driver class specified in your classpath or enter any named
driver that you have explicitly configured as described in
“Specifying Named Drivers” on page 61.
2 In the Connection group, complete the following
information:
URL: Select the URL you want to use for the connection from
the drop-down list or type a URL.

jXTransformer User’s Guide

 Connecting to the Database 87

UID: Type a user name for the database.

PWD: Type a password for the database.
3 Click OK. When you are connected, a message confirming the
connection appears in the Output window.

Connecting Using JDBC Data Sources

NOTE: To use JDBC data sources with the Builder, you must install
the JNDI service providers used by your data sources and you
must install the following Java packages and include them in
your classpath:
■ JDBC 2.0 Optional Package
■ Java Naming and Directory Interface Package

To connect to the database using a JDBC data source, select the

data source option on the Open JDBC Connection dialog box.
The fields on the dialog box change to accommodate
information required for a data source.

jXTransformer User’s Guide

88 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

To connect using a JDBC data source:

1 In the JNDI group, complete the following information:
Context Factory: Type the name of the JNDI context factory to
be used, or select the name from the drop-down list.
Provider URL: Type the name of the URL that locates the JNDI
provider to be used, or select a URL from the drop-down list.
2 In the Data Source group, complete the following
information:
Name: Type the name of the data source you want to use for
the connection.
UID: Type a user name for the database.
PWD: Type a password for the database.
3 Click OK. When you are connected, a message confirming the
connection appears in the Output window.

jXTransformer User’s Guide

 Executing a jXTransformer Query 89

Executing a jXTransformer Query

Once you execute a jXTransformer query, you can view the
resulting XML document in Tree view or Text view by selecting
the appropriate tab at the bottom of the XML window.

To execute a jXTransformer query:

1 Select Project / Execute Query. If you are not connected to
the database, you must make a JDBC connection. The Open
JDBC Connection dialog box appears.

The Connection URL option is selected by default. If you

want to connect to the database using:
■ JDBC connection URL, see “Connecting Using JDBC
Connection URLs” on page 86
■ JDBC data source, see “Connecting Using JDBC Data
Sources” on page 87

jXTransformer User’s Guide

90 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

2 Parameter markers are placeholders for values, represented

by question marks (?). If the jXTransformer query contains
parameter markers, the Query Parameters dialog box
appears, prompting you for the parameter marker values.

In the Value field, type the value of the parameter marker or

select the Null checkbox to set the parameter marker to a null
value. Then, click OK.
The Execute Query dialog box appears.

jXTransformer User’s Guide

 Executing a jXTransformer Query 91

3 In the Output group, select one of the following options:

■ To Window causes the XML document to appear in the
Query Results window. You can save the XML document
to a file from this window by selecting File / Save as.
■ To File causes the XML document to be saved directly to a
file instead of displaying it in the Builder. Type the path
and name of the file in the associated field or click the ...
button to browse to a file.
4 In the Options group, complete the following information:
Beautify: This option is turned on by default. The Beautify
option formats the content of the XML document with
standard indents and line breaks. Uncheck the Beautify
checkbox to turn off this option. The content of the XML
document will be formatted without indents and line breaks.
Encoding: Select the type of encoding to use for the XML
document. The default depends on your platform.
5 From the Rewrite Algorithm drop-down list, select a rewrite
algorithm. In most cases, you should use the default.
For more information about choosing query rewrite
algorithms, see “Choosing a jXTransformer Query Rewrite
Algorithm” on page 42.

jXTransformer User’s Guide

92 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

6 Click OK to execute the query. If you selected the:

■ To Window option, the XML results appear in the Query
Results window. Select File / Save as to save the XML
results to an XML file.

■ To File option, the XML results are saved to the specified

XML file.

jXTransformer User’s Guide

 Browsing the Database 93

Browsing the Database

To make sure that you know the correct columns and table
names to retrieve from the database and use in your
jXTransformer query, you can browse the database using a tool
within the Builder named the Database Browser. A JDBC
connection is required to browse the database. The Database
Browser also allows you to customize the JDBC filter settings as
described in “Customizing JDBC Filter Settings” on page 95.

Using the Database Browser

1 To open the Database Browser, select Tools / Database
Browser. The DataDirect Database Browser appears.

This example shows the Database Browser in a

non-connected state. If you were already connected to the
database when you opened the Database Browser, you
would see the database tree in the left pane.

jXTransformer User’s Guide

94 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

2 If you are already connected to the database, continue with

Step 3. Otherwise, make a JDBC connection. Right-click the
Not connected node in the Database Browser, and select
Connect to Database. The Open JDBC Connection dialog box
appears.

The Connection URL option is selected by default. If you want

to connect to the database using:
■ JDBC connection URL, see “Connecting Using JDBC
Connection URLs” on page 86
■ JDBC data source, see “Connecting Using JDBC Data
Sources” on page 87
Then, continue with the next step.

jXTransformer User’s Guide

 Browsing the Database 95

3 Browse the database as needed. You can expand any node in

the database tree by double-clicking that node or by
single-clicking the + (plus sign) for that node. When you
select an entity in the database tree, its properties appear in
the right pane of the DataDirect Database Browser as shown
in the following example:

Customizing JDBC Filter Settings

You can customize JDBC filter settings in the Database Browser
to show specific database tables. For example, you may want to
customize the filter settings to view database tables that begin
with the characters "Emp".

jXTransformer User’s Guide

96 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

To customize the JDBC filter settings:

1 In the Database Browser, select Tools / Options. The Database
Filter dialog box appears.

2 In the Name group, complete the following information:

Show All Catalogs: Select this checkbox if you want to show
all catalogs in the database.
Schema: Using the % character as a wildcard, set a filter to
only show schemas named with the characters you specify.
Table: Using the % character as a wildcard, set a filter to only
show tables named with the characters you specify.
Column: Using the % character as a wildcard, set a filter to
only show columns named with the characters you specify.

jXTransformer User’s Guide

 Opening an XML DTD 97

3 In the Type group, select the type of information you want to

see when you browse the database.
4 When you are satisfied with your JDBC filter settings, click
OK.

Opening an XML DTD

You can open an XML DTD in a separate window in the Builder
for reference. For example, you may want to compare the DTD
definition with the structure of your XML document.

To open a DTD:
1 Select File / Open DTD. The Open DTD dialog box appears.

2 In the Path field, select a path to the DTD you want to open
from the drop-down list, type the path, or click the ... button
to browse and select a DTD.

jXTransformer User’s Guide

98 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

3 Click OK. The DTD View window opens with the path and
name of the DTD displayed in the top-level node.

jXTransformer User’s Guide

 Opening an XML Document 99

Opening an XML Document

You can open an XML document in a separate window in the
Builder for reference. The Builder allows you to view the XML
document in Tree view or Text view.

To open an XML document:

1 Select File / Open XML Document. The Open XML Document
dialog box appears.

2 In the Path field, select a path to the XML document you

want to open from the drop-down list, type the path, or click
the ... button to browse and select an XML document.

jXTransformer User’s Guide

100 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

3 Click OK. The XML document opens in a separate window

with the path and name of the XML document in the title bar.

jXTransformer User’s Guide

 Generating DTDs or XML Schemas From a jXTransformer Query 101

Generating DTDs or XML Schemas From a

jXTransformer Query
This section describes how to generate DTDs and XML schemas
from a jXTransformer query using the Builder.

Generating a DTD
1 With a jXTransformer query open, select Project / Create DTD
from query. The Open JDBC Connection dialog box appears.

The Connection URL option is selected by default. If you

want to connect to the database using:
■ JDBC connection URL, see “Connecting Using JDBC
Connection URLs” on page 86
■ JDBC data source, see “Connecting Using JDBC Data
Sources” on page 87

jXTransformer User’s Guide

102 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

Then, continue with the next step.

2 Use the Create DTD dialog box to navigate to an existing
directory or create a new directory for the DTD, and specify
the filename of the DTD you want to create. Then, click Save.
The DTD is created in the specified directory and appears in
the DTD View dialog box.

jXTransformer User’s Guide

 Generating DTDs or XML Schemas From a jXTransformer Query 103

Generating an XML Schema

To generate XML schemas using the Builder, you must specify
every namespace URI defined in your jXTransformer query. A
separate XML schema will be created for each specified
namespace.

To generate an XML schema:

1 With a jXTransformer query open, select Project / Create XML
Schema from query. The Open JDBC Connection dialog box
appears.

The Connection URL option is selected by default. If you

want to connect to the database using:
■ JDBC connection URL, see “Connecting Using JDBC
Connection URLs” on page 86
■ JDBC data source, see “Connecting Using JDBC Data
Sources” on page 87
Then, continue with the next step.

jXTransformer User’s Guide

104 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

2 The Create XML Schema dialog box appears.

In the Output group, map namespace URIs or XML constructs

that are not qualified by a namespace to XML schema files by
completing the following information:
Namespace URI: Type each namespace URI specified in your
jXTransformer query as a separate entry. To generate an XML
schema for XML constructs that are not qualified by a
namespace, create a blank entry in this field, but make sure
that you complete the Path field for that entry.
Path: Type the corresponding full path and name of the file to
which you want each XML schema saved, or click the ...
button to navigate to a file.
3 In the Options group, complete the following information:
Beautify: This option is turned on by default. The Beautify
option formats the content of the XML schema with standard
indents and line breaks. Uncheck the Beautify checkbox to
turn off this option. The content of the XML schema will be
formatted without indents and line breaks.

jXTransformer User’s Guide

 Generating DTDs or XML Schemas From a jXTransformer Query 105

Encoding: Select the type of encoding to use for the XML

schema. The default depends on your platform.
4 Click OK. A separate XML schema is generated for each
namespace entry and, if specified, any XML constructs that
are not qualified by a namespace.

jXTransformer User’s Guide

106 Chapter 3 Creating jXTransformer Queries Using the jXTransformer Builder

jXTransformer User’s Guide

 107

4 Syntax of jXTransformer
Queries

This chapter describes the grammar and syntax of jXTransformer

queries. The following conventions are used to document the
jXTransformer query syntax:
■ Bold type indicates keywords and tokens that must be
entered as part of the query.
■ Italic type indicates variables.

■ Square brackets [ ] surround optional items.

■ A vertical rule | indicates an OR separator to delineate items.
■ Curly brackets { } surround items that can repeat zero or
more times.

The following jXTransformer syntax shows the high-level

components of a jXTransformer query.
jxtr_query ::= [xml_document (xml_document_info,] select
xml_constructor {, xml_constructor} rest_of_sql99_select
{; query} [)]

The following sections define each of the high-level components

of a jXTransformer query:

High-level Component See...

xml_document “xml_document” on page 108
xml_document_info “xml_document_info” on page 109
xml_constructor “xml_constructor” on page 113
rest_of_sql99_select “rest_of_sql99_select” on page 124
query “Query” on page 125

jXTransformer User’s Guide

108 Chapter 4 Syntax of jXTransformer Queries

xml_document
xml_document indicates that a complete XML document will be
created by the jXTransformer query instead of an XML document
fragment. A complete XML document contains an XML root
element. If you do not specify this constructor in your
jXTransformer query, a document fragment will be created. The
xml_document constructor is followed by xml_document_info,
which is discussed next.

jXTransformer User’s Guide

 xml_document_info 109

xml_document_info
The xml_document_info section of a jXTransformer query allows
you to perform the following tasks:
■ Define an XML root element, which creates a complete XML
document as opposed to an XML document fragment.
Within the XML root element, you can define one or multiple
XML attributes, one or multiple XML namespaces, or one or
more of either.
■ Enter one or multiple comments in the XML document
header. This is an optional component of the
xml_document_info section.
■ Specify one or multiple sets of processing instructions. This is
an optional component of the xml_document_info section.
■ Reference one private or public external DTD. This is an
optional component of the xml_document_info section.
Syntax xml_document_info ::= [xml_comment(’comment’) |
xml_pi(’target’, ’instruction’) |
xml_external_dtd([’public_id’,] ’system_uri’)
{, xml_comment(’comment’) |
, xml_pi(’target’, ’instruction’) |
, xml_external_dtd( [’public_id’,] ’system_uri’) } ]
xml_element (’root_element_name’ [,
xml_attribute (’attribute_name’,’attribute_value’) |
xml_namespace ([’prefix’,] ’uri’)]
{, xml_attribute (’attribute_name’,’attribute_value’) |
, xml_namespace ([’prefix’,] ’uri’) } ] )

where:

xml_comment adds an XML comment to the document header of

the resulting XML document.

jXTransformer User’s Guide

110 Chapter 4 Syntax of jXTransformer Queries

comment is any valid string constant value as defined in the

SQL99 specification, except for the optional
introducer character_set_specification.

xml_pi adds an XML processing instruction to the XML document.

Processing instructions allow you to pass one or multiple
processing instructions to applications so that the application can
use the resulting XML without requiring that extra steps be
performed.
target is any valid processing instruction name. It identifies
the processing instruction to the application. Applications can
only process the targets they recognize. An example of a
target is xml-stylesheet. The target must be within single
quotes.
instruction is any valid XML processing instruction, for
example, ’type="text/xsl"’. The instruction must be within
single quotes.

xml_external_dtd creates a reference to an external private or

public DTD.
public_id, if specified, creates a reference to a public external
DTD. This parameter must contain the public identifier for the
DTD that is being referenced.
system_uri is a System URI that identifies the DTD being
referenced. If this parameter is specified in addition to the
public_id parameter, the DTD being referenced is a public
external DTD; otherwise, the DTD being referenced is a
private external DTD.

xml_element, in this instance, is an XML root element. A root

element is required for xml_document.
xml_root_element_name is any valid XML root element name.
This value must be within single quotes and is the only
required parameter for xml_element as the root element.

jXTransformer User’s Guide

 xml_document_info 111

xml_attribute creates an XML attribute for the XML root

element.
xml_attribute_name is any valid XML attribute name. This
value must be within single quotes.
xml_attribute_value is any constant value for the XML
attribute. This value must be within single quotes.
xml_namespace creates an XML namespace definition for the
enclosing XML element.
prefix is the namespace prefix that will be used to qualify
elements or attributes with the namespace URI as
specified in the uri parameter. This value must be within
single quotes and is optional. If you do not specify a
prefix, the default namespace definition will be created.
uri is the URI that identifies the namespace being
defined. This value must be within single quotes and is
required.
Example The following example creates a complete XML document that
includes document-level jXTransformer constructs such as
processing instructions, comments, and a root element with
optional namespace and attribute declarations.
xml_document(
xml_comment(’Example XML result’),
xml_pi(’xml-stylesheet’, ’type="text/xsl"
href="file://myxsl.xsl"’),
xml_element(’exns:example’,
xml_attribute(’rootatt1’, ’example’),
xml_namespace(’http://www.jxtrdemo/default’),
xml_namespace(’exns’, ’http://www.jxtrdemo/example’),
select
xml_element(’empinfo’,
xml_attribute(’exns:id’, e.EmpId),
xml_attribute(’exns:name’, e.LastName))
from Employees e where e.EmpId < 6 ) )

jXTransformer User’s Guide

112 Chapter 4 Syntax of jXTransformer Queries

XML Result:
<!--Example XML result-->
<?xml-stylesheet type="text/xsl" href="file://myxsl.xsl" ?>
<exns:example
rootatt1=’example’
xmlns:"http://www.jxtrdemo/default"
xmlns:exns="http://www.jxtrdemo/example">
<empinfo exns:id=’1’ exns:name=’Marshall’ />
<empinfo exns:id=’2’ exns:name=’Ayers’ />
<empinfo exns:id=’3’ exns:name=’Simpson’ />
<empinfo exns:id=’4’ exns:name=’O&apos;Donnel’ />
<empinfo exns:id=’5’ exns:name=’Jenkins’ />
</exns:example>

jXTransformer User’s Guide

 xml_constructor 113

xml_constructor
The xml_constructor section of a jXTransformer query allows you
to perform the following tasks:
■ Create XML elements (except for a root element), attributes,
CDATA sections, and namespace definitions.
■ Retrieve data that you do not want included in the resulting
XML document. See “xml_hide” on page 122 for a complete
explanation.
Syntax xml_constructor ::= xml_element | xml_attribute |
xml_cdata | xml_namespace | xml_hide | select_expression

xml_element
The most simple form of xml_element is used to set the value of
an XML element to the value of a database column. For
example:
xml_element (’name’, e.LastName)

More advanced forms of xml_element can be used to:

■ Define XML attributes, XML CDATA, or XML namespaces
within the XML element. For example:
xml_element(’Employees_Info’,
xml_attribute(’ID’, e.EmpID),. . .
■ Define XML subelements within an XML element. For
example:

xml_element(’Employees_Info’,
xml_attribute(’ID’, e.EmpID),
xml_element(’name’,
xml_element(’first’, e.FirstName),
xml_element(’last’, e.LastName) ) )

jXTransformer User’s Guide

114 Chapter 4 Syntax of jXTransformer Queries

■ Nest one or more queries within the XML element.

Syntax xml_element ::= xml_element[_key] (’xml_element_name’,
xml_constructor | constant | (query) | select_expression
{, xml_constructor |, constant |, (query) |
, select_expression})

where:

xml_element creates an XML element.

xml_element_key creates an XML element similar to xml_element,

but, in addition, xml_element_key indicates that the column
selected from the database is the key or part of a multi-value key
that uniquely identifies each row retrieved by the query.
Specifying xml_element_key allows the underlying jXTransformer
query to optimize processing.
xml_element_name is any valid XML element name. This value
must be within single quotes.
xml_constructor is any of the following constructors
described in this section: xml_element, xml_attribute,
xml_cdata, xml_namespace, or xml_hide.
constant is a string constant value as defined in SQL99.
query is any valid jXTransformer query without
xml_document_info. Queries can be nested. Nested queries
must be surrounded by parentheses ( ). When you use nested
queries, jXTransformer requires an explicit key, specified
through one, or a combination of, xml_attribute_key,
xml_element_key, and xml_hide_key; otherwise,
jXTransformer creates an implicit key by making all the
columns specified in the parent jXTransformer query part of
the key, in which case, the query results could be incorrect.
select_expression is a valid SQL99 Select list expression,
except for the optional AS clause, for example, a simple table
column name such as e.lastname. In addition, it can contain
DataDirect-supported JDBC scalar functions. See “Example 2”
on page 116 for an example of using JDBC scalar functions in
a jXTransformer query.

jXTransformer User’s Guide

 xml_constructor 115

Example 1 The following example creates the Employees_Info XML element

with a subelement of name in an XML document. The name
subelement has two subelements named first and last. Only data
for employees whose hourly rate is 125 or higher is returned.
select
xml_element(’Employees_Info’,
xml_element(’name’,
xml_element(’first’, e.FirstName),
xml_element(’last’, e.LastName) ) )
from Employees e where e.HourlyRate >= 125

XML Result:
<Employees_Info>
<name>
<first>Betty</first>
<last>Jenkins</last>
</name>
</Employees_Info>
<Employees_Info>
<name>
<first>Mike</first>
<last>Johnson</last>
</name>
</Employees_Info>
<Employees_Info>
<name>
<first>Paul</first>
<last>Steward</last>
</name>
</Employees_Info>
<Employees_Info>
<name>
<first>Robert</first>
<last>Healy</last>
</name>
<Employees_Info>

jXTransformer User’s Guide

116 Chapter 4 Syntax of jXTransformer Queries

Example 2 The following example demonstrates using a nested query. The

explicit key definition is specified by xml_attribute_key in the
parent query. Notice that JDBC scalar functions are used in this
example.
select
xml_element(’employee’,
xml_attribute_key(’ID’, e.EmpId),
xml_attribute(’name’,
{fn concat({fn concat(e.FirstName, ’ ’)},e.LastName)}),
(select
xml_element(’project’,
xml_attribute(’name’,p.Name),
xml_attribute(’task’,a.Task))
from Projects p, Assignments a
where p.ProjId=a.ProjId and a.EmpId=e.EmpId))
from Employees e where e.EmpId < 3

XML Result:
<employee ID=’1’ name=’Marc Marshall’>
<project name=’Medusa’ task=’Analysis’></project>
<project name=’Medusa’ task=’Documentation’></project>
<project name=’Medusa’ task=’Planning’></project>
<project name=’Medusa’ task=’Testing’></project>
<project name=’Phoenix’ task=’Analysis’></project>
<project name=’Phoenix’ task=’Documentation’></project>
</employee>
<employee ID='2' name='Brian Ayers'>
<project name='Hydra' task='Analysis'></project>
<project name='Hydra' task='Documentation'></project>
<project name='Python' task='Analysis'></project>
<project name='Python' task='Development'></project>
</employee>

jXTransformer User’s Guide

 xml_constructor 117

xml_attribute
Syntax xml_attribute ::= xml_attribute (’xml_attribute_name’,
select_expression | constant | sql99_select) |
xml_attribute_key (’xml_attribute_name’, select_expression)

where:

xml_attribute creates an XML attribute for the enclosing XML

element.

xml_attribute_key creates an XML attribute similar to

xml_attribute, but, in addition, xml_attribute_key indicates that
the column selected from the database is the key or part of a
multi-value key that uniquely identifies each row retrieved by
the query. Specifying xml_attribute_key allows the underlying
jXTransformer query to optimize processing.
xml_attribute_name is any valid XML attribute name. This
value must be within single quotes and is required.
constant is a string constant value as defined in SQL99.
select_expression is a valid SQL99 Select list expression,
except for the optional AS clause, for example, a simple table
column name such as e.lastname. The Select expression can
select only one column from the database. The Select
expression value, as retrieved from the database, provides
the value for the named attribute. In addition,
select_expression can contain DataDirect-supported JDBC
scalar functions. See “Example 2” on page 116 for an
example of using JDBC scalar functions in a jXTransformer
query.
sql99_select is any valid SQL99 query with the exceptions
listed in “Rules and Exceptions for jXTransformer Query
Syntax” on page 127. The SQL99 query can contain only one
Select expression. When you specify a SQL99 query, a
space-separated concatenation of the complete result set is
created. Typically, this is used to construct IDREFs values for
an XML attribute. See “Query” on page 125 for an example

jXTransformer User’s Guide

118 Chapter 4 Syntax of jXTransformer Queries

of using a SQL99 query to provide the value for an XML

attribute.
Example The following example creates in an XML document the
Employees_Info XML element with an XML attribute named ID
and a subelement of name. This subelement has two subelements
named first and last. In this example, xml_attribute_key is used to
indicate that the table column that is selected is a key that
uniquely identifies each row retrieved by the query, thereby,
optimizing performance.
select
xml_element(’Employees_Info’,
xml_attribute_key(’ID’, e.EmpId),
xml_element(’name’,
xml_element(’first’, e.FirstName),
xml_element(’last’, e.LastName) ) )
from Employees e where e.EmpId in (12, 14)

XML Result:
<Employees_Info ID='12'>
<name>
<first>Paul</first>
<last>Steward</last>
</name>
</Employees_Info>
<Employees_Info ID=’14’>
<name>
<first>John</first>
<last>Jenkins</last>
</name>
</Employees_Info>

jXTransformer User’s Guide

 xml_constructor 119

xml_cdata
Syntax xml_cdata ::= xml_cdata (select_expression | constant)

where:

xml_cdata creates an XML CDATA section in the resulting XML

document that contains the value from the specified column or
the constant.
select_expression is a valid SQL99 Select expression, except
for the optional AS clause, for example, a simple table
column name such as e.lastname. In addition,
select_expression can contain DataDirect-supported JDBC
scalar functions. See “Example 2” on page 116 for an
example of using JDBC scalar functions in a jXTransformer
query.
constant is a string constant value as defined in SQL99.
Example The following example creates a CDATA section beneath the
Employees_Info element. The content for the CDATA section is
retrieved from the Resume column in the Employees table. A
CDATA section is used because the Resume column contains
some markup characters that must not be parsed.
select
xml_element(’Employees_Info’,
xml_attribute_key(’ID’, e.EmpId),
xml_element(’name’,
xml_element(’first’, e.FirstName),
xml_element(’last’, e.LastName) ),
xml_element (’HireDate’,
xml_attribute (’start’, e.StartDate),
xml_attribute (’end’, e.EndDate)),
xml_cdata (e.Resume))
from Employees e where e.EmpId in (12, 14)

jXTransformer User’s Guide

120 Chapter 4 Syntax of jXTransformer Queries

XML Result:
<Employees_Info ID='12'>
<name>
<first>Paul</first>
<last>Steward</last>
</name>
<HireDate start=’1997-01-04 00:00:00.0’ />
<![CDATA[ <a href=
’http://www.xesdemo/resume/12.htm’>P.Steward</a>]]>
</Employees_Info>
<Employees_Info ID=’14’>
<name>
<first>John</first>
<last>Jenkins</last>
</name>
<HireDate start=’1990-04-01 00:00:00.0’
end=’1998-01-12 00:00:00.0’ />
<![CDATA[ <a href=
’http://www.xesdemo/resume/14.htm’>J.Jenkins</a>]]>
</Employees_Info>

xml_namespace
Syntax xml_namespace ::= xml_namespace ([’prefix’,] ’uri’)

where:

xml_namespace creates an XML namespace definition for the

enclosing XML element.
prefix is the namespace prefix that will be used to qualify
elements or attributes with the namespace URI as specified in
the uri parameter. This value must be within single quotes
and is optional. If you do not specify a prefix, the default
namespace is defined.
uri is the URI that identifies the namespace being defined.
This value must be within single quotes and is required.

jXTransformer User’s Guide

 xml_constructor 121

Example The following example associates the namespace prefix emp

with the namespace URI http://mycomp.com/employees for the
Employees_Info element and its contents. Only the elements
with the emp prefix use the http://mycomp.com/employees
namespace; the other elements use the default namespace,
which is http://mycomp.com/default.

select
xml_element(’emp:Employees_Info’,
xml_attribute_key(’emp:ID’, e.EmpId),
xml_namespace (’http://mycomp.com/default’),
xml_namespace (’emp’, ’http://mycomp.com/employees’),
xml_element(’emp:name’,
xml_element(’first’, e.FirstName),
xml_element(’last’, e.LastName) ) )
from Employees e where e.EmpId in (12, 14)

XML Result:
<emp:Employees_Info emp:ID='12'
xmlns="http://mycomp.com/default"
xmlns:emp="http://mycomp.com/employees">
<emp:name>
<first>Paul</first>
<last>Steward</last>
</emp:name>
</emp.Employees_Info>
<emp:Employees_Info emp:ID=’14’>
xmlns="http://mycomp.com/default"
xmlns:emp="http://mycomp.com/employees">
<emp:name>
<first>John</first>
<last>Jenkins</last>
</emp:name>
</emp.Employees_Info>

jXTransformer User’s Guide

122 Chapter 4 Syntax of jXTransformer Queries

xml_hide
Syntax xml_hide ::= xml_hide[_key] (select_expression)

where:

xml_hide allows you to specify information to be retrieved from

the database that you do not want to include in the resulting
XML document.

xml_hide_key provides the same functionality as xml_hide, but in

addition, xml_hide_key indicates that the column selected from
the database is the key or part of a multi-value key that uniquely
identifies each row retrieved by the query. Specifying
xml_hide_key allows the underlying jXTransformer query to
optimize processing.
select_expression is a valid SQL99 Select list expression,
except for the optional AS clause, for example, a simple table
column name such as e.lastname.
Example The following example creates the Employees_Info XML element
and a subelement of name. This subelement has two subelements
named first and last. In this example, xml_hide_key is used to
retrieve the data in the e.EmpID column that uniquely identifies
each of the rows selected by the query, but is not included in the
XML results.
select
xml_element(’Employees_Info’,
xml_hide_key(e.EmpId),
xml_element(’name’,
xml_element(’first’, e.FirstName),
xml_element(’last’, e.LastName) ) )
from Employees e where e.EmpId=12

jXTransformer User’s Guide

 xml_constructor 123

XML Result:
<Employees_Info>
<name>
<first>Paul</first>
<last>Steward</last>
</name>
</Employees_Info>

select_expression
You can define a jXTransformer query that is similar to a SQL99
query. For example:
select t.a, t.b, t.c from tab t

This type of jXTransformer query lists in the XML document the

values of each database column selected. For example:

row1-value-of-a row1-value-of-b row1-value-of-c

row2-value-of-a row2-value-of-b row2-value-of-c ...

jXTransformer User’s Guide

124 Chapter 4 Syntax of jXTransformer Queries

rest_of_sql99_select
This section of a jXTransformer query allows you to specify the
database table from which the data is retrieved and the
conditions by which the data is retrieved. The From clause defines
the database tables and other optional SQL99 clauses, such as the
Where clause, define the conditions.
Syntax rest_of_sql99_select ::= from_clause [where_clause]
[having_clause] [group_by_clause]

These clauses are defined in the SQL99 specification.

IMPORTANT: jXTransformer requires that you use unique table

name aliases, for example:

from employees e

and

xml_element (’project’, e.EmpId)

jXTransformer User’s Guide

 Query 125

Query
This section of a jXTransformer query allows you to specify
multiple top-level queries. Additional top-level queries cannot
contain xml_document_info (see “xml_document_info” on
page 109). Multiple top-level queries result in the concatenation
of the results of all top-level queries.
Example The following example uses two top-level queries and uses a
SQL99 query to provide the value of an XML attribute. This
example selects employees that have benefits assigned to them.
For each of the selected employees, a list of benefit IDs is
selected. The second top-level query selects benefit information,
provided at least one employee has the benefit assigned to
them. For each benefit selected, a list of employees that have
the benefit assigned to them is selected.

select
xml_element(’employees’,
xml_attribute_key(’emp-id’,
{fn concat(’e-’,{fn convert(e1.EmpId,VARCHAR)})}),
xml_attribute(’emp-name’,e1.LastName),
xml_attribute(’emp-benefits’,
select
{fn concat(’b-’,
{fn convert(eb1.BenefitId,VARCHAR)})}
from EmpBenefits eb1 where eb1.EmpId=e1.EmpId))
from Employees e1 where exists
(select * from EmpBenefits eb2 where e1.EmpId=eb2.EmpId)
;
select
xml_element(’benefits’,
xml_attribute_key(’benefit-id’,
{fn concat(’b-’,
{fn convert(b2.BenefitId,VARCHAR)})}),
xml_attribute(’benefit-description’,b2.Description),
xml_attribute(’benefit-employees’,

jXTransformer User’s Guide

126 Chapter 4 Syntax of jXTransformer Queries

select
{fn concat(’e-’,
{fn convert(eb3.EmpId,VARCHAR)})}
from EmpBenefits eb3
where eb3.BenefitId=b2.BenefitId))
from Benefits b2
where exists
(select * from EmpBenefits eb4
where b2.BenefitId=eb4.BenefitId)

XML Result:
<employees emp-id="e-1" emp-name="Marshall"
emp-benefits="b-1 b-3" />
<employees emp-id="e-12" emp-name="Steward"
emp-benefits="b-3" />
<employees emp-id="e-2" emp-name="Allen"
emp-benefits="b-1 b-4" />
<benefits benefit-id="b-1" benefit-description="Bonus"
benefit-employees="e-1 e-2" />
<benefits benefit-id="b-3" benefit-description="Car"
benefit-employees="e-1 e-12" />
<benefits benefit-id="b-4" benefit-description="Commission"
benefit-employees="e-2" />

jXTransformer User’s Guide

 Rules and Exceptions for jXTransformer Query Syntax 127

Rules and Exceptions for jXTransformer Query

Syntax
The jXTransformer query syntax adheres to the following rules
and exceptions:
■ Does not support the relational set operators (UNION,
INTERSECT).
■ Must contain unique tables aliases for all tables used in the
query.
■ Allows the use of parameters (bind markers) where a
constant value is allowed in the SQL99 sections of the query.
Parameters are specified using a ? token, and you must
provide values for these parameters using the jXTransformer
API.
■ Supports aggregate functions. jXTransformer queries that
contain nested queries in which both parent and child
queries contain aggregate functions cannot be processed
using the sorted outer union algorithm.

■ Supports the DISTINCT query modifier. If a parent query uses

DISTINCT, all child queries must also use DISTINCT; otherwise,
unexpected results may be returned.

Executing jXTransformer Queries

A jXTransformer query is executed using a JXTRQuery object,
which is an object defined in the jXTransformer API. See
Chapter 6 “Using the jXTransformer API” on page 147 for more
information about the jXTransformer API.

jXTransformer User’s Guide

128 Chapter 4 Syntax of jXTransformer Queries

jXTransformer User’s Guide

 129

5 Syntax of jXTransformer Write

Statements

This chapter describes the grammar and syntax of jXTransformer

Write statements. jXTransformer write statements allow you
insert, update, and delete data, as explained in the following
list:
■ jXTransformer Insert statements insert data from an XML
document into a relational database. New rows are created
with the new data.
■ jXTransformer Update statements update data in a relational
database with data from an XML document.
■ jXTransformer Delete statements delete data in a relational
database. The rows that are deleted are specified by a Where
clause in the jXTransformer Delete statement.

The following conventions are used to document the

jXTransformer syntax:
■ Bold type indicates keywords and tokens that must be
entered as part of the write statement.
■ Italic type indicates variables.
■ Square brackets [ ] surround optional items.
■ A vertical rule | indicates an OR separator to delineate items.
■ Curly brackets { } surround items that can repeat zero or
more times.

jXTransformer User’s Guide

130 Chapter 5 Syntax of jXTransformer Write Statements

Insert Statement
jXTransformer Insert statements insert rows into a relational
database based on column values retrieved from an XML
document. When you define a jXTransformer Insert statement,
you specify:
1 The XML document from which to retrieve values to insert
into the database table. For example:
insert xml_document(’emp.xml’)
2 The database table and columns in which to insert the values.
For example:
into Employees (EmpId, FirstName, LastName, Title,
StartDate, HourlyRate, Resume)
3 The nodes of the XML document from which the values will
be retrieved. For example:

xml_row_pattern(’/insert/employee’)
4 The XML element or attribute of the nodes specified in Step 3
from which to retrieve the values to insert in the database
table. For example:
values(xml_xpath(’@ID’, ’Integer’),
xml_xpath(’@FirstName’),
xml_xpath(’@LastName’),
xml_xpath(’@Title’),
xml_xpath(’@StartDate’, ’Timestamp’),
xml_xpath(’@HourlyRate’, ’Integer’),
xml_xpath(’resume[1]/text()’ )
)

jXTransformer User’s Guide

 Insert Statement 131

Syntax
The syntax of a jXTransformer Insert statement is as follows:
Syntax jxtr_insert ::= insert xml_document
((’reference_to_xml’ | ?)[, (ignore_whitespace | ?)] )
[xml_namespace ([’prefix’,] ’uri’)
{,xml_namespace ([’prefix’,] ’uri’)}]
{into table_name [(column_list)]
xml_row_pattern((’row_pattern_expression’ | ? ))
jxtr_query_expression
}

where:

insert xml_document defines the XML document from which

values are retrieved and inserted into the database table. This
construct is required.
reference_to_xml is a reference to the XML document from
which the values for the Insert statement are being retrieved.
The value is the location of the XML document in URL
format, for example, ’file://employee.xml’. This value must be
surrounded by single quotes.
? is a parameter marker. You must set the values for
parameter markers in your JDBC application using the
jXTransformer API.
ignore_whitespace is 0 or 1 and is optional. If set to 1 (the
default), any leading or trailing whitespace that is part of the
value of a node is deleted. If set to 0, the whitespace is not
deleted. Whitespace is newline, carriage return, spaces, and
tabs.

jXTransformer User’s Guide

132 Chapter 5 Syntax of jXTransformer Write Statements

xml_namespace defines a namespace (prefix/URI mapping) for all

XPath expressions used in the Insert statement. This construct is
optional.
prefix is the namespace prefix that is used to qualify
elements or attributes with the namespace URI as specified in
the uri parameter. This value must be within single quotes
and is optional. If you do not specify a prefix, the default
namespace for the XPath expression is defined.
uri is the URI that identifies the namespace for the XPath
expression to use. This value must be within single quotes and
is required when you are defining a namespace for the XPath
expression to use.

into defines the database table and columns in which to insert

values. This construct is required.
table_name is the name and path of a database table. Refer to
the SQL99 specification for more information.
column_list is an optional list of database table column
names, separated by commas. It specifies the name and order
of the columns that will store the values specified in
jxtr_query_expression. If you omit column_list,
jxtr_query_expression must provide values for all columns
defined in the database table and they must be in the same
order that the columns are defined in the table. Refer to the
SQL99 specification for more information.

xml_row_pattern identifies the nodes in the XML input document

from which values are retrieved and inserted into the database
table. This construct is required.
row_pattern_expression is an absolute XPath expression that
returns a node set. The value must be surrounded by single
quotes, for example, ’//employee’. For each node in the
returned node set, one row is inserted into the database
table. Refer to the XPath specification at
http://www.w3.org/TR/xpath for more information.

jXTransformer User’s Guide

 Insert Statement 133

jxtr_query_expression is any valid SQL99 query expression with

the difference that xml_xpath constructs can be used in the
SQL99 query expression where the SQL99 syntax allows
expressions. For example:
values (
xml_xpath(’@ID’, ’Integer’),
xml_xpath(’@FirstName’)
)

This construct is required.

The syntax for an xml_xpath construct is:

xml_xpath((’xpath_expression’ | ?)
[ [, (’java_sql_datatype’ | ?) [, (scale | ?)] ]
[, (mixed_content_index | ?)] ] )

where:

xml_xpath identifies the XML element or attribute in the XML

input document from which the value is retrieved and inserted
into the database table. This construct is optional.
xpath_expression is any valid XPath expression that is
evaluated relative to each of the nodes returned from the
xml_row_pattern construct. The value must be surrounded by
single quotes, for example, ’@ID’. These expressions, when
specified, define the column values being inserted into the
database. Refer to the XPath specification at
http://www.w3.org/TR/xpath for more information.
java_sql_datatype is one of the field string names or int
values from java.sql.Types. When using field string names,
the value must be surrounded by single quotes, for example,
’INTEGER’. If you do not specify a value, CHAR is used.
scale is an integer that specifies the number of digits after
the decimal point; it is only valid for DECIMAL and NUMERIC
java.sql.Types. For all other types, this value is ignored.
mixed_content_index is an integer that specifies the ordinal
position of one value in a set of returned values to use for

jXTransformer User’s Guide

134 Chapter 5 Syntax of jXTransformer Write Statements

the Insert statement. The default is 0, which means to

concatenate all the returned values and use that
concatenated value for the Insert statement. Typically, you
need only specify a value for this argument when the element
referred to in the XPath expression has mixed content and
you want to insert only one value in the database table.
Example The following example inserts new rows into three tables:
■ Employees table: EmpID, FirstName, LastName, Title,
StartDate, HourlyRate, and Resume columns
■ EmpBenefits table: BenefitId, EmpId, Amount, and StartDate
columns
■ Assignments table: ProjId, EmpId, and Task columns

The values for the columns are retrieved from the XML document
emp.xml, shown next:

<?xml version="1.0" encoding="UTF-8"?>

<insert>
<employee ID="21" FirstName="Anne" LastName="Dodsworth"
Title="Miss" StartDate="2001-10-24" HourlyRate="115">
<resume><![CDATA[
<a href=’http://www.xesdemo/resume/21.htm’>
A. Dodsworth</a>]]></resume>
<benefits>
<benefit ID="1" Amount="1"
<benefit ID="2" Amount="175" StartDate="2001-11-01"/>
</benefits>
<projects>
<project ID="8">
<task>Analysis</task>
<task>Development</task>
</project>
<project ID="9">
<task>Analysis</task>
</project>
</projects>
</employee>
</insert>

jXTransformer User’s Guide

 Insert Statement 135

Insert statement:
insert xml_document(’emp.xml’, 1)
into Employees (EmpId, FirstName, LastName, Title,
StartDate, HourlyRate, Resume)
xml_row_pattern(’/insert/employee’)
values(xml_xpath(’@ID’, ’Integer’),
xml_xpath(’@FirstName’),
xml_xpath(’@LastName’),
xml_xpath(’@Title’),
xml_xpath(’@StartDate’, ’Timestamp’),
xml_xpath(’@HourlyRate’, ’Integer’),
xml_xpath(’resume[1]/text()’ )
)
into EmpBenefits (BenefitId, EmpId, Amount, StartDate)
xml_row_pattern(’/insert/employee/benefits/benefit’)
values(xml_xpath(’@ID’, ’Integer’),
xml_xpath(’../../@ID’, ’Integer’),
xml_xpath(’@Amount’, ’Integer’),
xml_xpath(’@StartDate’, ’Timestamp’)
)
into Assignments (ProjId, EmpId, Task)
xml_row_pattern(’/insert/employee/projects/project/task’)
values(xml_xpath(’../@ID’, ’Integer’),
xml_xpath(’../../../@ID’, ’Integer’),
xml_xpath(’text()’)
)

Results:

One new row inserted into the Employees table:

EmpId LastName FirstName Title StartDate EndDate HourlyRate Resume
21 Dodsworth Anne Miss 2001-10-24 115 <a href=
’http://www.xesdemo/
resume21.htm>
A.Dodsworth</a>

jXTransformer User’s Guide

136 Chapter 5 Syntax of jXTransformer Write Statements

Two new rows inserted into the EmpBenefits table:

EmpId BenefitId StartDate EndDate Amount
21 1 2001-10-24 1
21 2 2001-22-01 175

Three new rows inserted into the Assignments table:

EmpId ProjId Task StartDate EndDate TimeUsed EstimatedDuration
21 8 Analysis
21 8 Development
21 9 Analysis

jXTransformer Update statements update column values in a

relational database with new column values retrieved from an
XML document. When you define a JXTransformer Update
statement, you specify:
1 The XML document from which to retrieve new values to use
to update the database table. For example:
update xml_document(’emp.xml’)
2 The database table to update. For example:
Employees
3 The nodes of the XML document from which the new values
are retrieved. For example:
xml_row_pattern(’/update/employee’)
4 The database column to update and the XML element or
attribute of the nodes specified in Step 3 from which to
retrieve the new value for the column. For example:
set HourlyRate = xml_xpath(’@HourlyRate’,’Integer’)

jXTransformer User’s Guide

 Insert Statement 137

5 The database columns to use to identify which rows to

update and the XML elements or attributes of the node from
which to retrieve the value that identifies the rows to
update. For example:
where EmpId = xml_xpath(’@ID’,’Integer’)
NOTE: It is possible to have multiple parts in the Where
clause. For example:
where EmpId = xml_xpath(’@ID’,’Integer’) and
StartDate < xml_xpath(’@StartDate’, ’Timestamp’)

Syntax
The syntax of a jXTransformer Update statement is as follows:
Syntax jxtr_update ::= update xml_document
((’reference_to_xml’ | ?)[, (ignore_whitespace | ?)] )
[xml_namespace ([’prefix’,] ’uri’)
{,xml_namespace ([’prefix’,] ’uri’)}]
{table_name xml_row_pattern(
(’row_pattern_expression’ | ? ))
{set jxtr_set_clause_list}
where jxtr_search_condition
}

where:

update xml_document defines the XML document from which

values are retrieved and updated in the database table. This
construct is required.
reference_to_xml is a reference to the XML document from
which the values for the Update statement are being
retrieved. The value is the location of the XML document in
URL format, for example, ’file://employee.xml’. This value
must be surrounded by single quotes.

jXTransformer User’s Guide

138 Chapter 5 Syntax of jXTransformer Write Statements

? is a parameter marker. You must set the values for

parameter markers in your JDBC application using the
jXTransformer API.
ignore_whitespace is 0 or 1 and is optional. If set to 1 (the
default), any leading or trailing whitespace that is part of the
value of a node is deleted. If set to 0, the whitespace is not
deleted. Whitespace is newline, carriage return, spaces, and
tabs.

xml_namespace defines a namespace (prefix/URI mapping) for all

XPath expressions used in the Update statement. This construct is
optional.
prefix is the namespace prefix that is used to qualify
elements or attributes with the namespace URI as specified in
the uri parameter. This value must be within single quotes
and is optional. If you do not specify a prefix, the default
namespace for the XPath expression is defined.
uri is the URI that identifies the namespace for the XPath
expression to use. This value must be within single quotes and
is required when you are defining a namespace for the XPath
expression to use.

table_name is the name of a database table. This construct is

required. Refer to the SQL99 specification for more information.

xml_row_pattern defines the XML nodes from which values will

be used to update the database table. This construct is required.
row_pattern_expression is an absolute XPath expression that
returns a node set. The value must be surrounded by single
quotes, for example, ’//employee’. Refer to the XPath
specification at http://www.w3.org/TR/xpath for more
information.

set defines the database columns to update and the XML

document nodes from which to retrieve the new value. This
construct is required.
jxtr_set_clause_list is any valid SQL99 Set clause list with
the addition that xml_xpath constructs can be used in the

jXTransformer User’s Guide

 Insert Statement 139

SQL99 Set clause list where the SQL99 syntax allows

expressions. For example:
set HourlyRate = xml_xpath(’@HourlyRate’,’Integer’)
The syntax for an xml_xpath construct is:
xml_xpath((’xpath_expression’ | ?)
[ [, (’java_sql_datatype’ | ?) [, (scale | ?)] ]
[, (mixed_content_index | ?)] ] )
where:
xml_xpath defines the XML element or attribute from which
to retrieve the value to be used to update the database
table. This construct is optional.
xpath_expression is any valid XPath expression. The value
must be surrounded by single quotes, for example, ’@ID’.
These expressions, when specified, define either the new
values to use to update the columns
(jxtr_set_clause_list) or the column values being
updated in the database (jxtr_search_condition). Refer
to the XPath specification at http://www.w3.org/TR/xpath
for more information.
java_sql_datatype is one of the field string names or int
values from java.sql.Types. When using field string names,
the value must be surrounded by single quotes, for
example, ’INTEGER’. If you do not specify a value, CHAR is
used.
scale is an integer that specifies the number of digits
after the decimal point; it is only valid for DECIMAL and
NUMERIC java.sql.Types. For all other types, this value is
ignored.
mixed_content_index is an integer that specifies the
ordinal position of one value in a set of returned values
to use for the Update statement. The default is 0, which
means to concatenate all of the returned values and use
that value for the Update statement. Typically, you need

jXTransformer User’s Guide

140 Chapter 5 Syntax of jXTransformer Write Statements

only specify a value for this argument when the element

referred to in the XPath expression has mixed content and
you want to update only one value in the database table.

where defines the rows in the database table to update. This

construct is required.
jxtr_search_condition is any valid SQL99 search condition
with the addition that xml_xpath constructs can be used in
the SQL99 search condition where the SQL99 syntax allows
expressions. For example:
where EmpId = xml_xpath(’@ID’,’Integer’)
Example The following example updates one row in one database table,
Employees.

The XML document emp.xml, shown next, specifies the column

value that the Update statement uses to identify which row in
the relational database table to update and the new value to use
for the column to be updated. The row with an EmpId of 21 is the
row to be updated, and the HourlyRate column is the column to
be updated to a value of 120.
<?xml version="1.0" encoding="UTF-8"?>
<update>
<employee ID="21" HourlyRate="120">
</employee>
</update>

Update statement:
Update xml_document(’emp.xml’)
Employees xml_row_pattern(’/update/employee’)
set HourlyRate = xml_xpath(’@HourlyRate’,’Integer’)
where EmpId = xml_xpath(’@ID’,’Integer’)

jXTransformer User’s Guide

 Delete Statement 141

Delete Statement
jXTransformer Delete statements delete rows from a relational
database table based on column values retrieved from an XML
document. When you define a jXTransformer Delete statement,
you specify:
1 The XML document from which to retrieve values that
identify the rows in the database table to delete. For
example:
delete xml_document(’emp.xml’)
2 The database table from which to delete rows. For example:
from Employees
3 The nodes of the XML document from which the values that
identify which rows to delete are retrieved. For example:
xml_row_pattern(’/update/employee’)
4 The database columns to use to identify the rows to delete
and the XML element or attribute of the nodes specified in
Step 3 from which to retrieve the value that identifies the
rows to delete. For example:

where EmpId = xml_xpath(’@ID’,’Integer’)

jXTransformer User’s Guide

142 Chapter 5 Syntax of jXTransformer Write Statements

Syntax
The syntax of a jXTransformer Delete statement is as follows:

jxtr_delete ::= delete xml_document

((’reference_to_xml’ | ?)[, (ignore_whitespace | ?)] )
[xml_namespace ([’prefix’,] ’uri’)
{,xml_namespace ([’prefix’,] ’uri’)}]
{from table_name
xml_row_pattern((’row_pattern_expression’ | ? ))
where jxtr_search_condition
}

where:

delete xml_document defines the XML document from which

values are retrieved to identify which rows to delete from the
database table. This construct is required.
reference_to_xml is a reference to the XML document from
which the values for the Delete statement are being
retrieved. The value is the location of the XML document in
URL format, for example, ’file://employee.xml’. This value
must be surrounded by single quotes.
? is a parameter marker. You must set the values for
parameter markers in your JDBC application using the
jXTransformer API.
ignore_whitespace is 0 or 1 and is optional. If set to 1 (the
default), any leading or trailing whitespace that is part of the
value of a node is deleted. If set to 0, the whitespace is not
deleted. Whitespace is newline, carriage return, spaces, and
tabs.

xml_namespace defines a namespace (prefix/URI mapping) for all

XPath expressions used in the Delete statement.
prefix is the namespace prefix that will be used to qualify
elements or attributes with the namespace URI as specified in
the uri parameter. This value must be within single quotes

jXTransformer User’s Guide

 Delete Statement 143

and is optional. If you do not specify a prefix, the default

namespace for the XPath expression is defined.
uri is the URI that identifies the namespace for the XPath
expression to use. This value must be within single quotes
and is required when you are defining a namespace for the
XPath expression to use.

from defines the database table on which the delete operation

will take place. This construct is required.
table_name is a simple database table name or full pathname.
Refer to the SQL99 specification for more information.

xml_row_pattern defines the XML nodes from which values are

used to identify the row to delete in the database table.
row_pattern_expression is an absolute XPath expression that
returns a node set. The value must be surrounded by single
quotes, for example, ’//employee’. Refer to the XPath
specification at http://www.w3.org/TR/xpath for more
information.

where defines the rows in the database table to delete. This

construct is required.
jxtr_search_condition is any valid SQL99 search condition
with the addition that xml_xpath constructs can be used in
the SQL99 search condition where the SQL99 syntax allows
expressions. For example:
where EmpId = xml_xpath(’@ID’,’Integer’)
The syntax for the xml_xpath construct is:
xml_xpath((’xpath_expression’ | ?)
[ [, (’java_sql_datatype’ | ?) [, (scale | ?)] ]
[, (mixed_content_index | ?)] ] )
where:
xml_xpath defines the XML element or attribute from which
to retrieve the value to be used to identify the rows to delete
from the database table. This construct is optional.

jXTransformer User’s Guide

144 Chapter 5 Syntax of jXTransformer Write Statements

xpath_expression is any valid XPath expression. The value

must be surrounded by single quotes, for example, ’@ID’.
These expressions, when specified, define the column
values of the rows being deleted from the database. Refer
to the XPath specification at http://www.w3.org/TR/xpath
for more information.
java_sql_datatype is one of the field string names or int
values from java.sql.Types. When using field string names,
the value must be surrounded by single quotes, for
example, ’INTEGER’. If you do not specify a value, CHAR is
used.
scale is an integer that specifies the number of digits after
the decimal point; it is only valid for DECIMAL and
NUMERIC java.sql.Types. For all other types, this value is
ignored.
mixed_content_index is an integer that specifies the
ordinal position of one value in a set of returned values to
use for the Delete statement. The default is 0, which
means to concatenate all of the returned values and use
that value for the Delete statement. Typically, you need
only specify a value for this argument when the element
referred to in the XPath expression has mixed content and
you want to use only one of the mixed content parts in
the Delete statements Where clause.
Example The following example deletes rows from three different tables—
Assignments, EmpBenefits, and Employees. The rows that are
deleted contain the value 21 in the EmpId column of these tables.
The example uses a parameter marker for the reference to the
XML document that is used in this delete transaction. The value
for this marker must be set in the JDBC application that executes
the jXTransformer Delete statement. Also, this example uses an
xml_namespace constructor to define a prefix and URI mapping
for all XPath expressions used in the Delete statement.

jXTransformer User’s Guide

 Executing jXTransformer Write Statements 145

The XML document delete.xml, shown next, specifies the column

value that the Delete statement uses to identify which rows in
the relational database table to delete.

<?xml version="1.0" encoding="UTF-8"?>

<root xmlns:emp="http://www.jxtrdemo/delete">
<emp:employee ID="21"/>
</root>

Delete statement:

delete xml_document(?)
xml_namespace(’emp’,’http://www.jxtrdemo/delete’)
from Assignments
xml_row_pattern(’/root/emp:employee’)
where EmpId = xml_xpath(’@ID’,’Integer’)
from EmpBenefits
xml_row_pattern(’/root/emp:employee’)
where EmpId = xml_xpath(’@ID’,’Integer’)
from Employees
xml_row_pattern(’/root/emp:employee’)
where EmpId = xml_xpath(’@ID’,’Integer’)

Executing jXTransformer Write Statements

jXTransformer Insert, Update, and Delete statements are
executed using a JXTRUpdate object, which is an object defined
in the jXTransformer API. See Chapter 6 “Using the
jXTransformer API” on page 147 for more information about
using the jXTransformer API.

jXTransformer User’s Guide

146 Chapter 5 Syntax of jXTransformer Write Statements

jXTransformer User’s Guide

 jXTransformer API Classes 147

6 Using the jXTransformer API

In a JDBC programming environment, you use the jXTransformer

API to perform the following tasks:
■ Execute jXTransformer queries and transform the result sets
into XML. This API can return a result set in any of the
supported formats: DOM level 2, JDOM, character stream, or
SAX2.

■ Execute jXTransformer write statements (Insert, Update, or

Delete) to write data to a relational database from an XML
document and return a count of the rows inserted, updated,
or deleted.

This chapter describes the jXTransformer API classes and

methods you can use to execute jXTransformer queries and
jXTransformer write statements. It also provides information
about coding jXTransformer queries and write statements in
JDBC applications.

jXTransformer API Classes

Table 6-1 lists and defines the classes in the jXTransformer API
that can be used to create and execute jXTransformer queries
and jXTransformer write statements.

jXTransformer User’s Guide

148 Chapter 6 Using the jXTransformer API

Table 6-1. jXTransformer API Classes

Class Description
JXTRBase Implements methods that are
shared by the
JXTRResultSetWrapper, JXTRQuery,
JXTRSingleTableUpdate, and
JXTRUpdate classes. An abstract
class.
JXTRDatabaseExtension Implements methods that extend
database-specific processing. Use
this class only when you want to
override the default jXTransformer
behavior. An abstract class.
JXTRException Implements a Java exception
object, which is thrown if an
unexpected occurrence is
encountered during the processing
of a jXTransformer method.

jXTransformer User’s Guide

 jXTransformer API Classes 149

Table 6-1. jXTransformer API Classes (cont.)

Class Description
JXTRQuery Implements the methods required
to:
■ Transform the results from a
jXTransformer query into an
XML document in any of the
supported formats: DOM
level 2, JDOM, character stream,
or SAX2
■ Generate a DTD or schema
based on the jXTransformer
query that describes the XML
structure

■ Add document-level processing

instructions and comments

■ Add a reference to a public or

private external DTD or an
externally stored XML schema
See “JXTRQuery and
JXTRResultSetWrapper Classes” on
page 152 for more information.
JXTRQueryBase Implements methods that are
shared by the JXTRQuery and
JXTRResultSetWrapper classes. An
abstract class.

jXTransformer User’s Guide

150 Chapter 6 Using the jXTransformer API

Table 6-1. jXTransformer API Classes (cont.)

Class Description
JXTRResultSetWrapper Implements the methods required
to execute a SQL99 query and
generate an element-centric or
attribute-centric XML result set.
This class wraps XML elements or
attributes around the row and
column data that is retrieved from
the database. Use this class when
you do not want to define the
hierarchical structure of an XML
document.
See “JXTRQuery and
JXTRResultSetWrapper Classes” on
page 152 for more information.
JXTRSaxInputSource Implements the methods that
extend the SAX2 InputSource
interface and is typically used with
a JXTRSaxReader object.
JXTRSaxReader Implements the methods required
to implement a SAX2 XMLReader
interface and is used with a
JXTRResultSetWrapper or
JXTRQuery object.
JXTRSingleTableUpdate Implements the methods required
to execute a SQL99 Insert, Update,
or Delete statement based on one
or multiple sets of parameter
marker values retrieved from an
input XML document.
See “JXTRUpdate and
JXTRSingleTableUpdate Classes”
on page 154 for more information.

jXTransformer User’s Guide

 jXTransformer API Classes 151

Table 6-1. jXTransformer API Classes (cont.)

Class Description
JXTRSingleTableUpdateException Implements a Java exception
object, which is thrown if an
unexpected occurrence is
encountered during the processing
of a SQL99 Insert, Update, or
Delete statement.
JXTRStatement Implements the methods required
to determine if a jXTransformer
statement is a jXTransformer query
statement or a jXTransformer
Insert, Update, or Delete
statement.
JXTRUpdate Implements the methods required
to:
■ Execute a jXTransformer Insert,
Update, or Delete statement

■ Specify the format of the XML

document from which the data
will be retrieved

■ Specify values for parameter

markers
See “JXTRUpdate and
JXTRSingleTableUpdate Classes”
on page 154 for more information.
JXTRUpdateBase Implements methods that are
shared by the JXTRUpdate and
JXTRSingleTableUpdate classes. An
abstract class.
JXTRUpdateException Implements a Java exception
object, which is thrown if an
unexpected occurrence is
encountered during the processing
of a jXTransformer Insert, Update,
or Delete statement.

jXTransformer User’s Guide

152 Chapter 6 Using the jXTransformer API

JXTRQuery and JXTRResultSetWrapper

Classes
Table 6-2 lists some common tasks that you can perform using the
methods of the JXTRQuery and JXTRResultSetWrapper classes.
These two classes are the most frequently used jXTransformer API
classes when you are working with jXTransformer queries.

Table 6-2. Tasks Performed by the JXTRQuery and

JXTRResultSetWrapper Classes

Task Method
Add document-level comments addDocumentComment
Add document-level processing instructions addDocumentPI
Add root attributes addRootAttribute
Add a namespace definition to a root addRootNamespace
element
Execute a query and return the XML as a executeDOM
DOM level 2 document object
Execute a query and create the XML executeDOM
document under the specified DOM level 2
node
Execute a query and return the XML as a executeJDOM
JDOM document
Execute a query and create the XML executeJDOM
document under the specified JDOM
element
Execute a query and invoke the SAX2 executeSAX
callbacks as registered with the specified
XML reader
Execute a query and write the XML as a executeWriter
character stream to the specified writer,
which uses either UTF-8 encoding or
encoding you specify

jXTransformer User’s Guide

 jXTransformer API Classes 153

Table 6-2. Tasks Performed by the JXTRQuery and

JXTRResultSetWrapper Classes (cont.)

Task Method
Generate a DTD describing the structure of generateDTD
the query result and write the DTD on the
specified Writer object
Generate an XML schema describing the generateXMLSchema
structure of the query result and optionally
write the schema on the specified Writer
object
Set values for parameters setBigDecimal
setBoolean
setByte
setBytes
setInt
setObject
setString
setShort
setLong
setFloat
setDouble
setDate
setTime
setTimestamp
setNull
Set the root tag name for the resulting XML setRootTag
Set a private or public external DTD setExternalDTD
definition

For more details about each jXTransformer class and its

associated methods, refer to the Javadoc shipped with the
product.

jXTransformer User’s Guide

154 Chapter 6 Using the jXTransformer API

JXTRUpdate and
JXTRSingleTableUpdate Classes
Table 6-3 lists some common tasks that you can perform using the
methods of the JXTRUpdate and JXTRSingleTableUpdate classes.
These classes are the most frequently used jXTransformer API
classes when you are working with jXTransformer write
statements.

JXTRUpdate Class

Table 6-3. Tasks Performed by the JXTRUpdate Class

Task Method
Execute a jXTransformer Insert, executeUpdate
Update, or Delete statement and
return a row count
Read the input from an XML setDOM
document in the DOM level 2
format
Read the input from an XML setJDOM
document in the JDOM format
Read the input from an XML setReader
document in a character stream
format
Read the input from an XML setSAX
document in the SAX2 format

jXTransformer User’s Guide

 jXTransformer API Classes 155

Table 6-3. Tasks Performed by the JXTRUpdate Class (cont.)

Task Method
Set values for parameters setBigDecimal
setBoolean
setByte
setBytes
setDate
setDouble
setFloat
setInt
setLong
setNull
setObject
setShort
setString
setTime
setTimestamp
Sets configuration options setBinaryEncoding
setNullReplacementValue
setTimestampEncoding

For more details about each jXTransformer class and its

associated methods, refer to the Javadoc shipped with the
product.

jXTransformer User’s Guide

156 Chapter 6 Using the jXTransformer API

JXTRSingleTableUpdate Class

Table 6-4. Tasks Performed by the JXTRSingleTableUpdate Class

Task Method
Execute the SQL99 Insert, Update, executeUpdate
or Delete statement and return a
row count
Read the input from an XML setXMLDocument
document in one of the supported
formats: URL, DOM Level 2
document or node, JDOM
document or node, character
stream, SAX2
Set the XPath expression that will setXMLRowPattern
be used as the XML row pattern to
identify the data to be extracted
from the XML document
Set the XPath expressions used to setXMLXPath
extract the values from the XML
document
Set the namespace definitions setXMLNamespace
used in the XPath expressions

jXTransformer User’s Guide

 jXTransformer API Classes 157

Table 6-4. Tasks Performed by the JXTRSingleTableUpdate Class

Task Method
Execute the SQL99 Insert, Update, executeUpdate
or Delete statement and return a
row count
Set values for parameters setBigDecimal
setBinaryEncoding
setBoolean
setByte
setBytes
setDate
setDouble
setFloat
setInt
setLong
setNull
setNullReplacementValue
setObject
setShort
setString
setTime
setTimestamp
setTimestampEncoding

For more details about each jXTransformer class and its

associated methods, refer to the Javadoc shipped with the
product.

jXTransformer User’s Guide

158 Chapter 6 Using the jXTransformer API

Coding jXTransformer Queries and Write

Statements in JDBC Applications
NOTE: To compile and run JDBC applications that use
jXTransformer queries and write statements, you must add the
appropriate jar files to your classpath. For information about the
jar files you need to add, refer to the Installation Guide in your
DataDirect package.

Typically, a JDBC application containing a jXTransformer query or

write statement performs the following tasks:
1 Connects to the database using the JDBC API.
2 Prepares the jXTransformer query or write statement in a
String object.
3 Creates a JXTRQuery or JXTRUpdate object, passing in the
JDBC connection and the jXTransformer query or write
statement.
4 Sets options that are available to the jXTransformer query or
write statement.
5 Optionally, sets parameters for the query or write statement.
6 Uses one of the execute methods to execute the query or
write statement. In the case of a jXTransformer query, the
method used to execute the jXTransformer query determines
the format of the resulting XML document or XML document
fragment (DOM, JDOM, SAX2 event stream, or Writer). In the
case of a jXTransformer write statement, the method also
returns a count of rows inserted, updated, or deleted.

The following examples show a jXTransformer query and a

jXTransformer write statement coded in a JDBC application.

jXTransformer User’s Guide

 Coding jXTransformer Queries and Write Statements in JDBC Applications 159

Example A: jXTransformer Query

The following example shows a jXTransformer query in a JDBC
application. For more examples of jXTransformer queries that
demonstrate specific jXTransformer features and functions in a
JDBC application, refer to the README file in the
installdir\jxtr\examples directory (where installdir is your
jXTransformer installation directory).
/*
* --------------------------------------------------------------------------
* Copyright(c) 2002 DataDirect Technologies. All rights reserved.
*
* This product includes Xerces, developed by the Apache Software F
* Foundation (http://www.apache.org). Copyright (C) 1999-2000 The Apache
* Software Foundation. All rights reserved.
*
* This product includes Xalan, developed by the Apache Software
* Foundation (http://www.apache.org). Copyright (C) 1999-2000 The Apache
* Software Foundation. All rights reserved.
*
* This product includes JDOM, developed by the JDOM Project
* (http://www.jdom.org). Copyright (C) 2000 Brett McLaughlin & Jason Hunter.
* All rights reserved.
*
* Description:
*
* Example1:
* Demonstrates
* (a) Basic XML document fragment construction features.
* (b) Write the XML result to a writer (created from System.out)
* The example can be invoked through the Example class or by invoking
* the main in this class.
*
* See the accompanying readme file for more information on the
* provided examples.
*
* --------------------------------------------------------------------------
*/

jXTransformer User’s Guide

160 Chapter 6 Using the jXTransformer API

import java.io.OutputStreamWriter;
import java.sql.*;

import com.ddtek.jxtr.*;

import Example;

public class Example1 extends Example

{

/**
* Executes the 'Example1' example
*/
public void execute() throws Exception
{
// Output example description
System.out.println( "Example1 demonstrates:" );
System.out.println( " (a) Basic XML document fragment construction" );
System.out.println( " (b) Writer output to System.out" );

// Load properties from the resource

loadProperties();

// Create JDBC connection

jdbcConnect();

// Build JXTR query

StringBuffer jxtrQ = new StringBuffer();
jxtrQ.append ( "select " );
jxtrQ.append ( " xml_element ('employee', " );
jxtrQ.append ( " xml_attribute('ID', e.EmpId), " );
jxtrQ.append ( " xml_element('names', " );
jxtrQ.append ( " xml_element('first', e.FirstName), " );
jxtrQ.append ( " xml_element('last', e.LastName)), " );
jxtrQ.append ( " xml_element('hire-dates', " );
jxtrQ.append ( " xml_attribute('start', e.StartDate), " );
jxtrQ.append ( " xml_attribute('end', e.EndDate)), " );
jxtrQ.append ( " xml_cdata(e.Resume)) " );
jxtrQ.append ( "from Employees e where e.EmpId in (12, 14) " );

jXTransformer User’s Guide

 Coding jXTransformer Queries and Write Statements in JDBC Applications 161

// Construct new JXTRQuery object

JXTRQuery jxtrQuery = new JXTRQuery ( conn, new String ( jxtrQ ) );

// Output result header

System.out.println( "------------------------------------" );
System.out.println( "Query result (without implicit root)" );
System.out.println( "------------------------------------" );

// Execute
OutputStreamWriter systemOutWriter = new OutputStreamWriter ( System.out );
boolean generateImplicitRoot=false;
jxtrQuery.executeWriter ( systemOutWriter, generateImplicitRoot,
systemOutWriter.getEncoding (), 2 );

// Output result header

System.out.println( "---------------------------------" );
System.out.println( "Query result (with implicit root)" );
System.out.println( "---------------------------------" );

// Execute
generateImplicitRoot=true;
jxtrQuery.executeWriter ( systemOutWriter, generateImplicitRoot,
systemOutWriter.getEncoding (), 2 );

// Close JDBC connection

jdbcDisconnect();

/**
* Main method.
*/
public static void main ( String[] args ) throws Exception
{
Example thisDemo = new Example1();
thisDemo.execute();
}
}

jXTransformer User’s Guide

162 Chapter 6 Using the jXTransformer API

Example B: jXTransformer Write

Statement
The following example shows a jXTransformer write statement in
a JDBC application. For more examples of jXTransformer write
statements that demonstrate specific jXTransformer features and
functions in a JDBC application, refer to the README file in the
installdir\jxtr\examples directory (where installdir is your
jXTransformer installation directory).
/*
* --------------------------------------------------------------------------
* Copyright(c) 2002 DataDirect Technologies. All rights reserved.
*
* This product includes Xerces, developed by the Apache Software
* Foundation (http://www.apache.org). Copyright (C) 1999-2000 The Apache
* Software Foundation. All rights reserved.
*
* This product includes Xalan, developed by the Apache Software
* Foundation (http://www.apache.org). Copyright (C) 1999-2000 The Apache
* Software Foundation. All rights reserved.
*
* This product includes JDOM, developed by the JDOM Project
* (http://www.jdom.org). Copyright (C) 2000 Brett McLaughlin & Jason Hunter.
* All rights reserved.
*
* Description:
*
* Example9:
* Demonstrates
* (a) Basic update of multiple database tables
* using values from a XML document.
* (b) Use of query parameters to set XPath values and 'normal' values.
* (c) Write the number of updates rows to System.out.
* The example can be invoked through the Example class or by invoking
* the main in this class.
*
* See the accompanying readme file for more information on the
* provided examples.
*

jXTransformer User’s Guide

 Coding jXTransformer Queries and Write Statements in JDBC Applications 163

* --------------------------------------------------------------------------
*/
import java.io.OutputStreamWriter;
import java.sql.*;

import com.ddtek.jxtr.*;

import Example;

public class Example9 extends Example

{

/**
* Executes the 'Example9' example
*/
public void execute() throws Exception
{
// Output example description
System.out.println( "Example9 demonstrates:" );
System.out.println( " (a) Basic update of multiple database tables" );
System.out.println( " using values from a XML document." );
System.out.println( " (b) Use of query parameters to set XPath values
and 'normal' values." );
System.out.println( " (c) Write the number of updated rows to System.out." );

// Load properties from the resource

loadProperties();

// Create JDBC connection

jdbcConnect();

// Turn off autocommit

conn.setAutoCommit ( false );

// Set table names

String[] table = new String[] {"EmpBenefits", "Assignments"};

jXTransformer User’s Guide

164 Chapter 6 Using the jXTransformer API

// Build JXTR query

StringBuffer jxtrU = new StringBuffer();
jxtrU.append ( "update xml_document('Update.xml', 1) " );
jxtrU.append ( " " + table[0] + " " );
jxtrU.append ( " xml_row_pattern('/root/employee/benefits/benefit') " );
jxtrU.append ( " set Amount = Amount + xml_xpath('@AddedAmount',
'Integer'), " );
jxtrU.append ( " StartDate = xml_xpath('@NewStartDate',
'Timestamp') " );
jxtrU.append ( " where BenefitId = xml_xpath('@ID', 'Integer') " );
jxtrU.append ( " and EmpId = xml_xpath('../../@ID', 'Integer') " );
jxtrU.append ( " " + table[1] + " " );
jxtrU.append ( " xml_row_pattern('/root/employee/projects/project') " );
jxtrU.append ( " set Task = xml_xpath('@NewTask'), " );
jxtrU.append ( " StartDate = ? " );
jxtrU.append ( " where ProjId = xml_xpath('@ID', 'Integer') " );
jxtrU.append ( " and EmpId = xml_xpath(?, ?) " );
jxtrU.append ( " and Task = xml_xpath('@PreviousTask') " );

// Construct new JXTRUpdate object

JXTRUpdate jxtrUpdate = new JXTRUpdate ( conn, new String ( jxtrU ) );

// XML document contains ISO8601 timestamps.

jxtrUpdate.setTimestampEncoding(JXTRUpdate.TIMESTAMP_AS_ISO8601);

// Set parameters
jxtrUpdate.setTimestamp( 1, new java.sql.Timestamp
( System.currentTimeMillis() ) );
jxtrUpdate.setString ( 2, "../../@ID" );
jxtrUpdate.setString ( 3, "Integer" );

// Execute
int[][] updateCount = null;
try
{
updateCount = jxtrUpdate.executeUpdate();
} catch ( Exception ex )
{
System.out.println ( "!!! Insert failed !!!" );
if (ex instanceof JXTRUpdateException)
{

jXTransformer User’s Guide

 Coding jXTransformer Queries and Write Statements in JDBC Applications 165

// Get failed count.

updateCount = ((JXTRUpdateException)ex).getUpdateCount();
}
// Rollback changes
conn.rollback();
// Throw again.
throw ex;
}
finally
{
// Write change count to System.out
if ( updateCount == null )
{
System.out.println( "--------------------------" );
System.out.println( "No update count available." );
System.out.println( "--------------------------" );
}
else
{
// Output count header
System.out.println( "------------" );
System.out.println( "Update count" );
System.out.println( "------------" );
// Write total change count per table to System.out.
for (int i = 0; i < updateCount.length; i++)
{
int count = 0;
for (int j = 0; j < updateCount[i].length; j++)
{
count += updateCount[i][j];
}
System.out.println ( count + " row(s) were updated for table " +
table[i] );
}
}
}

// Commit changes
conn.commit();

jXTransformer User’s Guide

166 Chapter 6 Using the jXTransformer API

// Close JDBC connection

jdbcDisconnect();

/**
* Main method.
*/
public static void main ( String[] args ) throws Exception
{
Example thisDemo = new Example9();
thisDemo.execute();
}
}

jXTransformer User’s Guide

 167

7 Tutorial: Using jXTransformer

Queries

This chapter contains a step-by-step tutorial that shows you how

to create a jXTransformer query from scratch using the
jXTransformer Builder. It also shows you how to embed that
query in a JDBC application using the jXTransformer API.

This tutorial steps you through the process of constructing the

following jXTransformer query, which logically can be divided
into two parts: the first part specifies document-level constructs
and the second part specifies the data to be retrieved and
defines the structure of the XML document.

xml_document(
xml_comment('jxtr Example4 - Part 1'),
xml_external_dtd('example4.dtd'),
Specifies
document-level xml_pi('xml-stylesheet', 'type="text/xsl"
constructs href="file://example4.xsl"'),
xml_element('exns:example4',
xml_attribute('rootatt1','example4'),
xml_namespace('http://www.jxtrdemo/default'),
xml_namespace('exns','http://www.jxtrdemo/example4'),
select
xml_element('empinfo',
xml_attribute_key('exns:id',e.EmpId ),
Specifies data
to be retrieved
xml_attribute('exns:name',e.LastName),
and defines the (select
structure of xml_element('project',
the XML xml_attribute('name',p.Name),
document xml_attribute('task',a.Task))
from Projects p, Assignments a
where p.ProjId=a.ProjId and a.EmpId=e.EmpId) )
from Employees e where e.EmpId between ? and ?) )

jXTransformer User’s Guide

168 Chapter 7 Tutorial: Using jXTransformer Queries

NOTE: The preceding jXTransformer query example can be found

in the Example4.java file in the install_dir/jxtr/examples directory
(where install_dir is your jXTransformer installation directory). For
information on populating your database with test data and
using this example, refer to the README file in the
install_dir/jxtr/examples directory.

Our jXTransformer query example generates an XML document

that looks like this:
<!--jxtr Example4-->
<!DOCTYPE exns:example4 SYSTEM "example4.dtd">
<?xml-stylesheet type="test/xsl" href="file://example4.xsl"?>
<exns:example4
rootatt1=’example4’
xmlns="http://www.jxtrdemo/default"
xmlns=exns="http://www.jxtrdemo/example4">
<empinfo exns:id=’1’ name=’Marshall’>
<project name=’Medusa’ task=’Analysis’></project>
<project name=’Medusa’ task=’Documentation’></project>
<project name=’Medusa’ task=’Planning’></project>
<project name=’Medusa’ task=’Testing’></project>
<project name=’Phoenix’ task=’Analysis’></project>
<project name=’Phoenix’ task=’Documentation’></project>
</empinfo>
<empinfo exns:id='2' exns:name='Ayers'>
<project name='Hydra' task='Analysis'></project>
<project name='Hydra' task='Documentation'></project>
<project name='Python' task='Analysis'></project>
<project name='Python' task='Development'></project>
</empinfo>
<empinfo exns:id='3' exns:name='Simpson'>
<project name='Pegasus' task='Analysis'></project>
<project name='Pegasus' task='Testing'></project>
</empinfo>
<empinfo exns:id='4' exns:name='O&apos;Donnel'>
<project name='Centaur' task='Analysis'></project>
<project name='Centaur' task='Documentation'></project>
<project name='Centaur' task='Planning'></project>
</empinfo>

jXTransformer User’s Guide

 169

<empinfo exns:id='5' exns:name='Jenkins'>

<project name='Centaur' task='Analysis'></project>
<project name='Centaur' task='Testing'></project>
</empinfo>
</exns:example4>

This tutorial uses this jXTransformer query example to

demonstrate how to accomplish the following tasks with
jXTransformer:
■ Create XML documents that contain document-level
processing instructions, comments, namespaces, an external
DTD reference, and a root element. First, the tutorial will
show you how to create document-level constructs by
specifying them within the query. Later, it will show how to
specify them using the jXTransformer API. The advantage of
setting document-level constructs through the jXTransformer
API is that you can make changes to them without editing
the query.
■ Use keys to facilitate performance of data retrieval. Keys
uniquely identify each row selected by the base SQL99 query.
■ Use a nested query within a jXTransformer query. In our
jXTransformer query example, the following part of the
jXTransformer query example is a nested query:
(select
xml_element('project',
xml_attribute('name',p.Name),
xml_attribute('task',a.Task))
from Projects p, Assignments a
where p.ProjId=a.ProjId and a.EmpId=e.EmpId))
For the purposes of this tutorial, we refer to the nested query
as the child query and the query that contains the nested
query as the parent query.
■ Use parameter markers in the jXTransformer query and set
the values for those markers using the jXTransformer API.

jXTransformer User’s Guide

170 Chapter 7 Tutorial: Using jXTransformer Queries

Setting values for parameter markers can be done only

through the jXTransformer API.
■ Generate a DTD that describes the XML that results from the
jXTransformer query using the jXTransformer API.

Complete the tasks described in the next sections to create the

jXTransformer query in our example. These tasks include:
■ “Creating the jXTransformer Builder Project” on page 170
■ “Constructing the Parent Query” on page 173
■ “Constructing the Child Query” on page 180
■ “Specifying Document-Level Constructs in the jXTransformer
Query” on page 187

■ “Coding the jXTransformer Query in a JDBC Application” on

page 200

Creating the jXTransformer Builder Project

1 Start the Builder. How you start the Builder depends on your
platform:
■ On Windows: Run the builder.bat file located in your
Builder installation directory.
■ On UNIX: Run the builder.sh shell script located in your
Builder installation directory.
The builder.bat file and builder.sh script must be customized
at installation to reflect your configuration. For instructions
on customizing the builder.bat file and builder.sh script, refer
to the Installation Guide in your DataDirect package.

jXTransformer User’s Guide

 Creating the jXTransformer Builder Project 171

2 Open a new jXTransformer Builder project by selecting File /

New Project. An untitled project node appears in the Tree
view of the jXTransformer Query window.

3 Save the jXTransformer query project by selecting File / Save

Project As and specifying Example4.jxb as the filename of the
project. Notice that the project node is renamed to
Example4. As you work with this example, you can save your
changes to the project file at any time by selecting File / Save
Project.

Our jXTransformer query example contains a nested, or child,

query as shown in the following example.

select
xml_element('empinfo',
Parent xml_attribute_key('exns:id',e.EmpId ),
query xml_attribute('exns:name',e.LastName),
(select
Child
xml_element('project',
query xml_attribute('name',p.Name),
xml_attribute('task',a.Task))
from Projects p, Assignments a
where p.ProjId=a.ProjId and a.EmpId=e.EmpId))
from Employees e where e.EmpId between ? and ?

jXTransformer User’s Guide

172 Chapter 7 Tutorial: Using jXTransformer Queries

As you build the query in the example, you will construct the
parent query first. Then, you will construct the child query.

NOTE: Typically, you would construct the part of the query that
represents the structure of the XML document first, and then,
insert document-level constructs in the query. If you prefer,
however, you can insert document-level constructs first as
described in “Specifying Document-Level Constructs in the
jXTransformer Query” on page 187. Or, you can set the
document-level constructs in the jXTransformer API as shown in
“Coding the jXTransformer Query in a JDBC Application” on
page 200.

jXTransformer User’s Guide

 Constructing the Parent Query 173

Constructing the Parent Query

1 First, create a Base SQL Query for the parent query. The Base
SQL Query is required and helps defines the data to be
retrieved. It also facilitates the process of constructing the
query. To create a Base SQL Query, right-click the project
node and select Insert / Base SQL Query Node. The Base SQL
Query Node dialog box appears.

2 Type the following Base SQL Query for the parent query:
select
e.EmpId,
e.LastName
from Employees e where e.EmpId between ? and ?
The Base SQL Query accomplishes the following tasks:
■ Selects every column in the parent query containing the
data to retrieve
■ Specifies the tables from which to retrieve data
■ Optionally, specifies any filters on the Select statement
Notice that the Where clause in our example specifies a filter
on the Select statement of the parent query and contains

jXTransformer User’s Guide

174 Chapter 7 Tutorial: Using jXTransformer Queries

parameter markers. Parameter markers are placeholders for

values, represented by question marks (?). Later, this tutorial
will show you how to set the values of the parameter markers
using the jXTransformer API in “Coding the jXTransformer
Query in a JDBC Application” on page 200.
3 Click OK. The Builder checks the Base SQL Query for syntax.
The Base SQL Query node appears in the project tree.

Now that you have defined which data to retrieve from the
database for the parent query, you can define the XML
structure, including the hierarchical relationships of the data.

jXTransformer User’s Guide

 Constructing the Parent Query 175

So, examine the parent query in our example. You need to

create an XML element that contains related employee
information, including employee ID, last name of the
employee, and basic project information for that employee.

select
xml_element('empinfo',
Parent xml_attribute_key('exns:id',e.EmpId ),
query xml_attribute('exns:name',e.LastName),
(select
Child
xml_element('project',
query xml_attribute('name',p.Name),
xml_attribute('task',a.Task))
from Projects p, Assignments a
where p.ProjId=a.ProjId and a.EmpId=e.EmpId))
from Employees e where e.EmpId between ? and ?

Notice that the element named empinfo in the parent query

is a parent to the following attributes and nested query:
TIP: When ■ An attribute named exns:id that retrieves the employee
specifying table ID (a key) from the database column e.EmpId in the
names, you must database table Employees with an alias of e.
use unique table
aliases (for ■ An attribute named exns:name that retrieves the last
example, name of the employee from the database column
Employees e).
e.LastName in the database table Employees with an alias
of e.
NOTE: In our query example, the attribute names exns:id
and exns:name include a namespace prefix (exns) which is
preceded by a colon(:). The namespace in our example is
specified using a jXTransformer document-level construct
as described in “Specifying Document-Level Constructs in
the jXTransformer Query” on page 187 and “Coding the
jXTransformer Query in a JDBC Application” on page 200.
■ A nested query that retrieves basic project information
for the employee, such as the name of the project and
the task the employee worked on for that project, from

jXTransformer User’s Guide

176 Chapter 7 Tutorial: Using jXTransformer Queries

two different database tables, Projects with an alias of p

and Assignments with an alias of a.
(select
xml_element('project',
xml_attribute('name',p.Name),
xml_attribute('task',a.Task))
from Projects p, Assignments a
where p.ProjId=a.ProjId and a.EmpId=e.EmpId))
Notice that the Where clause in the nested query creates a
link between the two database tables, Projects and
Assignments.
4 Because the element only contains child constructs, you can
create an ELEMENT node named empinfo with an empty
value. Right-click the Base SQL Query node, and select Insert /
Element / Empty. The Element Node dialog box appears.

5 In the Name field, type empinfo.

jXTransformer User’s Guide

 Constructing the Parent Query 177

6 Click OK. The ELEMENT node appears in the project tree.

TIP: Because keys 7 Now, add an attribute key named exns:id that will retrieve
uniquely identify the employee ID from the database column e.EmpId. Because
rows in the this attribute key will be a child of the element named
database, we
recommend that
empinfo, right-click the ELEMENT node named empinfo.
you use keys when Select Insert / Attribute node / As Select Expression. The
possible to Attribute Node dialog box appears.
facilitate the
performance of
data retrieval.

8 In the Name field, type exns:id.

jXTransformer User’s Guide

178 Chapter 7 Tutorial: Using jXTransformer Queries

9 The database column e.EmpId is already specified in the Select

Expression drop-down list, so there is no need to select it.
10 Select the Is Key? checkbox.
11 Click OK. The ATTRIBUTE KEY node appears in the project
tree.

jXTransformer User’s Guide

 Constructing the Parent Query 179

12 Next, add an attribute named exns:name that will retrieve

the last name of the employee from the database column
e.LastName. Because this attribute will be a child of the
element named empinfo, right-click the ELEMENT node
named empinfo. Select Insert / Attribute node / As Select
Expression. The Attribute Node dialog box appears.

13 In the Name field, type exns:name.

14 In the Select Expression drop-down list, select e.LastName.
15 Click OK. The ATTRIBUTE node appears in the project tree.

jXTransformer User’s Guide

180 Chapter 7 Tutorial: Using jXTransformer Queries

Now, you have constructed the parent query and can construct
the nested child query as described in the next section.

Constructing the Child Query

1 To construct the child query, create another Base SQL Query
that is a child of the element named empinfo. To do this,
right-click the ELEMENT node named empinfo. Select Insert /
Base SQL Query. The Base SQL Query Node dialog box
appears.

2 Type the following Base SQL Query for the child query:
select
p.Name,
a.Task
from Projects p, Assignments a
where p.ProjId=a.ProjId and a.EmpId=e.EmpId

jXTransformer User’s Guide

 Constructing the Child Query 181

Remember that the Base SQL Query accomplishes the

following tasks:
■ Selects every column in the parent query containing the
data to retrieve
■ Specifies the tables from which to retrieve data
■ Optionally, specifies any filters on the Select statement

3 Click OK. The Builder checks the Base SQL Query for syntax.
The Base SQL Query node appears in the project tree.

Now that you have defined which data to retrieve from the
database for the child query, you can now define the XML
structure, including the hierarchical relationships of the data.

jXTransformer User’s Guide

182 Chapter 7 Tutorial: Using jXTransformer Queries

Examine the child query in our example as shown in the

following code. You need to create an element that contains
basic project information for the employee, including the
name of the project and the task the employee worked on for
that project.
(select
xml_element('project',
xml_attribute('name',p.Name),
xml_attribute('task',a.Task))
from Projects p, Assignments a
where p.ProjId=a.ProjId and a.EmpId=e.EmpId))
Notice that the element named project is a parent to the
following attributes:

■ An attribute named name that retrieves the name of the

project the employee worked on from the database
column p.Name in the database table Projects with an
alias of p
■ An attribute named task that retrieves the task the
employee worked on from the database column a.Task in
the database table Assignments with an alias of a
4 Because the element only contains child constructs, you can
create an ELEMENT node named project with an empty value.
To do this, right-click the Base SQL Query node, and select
Insert / Element / Empty. The Element Node dialog box
appears.

5 In the Name field, type project.

jXTransformer User’s Guide

 Constructing the Child Query 183

6 Click OK. The ELEMENT node appears in the project tree.

7 Now, add an attribute named name that will retrieve the

name of the project from the database column p.Name.
Because this attribute will be a child of the element named
project, right-click the ELEMENT node named project. Select
Insert / Attribute node / As Select Expression. The Attribute
Node dialog box appears.

8 In the Name field, type name.

9 The database column p.Name is already selected in the Select
Expression drop-down list, so there is no need to select it.

jXTransformer User’s Guide

184 Chapter 7 Tutorial: Using jXTransformer Queries

10 Click OK. The ATTRIBUTE node appears in the project tree.

11 Next, add an attribute named task that retrieves the tasks the
employee worked on from the database column a.Task.
Because this attribute will be a child of the element named
project, right-click the ELEMENT node named project. Select
Insert / Attribute node / As Select Expression. The Attribute
Node dialog box appears.

12 In the Name field, type task.

13 In the Select Expression drop-down list, select a.Task.

jXTransformer User’s Guide

 Constructing the Child Query 185

14 Click OK. The ATTRIBUTE node appears in the project tree.

15 Save the jXTransformer query example by selecting File / Save

Project.

You have completed the part of the query that specifies which
data will be retrieved and defines the XML structure of the
resulting XML document.

If you want to see what the jXTransformer query looks like using
the jXTransformer grammar, switch to Text view in the Builder by
selecting the Text View tab. If your jXTransformer query is
syntactically correct, the Builder allows you to switch from Tree
view to Text view or the reverse.

jXTransformer User’s Guide

186 Chapter 7 Tutorial: Using jXTransformer Queries

In Text view, the jXTransformer query should look like this:

To learn how to specify document-level constructs within the

query, you can continue with the next section. Or, you can specify
document-level constructs as described in “Coding the
jXTransformer Query in a JDBC Application” on page 200.

jXTransformer User’s Guide

 Specifying Document-Level Constructs in the jXTransformer Query 187

Specifying Document-Level Constructs in the

jXTransformer Query
If the jXTransformer Builder project you created in the previous
section is not already opened, open it by selecting File / Open
Project. Navigate to the project file named Example4.jxb and
select it. The project appears either in Text view or Tree view,
depending on the Builder view in which it was last saved. If the
project appears in Text view, switch to Tree view by selecting the
Tree View tab on the jXTransformer Query window.

jXTransformer User’s Guide

188 Chapter 7 Tutorial: Using jXTransformer Queries

Adding the Root Element

1 Insert a root element by selecting Insert / Document Header. A
ROOT ELEMENT node is created in the project tree with a
default root element name of jxtr-result.

2 Because the root element will be named exns:example4,

right-click the ROOT ELEMENT node and select Edit. The Root
Element Node dialog box appears with jxtr-result in the Name
field.

3 Highlight jxtr-result In the Name field and type

exns:example4.

jXTransformer User’s Guide

Specifying Document-Level Constructs in the jXTransformer Query 189

4 Click OK. The name of the ROOT ELEMENT node in the

project tree is changed to exns:example4.

Notice that the root element contains an attribute named

rootatt1and two namespace definitions. The first namespace
definition defines the default namespace; the second defines
a namespace with a prefix ID of exns.

jXTransformer User’s Guide

190 Chapter 7 Tutorial: Using jXTransformer Queries

Adding an Attribute to the Root

Element
1 Add an attribute named rootatt1 to the root element. Select
the ROOT ELEMENT node, and select Insert / Attribute Mode /
Constant. The Attribute Node dialog box appears.

2 In the Name field, type rootatt1.

3 In the Value field, type example4.

4 Click OK. The ATTRIBUTE node appears in the project tree.

jXTransformer User’s Guide

Specifying Document-Level Constructs in the jXTransformer Query 191

Add Namespaces to the Root Element

1 Define the default namespace associated with the root
element. Select the ROOT ELEMENT node, and select Insert /
Namespace Node. The Namespace Node dialog box appears.

2 Because we are defining the default namespace, there is no

prefix ID. Leave the Prefix field blank.
3 In the Namespace URI, type http://www.jxtrdemo/example4.
4 Click OK. The NAMESPACE node appears in the project tree.

jXTransformer User’s Guide

192 Chapter 7 Tutorial: Using jXTransformer Queries

5 Next, define a namespace associated with the root element

with a prefix ID of exns. Select the ROOT ELEMENT node, and
select Insert / Namespace Node. The Namespace Node dialog
box appears.

6 In the Prefix field, type exns.

7 In the Namespace URI field, type
http://www.jxtrdemo/example4.

8 Click OK. The NAMESPACE node appears in the project tree.

jXTransformer User’s Guide

Specifying Document-Level Constructs in the jXTransformer Query 193

Adding a Comment
1 Next, add a comment to the document header. Select the
project node, and select Insert / Comment. The Comment
Node dialog box appears.

2 In the Comment field, type jxtr Example4.

3 Click OK. The COMMENT node appears in the project tree.

jXTransformer User’s Guide

194 Chapter 7 Tutorial: Using jXTransformer Queries

Adding a Reference to an External DTD

1 Add a reference to an external DTD named example4.dtd.
Select the project node, and select Insert / External DTD. The
External DTD Node dialog box appears.

2 Because you are specifying a private external DTD, leave the

Public Identifier field blank.

3 In the URI field, type example4.dtd.

4 Click OK. The EXTERNAL DTD node appears in the project
tree.

jXTransformer User’s Guide

Specifying Document-Level Constructs in the jXTransformer Query 195

Adding a Processing Instruction

1 Add a processing instruction that specifies an XSL stylesheet
named example4.xsl. Select the project node, and select
Insert / Processing Instruction. The Processing Instruction
Node dialog box appears.

2 In the Processing Instruction Target field, type

xml-stylesheet.

3 In the Processing Instruction field, type "text/xsl" href=

"file://example4.xsl".

jXTransformer User’s Guide

196 Chapter 7 Tutorial: Using jXTransformer Queries

4 Click OK. The PROCESSING INSTRUCTION node appears in the

project tree.

Executing the jXTransformer Query

You have now specified all the document-level constructs in our
jXTransformer query example within the query. If you want to see
what the XML results would look like, you can execute the query
using the Builder.

NOTE: To execute the query and return valid results, you must
have created the demo database tables as explained in the
README in the install_dir/jxtr/examples directory (where
install_dir is the jXTransformer installation directory).

jXTransformer User’s Guide

Specifying Document-Level Constructs in the jXTransformer Query 197

To execute the jXTransformer query:

1 Select Project / Execute Query. If you are not connected to
the database, you must make a JDBC connection. The Open
JDBC Connection dialog box appears.

The Connection URL option is selected by default. If you

want to connect to the database using:
■ JDBC connection URL, see “Connecting Using JDBC
Connection URLs” on page 86
■ JDBC data source, see “Connecting Using JDBC Data
Sources” on page 87
Then, continue with the next step.

jXTransformer User’s Guide

198 Chapter 7 Tutorial: Using jXTransformer Queries

2 Because the jXTransformer query contains parameter markers,

the Query Parameters dialog box appears, prompting you for
the parameter values.

In the first Value field, type 1 and in the second Value field,
type 5. Then, click OK.
The Execute Query window appears.

jXTransformer User’s Guide

Specifying Document-Level Constructs in the jXTransformer Query 199

3 Click OK to execute the query. The query results appear in

the Query Results window.

Continue with the next section to learn how to code the

jXTransformer query in a JDBC application.

jXTransformer User’s Guide

200 Chapter 7 Tutorial: Using jXTransformer Queries

Coding the jXTransformer Query in a JDBC

Application
You can cut and paste the jXTransformer query from the
jXTransformer Query window of the Builder into a JDBC
application. For details about how to code the query in a JDBC
application, refer to the following examples:
■ “Example A: Document-Level Constructs in the jXTransformer
Query” on page 200 demonstrates how to embed a
jXTransformer query that contains document-level constructs
in a JDBC application.

■ “Example B: Document-Level Constructs in the jXTransformer

API” on page 205 demonstrates how to code the same
document-level constructs using the jXTransformer API
instead of coding them in the query. The advantage of setting
document-level constructs through the jXTransformer API is
that you can make changes to them without editing the
query.

Example A: Document-Level Constructs

in the jXTransformer Query
The code example in this section can be found in the
Example4.java file in the install_dir/jxtr/examples directory
(where install_dir is the jXTransformer installation directory).

The following code example performs the following tasks:

■ Imports the necessary Java classes.
■ Sends a description of the example to System.out.
■ Loads the necessary Java properties and creates a JDBC
connection.

jXTransformer User’s Guide

 Coding the jXTransformer Query in a JDBC Application 201

■ Embeds the jXTransformer query you created in the

preceding sections. Notice that the query itself specifies the
document-level constructs and that each line of the query
begins with:
jxtrQ.append ( "
and ends with:

");
Also, notice that quotes in a Java string constant must be
preceded by the Java escape character \, for example:

jxtrQ.append ( " xml_pi('xml-stylesheet', ");

jxtrQ.append ( " 'type=\"text/xsl\"
href=\"file://example4.xsl\"'), ");
■ Constructs a new jXTransformer query object named
JXTRQuery based on the specified JDBC connection,
jXTransformer query, and rewrite algorithm.
■ Sets the values for the parameter markers that are
represented by question marks in the Where clause of the
jXTransformer query by calling the jXTransformer method
setInt. The format of the jXTransformer setInt method of the
JXTRQuery class is:
setInt (paramIx, paramValue)
where paramIx identifies the parameter and paramValue sets
the value of the parameter. So, you can see that in our
example:

JXTRQuery.setInt ( 1, 1 );
sets the value of the first parameter marker to 1, and:
JXTRQuery.setInt ( 2, 5 );
sets the value of the second parameter marker to 5.

jXTransformer User’s Guide

202 Chapter 7 Tutorial: Using jXTransformer Queries

TIP: You also can ■ Generates a DTD describing the resulting XML named
generate a DTD example4.dtd by calling the jXTransformer generateDTD
that describes the method of the JXTRQuery class.
resulting XML
using the ■ Sends the resulting XML document to System.out.
jXTransformer
Builder. ■ Closes the JDBC connection and declares the main method.

import java.io.OutputStreamWriter;
import java.sql.*;

import com.ddtek.jxtr.*;

import Example;

public class Example4 extends Example

{

/**
* Executes the 'Example4' example
*/
public void execute() throws Exception
{
// Output example description
System.out.println( "Example4 demonstrates" );
System.out.println( " (a) Creating XML documents that contain
document-level processing instructions," );
System.out.println( " comments, namespaces, an external DTD
reference, and a root element with attributes." );
System.out.println( " (b) How to accomplish this through the
jXTransformer grammar" );
System.out.println( " (c) Using a parameter marker in a jXTransformer
query." );
System.out.println( " (d) Creating a DTD describing the XML that results
from executing the jXTransformer query." );

// Load properties from the resource

loadProperties();

jXTransformer User’s Guide

 Coding the jXTransformer Query in a JDBC Application 203

// Create JDBC connection

jdbcConnect();

// Build jxtr query

StringBuffer jxtrQ = new StringBuffer();
jxtrQ.append ( "xml_document( ");
jxtrQ.append ( " xml_comment('jxtr Example4' ), ");
jxtrQ.append ( " xml_external_dtd('example4.dtd' ), ");
jxtrQ.append ( " xml_pi('xml-stylesheet', ");
jxtrQ.append ( " 'type=\"text/xsl\" href=\"file://example4.xsl\"'), ");
jxtrQ.append ( " xml_element('exns:example4', ");
jxtrQ.append ( " xml_attribute('rootatt1','example4'), ");
jxtrQ.append ( " xml_namespace('http://www.jxtrdemo/default'), ");
jxtrQ.append ( " xml_namespace('exns','http://www.jxtrdemo/example4'), ");
jxtrQ.append ( " select ");
jxtrQ.append ( " xml_element('empinfo', ");
jxtrQ.append ( " xml_attribute_key('exns:id',e.EmpId ), ");
jxtrQ.append ( " xml_attribute('exns:name',e.LastName), ");
jxtrQ.append ( " (select ");
jxtrQ.append ( " xml_element('project', ");
jxtrQ.append ( " xml_attribute('name',p.Name), ");
jxtrQ.append ( " xml_attribute('task',a.Task)) ");
jxtrQ.append ( " from Projects p, Assignments a ");
jxtrQ.append ( " where p.ProjId=a.ProjId and a.EmpId=e.EmpId)) ");
jxtrQ.append ( " from Employees e where e.EmpId between ? and ?)) ");

// Construct new JXTRQuery object

JXTRQuery JXTRQuery = new JXTRQuery ( conn, new String ( jxtrQ ) );

// Set parameter marker value

JXTRQuery.setInt ( 1, 1 );
JXTRQuery.setInt ( 2, 5 );

// Create dtd
java.io.FileWriter dtdFile = new java.io.FileWriter ( "example4.dtd" );
JXTRQuery.generateDTD ( dtdFile );
dtdFile.close();

// Output result header

System.out.println( "------------" );
System.out.println( "Query result" );

jXTransformer User’s Guide

204 Chapter 7 Tutorial: Using jXTransformer Queries

System.out.println( "------------" );

// Execute
OutputStreamWriter systemOutWriter = new OutputStreamWriter ( System.out );
boolean outputDocHeader = true;
JXTRQuery.executeWriter ( systemOutWriter, outputDocHeader,
systemOutWriter.getEncoding ( ), 2 );

// Close JDBC connection

jdbcDisconnect();

/**
* Main method.
*/
public static void main ( String[] args ) throws Exception
{
Example thisDemo = new Example4();
thisDemo.execute();
}

jXTransformer User’s Guide

 Coding the jXTransformer Query in a JDBC Application 205

Example B: Document-Level Constructs

in the jXTransformer API
The following code example can be found in the Example5.java
file in the install_dir/jxtr/examples directory (where install_dir is
the jXTransformer installation directory).

The following code example performs the following tasks:

■ Imports the necessary Java classes.

■ Sends a description of the example to System.out.
■ Loads the necessary Java properties and creates a JDBC
connection.
■ Embeds a version of the jXTransformer query that does not
contain the document-level constructs in the jXTransformer
query. Instead, they are specified using the jXTransformer
API. Again, notice that each line of the query begins with:

jxtrQ.append ( "
and ends with
");
■ Constructs a new jXTransformer query object named
JXTRQuery based on the specified JDBC connection,
jXTransformer query, and rewrite algorithm.
■ Specifies the document-level constructs through the
jXTransformer API by calling the following methods:
• addDocumentComment adds the XML comment
<!--jxtr Example5--> in the document header.

• setExternalDTD creates a reference to an external DTD

named example4.dtd. Notice that this DTD was
generated by calling the jXTransformer generateDTD
method in “Example A: Document-Level Constructs in the
jXTransformer Query” on page 200.

jXTransformer User’s Guide

206 Chapter 7 Tutorial: Using jXTransformer Queries

• addDocumentPI specifies that a stylesheet named

example4.xsl be used to format the resulting XML
document.
• setRootTag creates a root element named exns:example5.

• addRootAttribute creates an attribute associated with the

root element exns:example5 that has a value of example5.
• addRootNameSpace creates a default namespace named
http://www.jxtrdemo/default. Then, the
addRootNameSpace method is repeated to define a
namespace named http://www.jxtrdemo/example5 with
the prefix ID exns.
■ Sets the values for the parameter markers that are
represented by question marks in the Where clause of our
child query. For this second version of the query, the following
code:
JXTRQuery.setInt ( 1, 6 );
sets the value of the first parameter marker to 6, and:

JXTRQuery.setInt ( 2, 10 );
sets the value of the second parameter marker to 10.
■ Sends the resulting XML document to System.out.
■ Closes the JDBC connection and declares the main method.

import java.io.OutputStreamWriter;
import java.sql.*;

import com.ddtek.jxtr.*;

import Example;

public class Example5 extends Example

{

jXTransformer User’s Guide

 Coding the jXTransformer Query in a JDBC Application 207

/**
* Executes the 'Example5' example
*/
public void execute() throws Exception
{
// Output example description
System.out.println( "Example5 demonstrates" );
System.out.println( " (a) Creating XML documents that contain
document-level processing instructions," );
System.out.println( " comments, namespaces, an external DTD
reference, and a root element with attributes." );
System.out.println( " (b) How to accomplish this through the
jXTransformer API" );
System.out.println( " (c) Using a parameter marker in a jXTransformer
query." );

// Load properties from the resource

loadProperties();

// Create JDBC connection

jdbcConnect();

// Build jxtr query

jxtrQ.append ( "select ");
jxtrQ.append ( " xml_element('empinfo', ");
jxtrQ.append ( " xml_attribute_key('exns:id',e.EmpId ), ");
jxtrQ.append ( " xml_attribute('exns:name',e.LastName), ");
jxtrQ.append ( " (select ");
jxtrQ.append ( " xml_element('project', ");
jxtrQ.append ( " xml_attribute('name',p.Name), ");
jxtrQ.append ( " xml_attribute('task',a.Task)) ");
jxtrQ.append ( " from Projects p, Assignments a ");
jxtrQ.append ( " where p.ProjId=a.ProjId and a.EmpId=e.EmpId)) ");
jxtrQ.append ( "from Employees e where e.EmpId between ? and ? ");

// Construct new JXTRQuery object

JXTRQuery JXTRQuery = new JXTRQuery ( conn, new String ( jxtrQ ) );

jXTransformer User’s Guide

208 Chapter 7 Tutorial: Using jXTransformer Queries

// Set document level comment, dtd reference and pi

JXTRQuery.addDocumentComment ( "jxtr Example5" );
JXTRQuery.setExternalDTD ( "example4.dtd" );
JXTRQuery.addDocumentPI ( "xml-stylesheet", "type=\"text/xsl\" href=
\"file://example4.xsl\"");

// Set root element name, root attribute and namespaces

JXTRQuery.setRootTag ( "exns:example5" );
JXTRQuery.addRootAttribute ( "rootatt1", "example5" );
JXTRQuery.addRootNameSpace ( "http://www.jxtrdemo/default" );
JXTRQuery.addRootNameSpace ( "exns", "http://www.jxtrdemo/example5" );

// Close JDBC connection

jdbcDisconnect();

/**
* Main method.
*/
public static void main ( String[] args ) throws Exception
{
Example thisDemo = new Example5();
thisDemo.execute();
}

jXTransformer User’s Guide

 209

A JDBC Data Types

Table A-1 lists the JDBC data types supported by jXTransformer

and the XML representations to which they are converted by the
DataDirect JDBC driver.

Table A-1. Supported JDBC Data Type Conversions to XML

Representations

JDBC Data Type XML Representation

Char As-is
Varchar As-is
Longvarchar As-is
Numeric String representation of number
Decimal String representation of number
Bit 0 or 1
Tinyint String representation of number
Smallint String representation of number
Integer String representation of number
Bigint String representation of number
Real String representation of number
Float String representation of number
Double String representation of number
Binary String containing base64 or hexadecimal
encoded binary value
Varbinary String containing base64 or hexadecimal
encoded binary value
Longvarbinary String containing base64 or hexadecimal
encoded binary value
Date YYY-MM-DD
Time HH:MI:SS

jXTransformer User’s Guide

210 Appendix A JDBC Data Types

Table A-1. Supported JDBC Data Type Conversions to XML

Representations (cont.)

JDBC Data Type XML Representation

Timestamp YYYY-MM-DD HH:MI:SS.Fractional_part
(ODBC)
or
YYYY-MM-DDTHH: MI:SS.Fractional_part
(ISO8601)
Clob As-is
Blob String containing base64 or hexadecimal
encoded binary value

jXTransformer User’s Guide

 211

B jXTransformer Statement
Processing

This appendix provides additional information that you need to

know about how jXTransformer processes jXTransformer query
and write statements.

Handling of JDBC PreparedStatement Objects

By default, jXTransformer automatically closes all JDBC
preparedStatement objects that have been created to execute a
jXTransformer query or write statement after the jXTransformer
statement is executed.

NOTE: This does not apply to JXTRQuery or

JXTRResultSetWrapper objects for which the JDBC statement
type is set to JDBC_STAT using the setPreferredJDBCStatType
method in the JXTRQueryBase class.

If DEFAULT_CLOSE_JDBC_STATEMENTS is set to false in the

JXTRBase class when the setPreparedStatementCloseBehavior
method in the JXTRBase class is invoked with the autoClose
parameter set to false, the JDBC preparedStatement objects will
remain open after execution and will be reused when the
jXTransformer statement is re-executed. In that case, an explicit
call must be made to close all JDBC preparedStatement objects and
release their associated resources.

jXTransformer User’s Guide

212 Appendix B jXTransformer Statement Processing

Using Namespaces in XPath Expressions for

jXTransformer Write Statements
When using namespaces in an XPath expression, you must map
the namespace prefixes to URIs so that matches in the input XML
document (which may use other prefixes for the same URIs) can
be made correctly. You can map namespace prefixes to URIs using
either of the following methods:
■ Specifying the jXTransformer xml_namespace constructor (see
Chapter 5 “Syntax of jXTransformer Write Statements” on
page 129 for more information)
■ Specifying the setXMLNamespaces method in the
JXTRSingleUpdateStatement class

Using NULL Replacement Values for

jXTransformer Write Statements
When an xml_xpath expression does not return text content, by
default jXTransformer interprets the value as a NULL value. If you
want to change this behavior, use the setNullReplacementValue
method in the JXTRBase class. When this method is used, the
specified value is used instead of a NULL value.

jXTransformer User’s Guide

 213

Glossary

DTD (Document The statement of rules for an XML document that specify which XML
Type Definition) elements and attributes are allowed in the document.

DOM (Document A specification for how objects in XML are represented. The DOM
Object Model) defines what attributes are associated with each XML object, and how
the objects and attributes can be manipulated.

JAXP A Java API that supports processing of XML documents using DOM,
SAX, and XSLT.

JDOM A Java API for manipulating XML documents.

jXTransformer A GUI tool that helps you create and modify jXTransformer queries
Builder without having to know the syntax of the jXTransformer grammar. You
can also use the jXTransformer Builder to check the syntax and
semantics of your jXTransformer query before you use it in your JDBC
applications. The jXTransformer Builder does not support
jXTransformer Insert, Update, and Delete statements.

jXTransformer A file with the extension .jxb that can be opened and saved by the
Builder project jXTransformer Builder. One or multiple jXTransformer queries
comprises a jXTransformer Builder project.

jXTransformer A query specified in the jXTransformer query grammar. A

query jXTransformer query contains instructions that control which data in
the database is retrieved and how the returned result set is
transformed into XML.

jXTransformer Insert, Update, and Delete statements specified in the jXTransformer

write statements write statement grammar. Write statements allows you to update data
from an XML document into a relational database.

mixed content Content for an XML element that is mixed, that is, contains character
data or character data with child elements.

namespace A unique identifier that is used to group a set of XML names (elements
or attributes).

processing A method of sending instructions to computer applications.

instruction

jXTransformer User’s Guide

214 Glossary

root element In XML, the element that is the single top-level tag. In jXTransformer, if
you omit the root element, an XML document fragment is created
instead of a complete XML document.

SAX The Simple API for XML is a standard interface for event-based XML
parsing.

schema A pattern that defines the elements, their attributes, and the
relationships between different elements.

URI (Uniform A character string that identifies the type and location of an Internet
Resource resource.
Identifier)

XML attribute A property associated with an XML element that is a named

characteristic of that element.

XML element A section of an XML document that is defined by start- and end-tags.

XPath A language that describes a way to locate and process items in XML
documents by using an addressing syntax based on a path through the
document's logical structure or hierarchy.

jXTransformer User’s Guide

 215

Index

A E
attribute-centric XML documents 39 element-centric XML documents 39
example
query 19
query in a JDBC application 159
C write statements 24
write statements in a JDBC application 162
choosing executing
rewrite algorithms 42 queries 127
XML write statements 145
document structure for queries 39
input format for write statements 45
output format for queries 41
contacting Technical Support 14 F
conventions used in this book 11
creating features, jXTransformer 17
complete XML documents 36 For XML Explicit Select statement 42
hierarchical XML documents 29
ID/IDREFS links 34
XML document fragments 36
customizing the Builder 56 G
generating
DTDs and XML schemas from queries 38
D XML from SQL99 queries 39
glossary 213
data types, JDBC to XML 209
DOM 18, 41, 45
DTDs, generating from queries 38
H
handling of JDBC preparedStatement
objects 211
hiding data in queries 33

jXTransformer User’s Guide

216 Index

hierarchical XML documents JXTRSingleTableUpdate 45, 150, 154

creating 29 JXTRSingleTableUpdateException 151
structure, choosing 39 JXTRSingleUpdateStatement 212
JXTRStatement 151
JXTRUpdate 45, 151, 154, 158
JXTRUpdateBase 151
I JXTRUpdateException 151
processing 211
ID/IDREFS links, creating 34 Reader object 45
SAX-2 41, 45
setDOM 45
setJDOM 45
J setNullReplacementValue 212
setPreparedStatementCloseBehavior 211
JAXP 18 setReader 45
JDBC applications setSAX 45
coding queries and write statements setXMLNamespaces 212
in 158 using 147
preparedStatement objects 211 Writer object 41
using jXTransformer Builder
queries in 22 about 21
write statements in 27 assigning
JDBC data types 209 constant value to an XML element 80
JDBC scalar functions 18, 114 Select expression value to an XML
JDOM 18, 41, 45 element 80
jXTransformer API base SQL query 70
classes 147 about 53
DEFAULT_CLOSE_JDBC_STATEMENTS 211 creating 70
DOM 41, 45 browsing the database 93
executeDOM 41 CDATA sections, creating 77
executeJDOM 41 changing
executeSAX 41 GUI appearance 57
executeWriter 41 text editor 59
handling of JDBC preparedStatement closing a project 64
objects 211 comments, specifying 66
JDOM 41, 45 complete XML documents, creating 55
JXTRBase 212 connecting to the database 84
JXTRQuery 38, 39, 41, 43, 127, 149, 152, constant value, assigning to an XML
158, 211 element 80
JXTRQueryBase 149, 211 creating
JXTRResultSetWrapper 40, 41, 150, base SQL query 70
152, 211 CDATA sections 77
JXTRSaxInputSource 150 complete XML documents 55
JXTRSaxReader 150 new project 63

jXTransformer User’s Guide

 Index 217

query in Text view 83 project

query in Tree view 65 closing 64
root element 55 creating new 63
XML attributes 73 opening 64
XML elements 71 project tree nodes
creating XML document fragments 55 using 50
customizing 56 working with 53
Database Browser query
JDBC filter settings 95 creating in Text view 83
using 93 creating in Tree view 65
debug logging 58 executing 89
deleting nodes 82 modifying in Text view 83
document header, turning on 66 modifying in Tree view 65
DTDs syntax, checking 84
generating from queries 101 root element
specifying external 69 and document header 55
executing queries 89 creating 66
external DTDs, specifying 69 Select expression, assigning to an XML
generating element 80
DTDs from queries 101 specifying
XML schemas from queries 103 comments 66
GUI appearance, changing 57 external DTDs 69
hiding data 76 named drivers 61
JDBC filter settings 95 namespaces 79
modifying parameter markers 90
nodes 81 processing instructions 67
query in Text view 83 starting 55
query in Tree view 65 text editor, changing 59
moving nodes 82 Text view 48, 83
named drivers, specifying 61 Tree view 48, 65
namespaces, specifying 79 turning on the document header 66
new project, creating 63 using project tree nodes 50
nodes Web browser setting 58
deleting 82 working with 48
modifying 81 XML
moving 82 attributes, creating 73
null parameter markers 90 documents, opening 99
opening DTDs, opening 97
a project 64 elements, creating 71
DTDs 97 schemas, generating from queries 103
XML documents 99
parameter markers, specifying 90
processing instructions, specifying 67

jXTransformer User’s Guide

218 Index

jXTransformer query coding in a JDBC application 158

about 18 Delete statement 141
choosing example 24
rewrite algorithm 42 executing 145
XML document structure 39 input format, choosing 45
XML output format 41 Insert statement 130
coding in JDBC applications 158 JDBC applications
creating coding in 158
in Text view of the Builder 83 using in 27
in Tree view of the Builder 65 JDBC preparedStatement objects 211
Distinct clauses in 43 processing of 44
document fragments, creating 36 syntax 129
DTDs, generating 38 using in JDBC applications 27
example 19
executing 127
generating
DTDs 38 K
XML schemas 38
hiding data in 33 keys, using in queries 31
ID/IDREFS, creating 34
JDBC applications
coding in 158
using in 22 M
JDBC preparedStatement objects 211
keys, using 31 Microsoft SQL Server 2000 and queries 42
modifying multiple queries 34
in Text view of the Builder 83
in Tree view of the Builder 65
multiple 34
nested 29, 30, 31, 32, 39, 42, 43, 169
Order By clauses in 42, 43
N
rewrite algorithms, choosing 42
namespaces, using in XPath expressions 212
syntax 107
nested queries 18, 29, 30, 31, 32, 39, 42,
tutorial 167
43, 169
using in JDBC applications 22
NULL replacement values, using in
XML document structure, choosing
jXTransformer write statements 212
attribute-centric 39
element-centric 39
hierarchical 39
XML output format, choosing 41
XML schemas, generating 38
P
jXTransformer write statements
about 23 parameter markers 18, 90, 142, 169
choosing an input format 45 processing, jXTransformer statement 211

jXTransformer User’s Guide

 Index 219

R queries
in JDBC applications 22
tutorial 167
Reader object 45 Tree and Text views of the Builder 48
reader/writer object interfaces 18 write statements in JDBC applications 27
rewrite algorithms 91
for XML explicit 42
nested loop 42
outer union 42
sorted outer union 42
W
working with
Builder 48
S Builder project tree nodes 53
Writer object 41

SAX-2 18, 41, 45

scalar functions 114
SQL99
query, generating XML documents
X
from 39
XML
Select expressions 18
attribute-centric documents 39
starting the Builder 55
choosing
SupportLink 14
input format for write statements 45
syntax
output format for queries 41
queries 107
document fragments 36
write statements 129
document structure, choosing 39
attribute-centric 39
element-centric 39
T hierarchical 39
DOM 41, 45
element-centric documents 39
Technical Support, contacting 14 hierarchical documents 29, 39
tutorial, using queries 167 input format for write statements,
choosing 45
JDBC data type conversions to XML 209
JDOM 41, 45
U output format for queries, choosing 41
output options 45
using Reader object 45
jXTransformer API 147 SAX-2 41, 45
keys in queries 31 schemas, generating 38
nested queries 30 SQL queries, generating from 39
Writer object 41

jXTransformer User’s Guide

220 Index

xml_attribute 34, 52, 111, 117

xml_attribute_key 31, 52, 117
xml_cdata 52, 119
xml_comment 51, 109
xml_document 108
xml_element 51, 52, 110, 113, 114
xml_element_key 31, 52, 114
xml_external_dtd 51, 110
xml_hide 33, 52, 122
xml_hide_key 31, 33, 52, 122
xml_namespace 52, 111, 120, 212
xml_pi 51, 110
xml_row_pattern 44
xml_xpath 44, 212
XPath 18
processing XPath expressions in
jXTransformer write statements 44
using namespaces in 212

jXTransformer User’s Guide