3 Getting Started with Oracle XML Developer's Kit for Java

This chapter explains how to get started with Oracle XML Developer's Kit (XDK) for Java.

Topics:

Installing XDK for Java Components
XDK for Java Component Dependencies
Setting Up the XDK for Java Environment
Verifying the XDK (Java) Version

Installing XDK for Java Components

XDK for Java components are included with Oracle Database. This chapter assumes that you installed XDK with Oracle Database and installed the demo programs from the Oracle Database Examples media. For a description of the XDK directory structure, see "Installing XDK".

Example 3-1 lists the main directories under the Oracle home directory for Java (This is the UNIX directory structure.) The contents of the subdirectories are listed individually, after the example.

Example 3-1 Oracle XML Developer's Kit for Java Libraries, Utilities, and Demos

- $ORACLE_HOME
    | - bin/
    | - lib/
    | - jlib/
    | - jdbc/
    | - rdbms/
    | - xdk/

The bin directory contains these components:

         orajaxb
         orapipe
         oraxml
         oraxsl
         transx

The lib directory contains these JAR and ZIP files:

         classgen.jar
         jdev-rt.zip
         oraclexsql.jar
         transx.zip
         xml.jar
         xml2.jar
         xmldemo.jar
         xmlmesg.jar
         xmlparserv2.jar
         xschema.jar
         xsqlserializers.jar
         xsu12.jar

The jlib directory contains these JAR files:

         orai18n.jar
         orai18n-collation.jar
         orai18n-mapping.jar
         orai18n-utility.jar

The jdbc directory contains this lib subdirectory:

         | - lib/
              ojdbc6.jar

The rdbms directory contains this jlib subdirectory:

         | - jlib/
              xdb.jar

And, the xdk directory contains this demo subdirectory:

         | demo/
            | - java/
                 | - classgen/
                 | - jaxb/
                 | - parser/
                 | - pipeline/
                 | - schema/
                 | - transviewer/
                 | - tranxs/
                 | - xsql/
                 | - xsu/

The /xdk/demo/java subdirectories contain sample programs and data files for XDK for Java components. The chapters in Part I, "Oracle XML Developer's Kit for Java" explain how to use these programs to learn about the most important Java features.

XDK for Java Component Dependencies

XDK for Java components are certified and supported with Java Development Kit (JDK) versions 5 and 6. Earlier versions of Java are no longer supported. Figure 3-1 shows the dependencies of XDK for Java components when using JDK 5.

Figure 3-1 Oracle XML Developer's Kit for Java Component Dependencies for JDK 5

Description of "Figure 3-1 Oracle XML Developer's Kit for Java Component Dependencies for JDK 5"

XDK for Java components need the libraries in Table 3-1. Some of the libraries are not specific to XDK, but are shared among other Oracle Database components.

Table 3-1 Java Libraries for Oracle XML Developer's Kit for Java Components

Library	Directory	Includes . . .
`classgen.jar`	`$ORACLE_HOME/lib`	Extensible Markup Language (XML) class generator for Java runtime classes. Note: This library is maintained only for backward compatibility. Use the Java Architecture for XML Binding (JAXB) class generator in `xml.jar` instead.
`jdev-rt.zip`	`$ORACLE_HOME/lib`	Java graphical user interface (GUI) libraries for use when working with the demos with the Java Development Environment (JDE).
`ojdbc6.jar`	`$ORACLE_HOME/jdbc/lib`	Oracle Java Database Connectivity (JDBC) drivers for Java 6. This Java Archive (JAR) depends on `orai18n.jar` for character set support if you use a multibyte character set other than 8-bit encoding of Unicode (UTF-8), ISO8859-1, or JA16SJIS.
`oraclexsql.jar`	`$ORACLE_HOME/lib`	Most of the XSQL Servlet classes needed to construct XSQL pages. Note: This JAR is superseded by `xml.jar` and is retained only for backward compatibility.
`orai18n.jar`	`$ORACLE_HOME/jlib`	Globalization support for JDK 1.2 or above. It is a wrapper of all other Globalization JARs and includes character set converters. If you use a multibyte character set other than UTF-8, ISO8859-1, or JA16SJIS, then put this archive in your `CLASSPATH` so that JDBC can convert the character set of the input file to the database character set when loading XML files with XML SQL Utility (XSU), TransX Utility, or XSQL Servlet.
`orai18n-collation.jar`	`$ORACLE_HOME/jlib`	Globalization collation features: the `OraCollator` class and the `lx3*.glb` and `lx4001[0-9].glb` files.
`orai18n-mapping.jar`	`$ORACLE_HOME/jlib`	Globalization locale and character set name mappings: the `OraResourceBundle` class and `lx4000[0-9].glb` files. This archive is used mainly by products that need only locale name mapping tables.
`orai18n-utility.jar`	`$ORACLE_HOME/jlib`	Globalization locale objects: the `OraLocaleInfo` class, the `OraNumberFormat` and `OraDateFormat` classes, and the `lx[01]*.glb` files.
`transx.zip`	`$ORACLE_HOME/lib`	TransX Utility classes. Note: This archive is superseded by `xml.jar` and is retained only for backward compatibility.
`xdb.jar`	`$ORACLE_HOME/rdbms/jlib`	Classes needed by `xml.jar` to access `XMLType`, classes needed to access Oracle XML DB Repository, and `XMLType` Document Object Model (DOM) classes for manipulation of the DOM tree.
`xml.jar`	`$ORACLE_HOME/lib`	JAXB and Pipeline Processor classes and classes from these libraries: `oraclexsql.jar` `xsqlserializers.jar` `transx.jar`
`xmldemo.jar`	`$ORACLE_HOME/lib`	The visual JavaBeans: `XMLTreeView`, `XMLTransformPanel`, `XMLSourceView`, and `DBViewer`.
`xmlmesg.jar`	`$ORACLE_HOME/lib`	Support for using XML parser with a language other than English.
`xmlparserv2.jar`	`$ORACLE_HOME/lib`	Application programming interfaces (APIs) for: DOM and Simple API for XML (SAX) parsers XML Schema processor Extensible Stylesheet Language Transformation (XSLT) processor XML compression Java API for XML Processing (JAXP) Utility functionality such as `XMLSAXSerializer` and asynchronous DOM Builder This library includes `xschema.jar`.
`xschema.jar`	`$ORACLE_HOME/lib`	XML Schema classes contained in `xmlparserv2.jar`. Note: This JAR file is retained only for backward compatibility.
`xsqlserializers.jar`	`$ORACLE_HOME/lib`	Classes that XSQL Servlet needs for serialized output such as PDF. Note: This archive is superseded by `xml.jar` and is retained only for backward compatibility.
`xsu12.jar`	`$ORACLE_HOME/lib`	Classes that implement XSU. These classes depend on `xdb.jar` for `XMLType` access.

Setting Up the XDK for Java Environment

To set up the XDK for Java environment, do either of the following:

During Oracle Database installation of XDK, manually set the $CLASSPATH (UNIX) or %CLASSPATH% (Windows) environment variables.
When compiling and running Java programs at the command line, set the -classpath option.

Topics:

Setting XDK for Java Environment Variables for UNIX
Testing the XDK for Java Environment on UNIX
Setting XDK for Java Environment Variables for Windows
Testing the XDK for Java Environment on Windows

Setting XDK for Java Environment Variables for UNIX

Table 3-2 describes the UNIX environment variables that the XDK for Java components need.

Table 3-2 UNIX Environment Variables for Oracle XML Developer's Kit for Java Components

Variable	Description
`$CLASSPATH`	Includes: .:${CLASSPATHJ}:${ORACLE_HOME}/lib/xmlparserv2.jar: ${ORACLE_HOME}/lib/xsu12.jar:${ORACLE_HOME}/lib/xml.jar Note: A period (.) to represent the current directory is optional.
`$CLASSPATHJ`	For JDK 5, set: CLASSPATHJ=${ORACLE_HOME}/jdbc/lib/ojdbc6.jar:${ORACLE_HOME}/jlib/orai18n.jar Certain character sets need `orai18n.jar`.
`$JAVA_HOME`	Installation directory for the Java JDK, Standard Edition. Modify the path that links to the Java SDK.
`$LD_LIBRARY_PATH`	For OCI JDBC connections: ${ORACLE_HOME}/lib:${LD_LIBRARY_PATH}
`$PATH`	`${JAVA_HOME}/bin`

After setting up the XDK for Java environment on UNIX, you can use the command-line utilities described in Table 3-3.

Table 3-3 Oracle XML Developer's Kit for Java UNIX Utilities

Executable/Class	Directory/JAR	Description
`xsql`	`$ORACLE_HOME/bin`	XSQL command-line utility. The script executes the `oracle.xml.xsql.XSQLCommandLine` class. Edit this shell script for your environment before use. See Also: "Using the XSQL Pages Command-Line Utility"
`OracleXML`	`$ORACLE_HOME/lib/xsu12.jar`	XSU command-line utility See Also: "Using the XSU Command-Line Utility"
`orajaxb`	`$ORACLE_HOME/bin`	JAXB command-line utility See Also: "Using the JAXB Class Generator Command-Line Utility"
`orapipe`	`$ORACLE_HOME/bin`	Pipeline command-line utility See Also: "Using the XML Pipeline Processor Command-Line Utility"
`oraxml`	`$ORACLE_HOME/bin`	XML parser command-line utility See Also: "Using the XML Parser Command-Line Utility (oraxml)"
`oraxsl`	`$ORACLE_HOME/bin`	XSLT processor command-line utility See Also: "Using the XSLT Processor Command-Line Utility"
`transx`	`$ORACLE_HOME/bin`	TransX command-line utility See Also: "Using the TransX Command-Line Utility"

Testing the XDK for Java Environment on UNIX

If your environment is set up correctly, then the UNIX shell script in Example 3-2 generates version and usage information for the utilities in Table 3-3.

Example 3-2 Testing the Oracle XML Developer's Kit for Java Environment on UNIX

#!/usr/bin/tcsh
echo;echo "BEGIN TESTING";echo
echo;echo "now testing the XSQL utility...";echo
xsql
echo; echo "now testing the XSU utility...";echo
java OracleXML
echo;echo "now testing the JAXB utility...";echo
orajaxb -version
echo;echo "now testing the Pipeline utility...";echo
orapipe -version
echo;echo "now testing the XSLT Processor utility...";echo
oraxsl
echo;echo "now testing the TransX utility...";echo
transx
echo;echo "END TESTING"

Setting XDK for Java Environment Variables for Windows

Table 3-4 describes the Windows environment variables that the XDK for Java components need.

Table 3-4 Windows Environment Variables for Oracle XML Developer's Kit for Java Components

Variable	Notes
`%CLASSPATH%`	Includes: .;%CLASSPATHJ%;%ORACLE_HOME%\lib\xmlparserv2.jar; %ORACLE_HOME%\lib\xsu12.jar;%ORACLE_HOME%\lib\xml.jar; %ORACLE_HOME%\lib\xmlmesg.jar;%ORACLE_HOME%\lib\oraclexsql.jar Note: A single period "." to represent the current directory is not required, but may be useful.
`%CLASSPATHJ%`	For JDK 5, set: CLASSPATHJ=%ORACLE_HOME%\jdbc\lib\ojdbc6.jar:%ORACLE_HOME%\lib\orai18n.jar The `orai18n.jar` is needed to support certain character sets.
`%JAVA_HOME%`	Installation directory for the Java software developer's kit (SDK), Standard Edition. Modify the path that links to the Java SDK.
`%PATH%`	`%JAVA_HOME%\bin`

After setting up the XDK for Java environment on Windows, you can use the command-line utilities described in Table 3-5.

Table 3-5 Oracle XML Developer's Kit for Java Windows Utilities

Batch File/Class	Directory/JAR	Description
`xsql.bat`	`%ORACLE_HOME%\bin`	XSQL command-line utility. The batch file executes the `oracle.xml.xsql.XSQLCommandLine` class. Edit the batch file for your environment before use. See Also: "Using the XSQL Pages Command-Line Utility"
`OracleXML`	`%ORACLE_HOME%\lib\xsu12.jar`	XSU command-line utility See Also: "Using the XSU Command-Line Utility"
`orajaxb.bat`	`%ORACLE_HOME%\bin`	JAXB command-line utility See Also: "Using the JAXB Class Generator Command-Line Utility"
`orapipe.bat`	`%ORACLE_HOME%\bin`	Pipeline command-line utility See Also: "Using the XML Pipeline Processor Command-Line Utility"
`oraxml.bat`	`%ORACLE_HOME%\bin`	XML parser command-line utility See Also: "Using the XML Parser Command-Line Utility (oraxml)"
`oraxsl.bat`	`%ORACLE_HOME%\bin`	XSLT processor command-line utility See Also: "Using the XSLT Processor Command-Line Utility"
`transx.bat`	`%ORACLE_HOME%\bin`	TransX command-line utility See Also: "Using the TransX Command-Line Utility"

Testing the XDK for Java Environment on Windows

If your environment is set up correctly, then you can run the commands in Example 3-3 at the system prompt to generate version and usage information for the utilities in Table 3-5.

Example 3-3 Testing the Oracle XML Developer's Kit for Java Environment on Windows

xsql.bat
java OracleXML
orajaxb.bat -version
orapipe.bat -version
oraxsl.bat
transx.bat

Verifying the XDK (Java) Version

To see which version of XDK you have installed, use javac to compile the Java code shown in Example 3-4.

Example 3-4 XDKVersion.java

//
// XDKVersion.java
//
import java.net.URL;
import oracle.xml.parser.v2.XMLParser;
public class XDKVersion
{
   static public void main(String[] argv)
   {
      System.out.println("You are using version: ");
      System.out.println(XMLParser.getReleaseVersion());
   }
}

After compilation, run the program on the operating system command line:

java XDKVersion

The result is similar to:

You are using version:
Oracle XML Developers Kit 11.1.0.6.0 - Production