2 Getting Started with Java XDK Components

This chapter contains these topics:

Installing Java XDK Components
Java XDK Component Dependencies
Setting Java XDK Environment Variables for UNIX
Setting Java XDK Environment Variables for Windows
Verifying the Java XDK Components Version

Installing Java XDK Components

The Java XDK components are included with Oracle Database. This chapter assumes that you have installed XDK with Oracle Database and also installed the demo programs on the Oracle Database Companion CD. Refer to "Installing the XDK" for installation instructions and a description of the XDK directory structure.

Example 2-1 shows the UNIX directory structure for the XDK demos and the libraries used by the XDK components. The $ORACLE_HOME/xdk/demo/java subdirectories contain sample programs and data files for the XDK for Java components. The chapters in Part I, "XDK for Java" explain how to understand and use these programs.

Example 2-1 Java XDK Libraries, Utilities, and Demos

- Oracle_home_directory
    | - bin/
         orajaxb
         orapipe
         oraxml
         oraxsl
         transx
    | - lib/
         classgen.jar
         jdev-rt.zip
         oraclexsql.jar
         transx.zip
         xml.jar
         xml.jar
         xmlcomp.jar
         xmlcomp2.jar
         xmldemo.jar
         xmlmesg.jar
         xmlparserv2.jar
         xschema.jar
         xsqlserializers.jar
         xsu12.jar
    | - jlib/
         classes12.jar
         orai18n.jar
         orai18n-collation.jar
         orai18n-mapping.jar
         orai18n-utility.jar
    | - jdbc/
         | - lib/
              ojdbc14.jar
    | - rdbms/
         | - jlib/
              xdb.jar

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

The subdirectories contain sample programs and data files for the Java XDK components. The chapters in Part I, "XDK for Java" explain how to use these programs to gain an understanding of the most important Java features.

Java XDK Component Dependencies

The Java XDK components are certified and supported with JDK versions 1.2, 1.3, and 1.4. Figure 2-1 shows the dependencies of Java XDK components when using JDK 1.2 and higher.

Figure 2-1 Java XDK Component Dependencies for JDK 1.2 and Higher

Description of the illustration adxdk110.gif

The Java XDK components require the libraries alphabetically listed in Table 2-1. Note that some of the libraries are not specific to the XDK, but are shared among other Oracle Database components.

Table 2-1 Java Libraries for XDK Components

Library	Directory	Includes . . .
`classes12.jar`	`$ORACLE_HOME/jdbc/lib`	Oracle JDBC drivers for Java 1.2 and 1.3. This JAR depends on `orai18n.jar` for character set support if you use a multibyte character set other than UTF-8, ISO8859-1, or JA16SJIS.
`classgen.jar`	`$ORACLE_HOME/lib`	XML class generator for Java runtime classes. Note: This library is maintained for backward compatibility only. You should use the JAXB class generator in `xml.jar` instead.
`jdev-rt.zip`	`$ORACLE_HOME/lib`	Java GUI libraries for use when working with the demos with the JDeveloper IDE.
`ojdbc14.jar`	`$ORACLE_HOME/jdbc/lib`	Oracle JDBC drivers for Java 1.4. This JAR depends on `orai18n.jar` for character set support if you use a multibyte character set other than UTF-8, ISO8859-1, or JA16SJIS.
`oraclexsql.jar`	`$ORACLE_HOME/lib`	Most of the XSQL Servlet classes needed to construct XSQL pages. Note: This archive is superseded by `xml.jar` and is maintained for backward compatibility only.
`orai18n.jar`	`$ORACLE_HOME/jlib`	Globalization support for JDK 1.2 and later. 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 place 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 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 mainly used by the 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 replaced by `xml.jar` and is retained for backward compatibility only.
`xdb.jar`	`$ORACLE_HOME/rdbms/jlib`	Classes needed by `xml.jar` and `xmlcomp2.jar` to access `XMLType`. It also includes classes needed to access the XML DB Repository as well as the `XMLType` DOM classes for manipulation of the DOM tree.
`xml.jar`	`$ORACLE_HOME/lib`	Classes from the following libraries: `oraclexsql.jar` `xsqlserializers.jar` `xmlcomp.jar` `xmlcomp2.jar` `transx.jar` The archive also contains the JAXB and Pipeline Processor classes.
`xmlcomp.jar`	`$ORACLE_HOME/lib`	XML JavaBeans that do not depend on the database: `DOMBuilder`, `XSLTransformer`, `DBAccess`, `XSDValidator`, and `XMLDiffer`. Note: This archive is included for backward compatibility only because its classes are included in `xml.jar`. They do not include the visuals Beans included in previous releases.
`xmlcomp2.jar`	`$ORACLE_HOME/lib`	XML JavaBeans that depend on the database: `XMLDBAccess` and `XMLCompress`. Thus, it depends on `xdb.jar`, which includes the classes that support XML DB. Note: This JAR is included for backward compatibility only because its classes are included in `xml.jar`. They do not include the visuals Beans included in previous releases.
`xmldemo.jar`	`$ORACLE_HOME/lib`	The visual JavaBeans: `XMLTreeView`, `XMLTransformPanel`, `XMLSourceView`, and `DBViewer`.
`xmlmesg.jar`	`$ORACLE_HOME/lib`	Needed if you use XML parser with a language other than English.
`xmlparserv2.jar`	`$ORACLE_HOME/lib`	APIs for the following: DOM and SAX parsers XML Schema processor XSLT processor XML compression JAXP Utility functionality such as `XMLSAXSerializer` and asynchronous DOM Builder This library includes `xschema.jar`.
`xschema.jar`	`$ORACLE_HOME/lib`	Includes the XML Schema classes contained in `xmlparserv2.jar`. Note: This JAR file is maintained for backward compatibility only.
`xsqlserializers.jar`	`$ORACLE_HOME/lib`	Serializer classes for XSQL Servlet needed for serialized output such as PDF. Note: This archive is superseded by `xml.jar` and is maintained for backward compatibility only.
`xsu12.jar`	`$ORACLE_HOME/lib`	Classes that implement XSU. These classes have a dependency on `xdb.jar` for `XMLType` access.

Setting Up the Java XDK Environment

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

This section contains the following topics:

Setting Java XDK Environment Variables for UNIX
Setting Java XDK Environment Variables for Windows

Setting Java XDK Environment Variables for UNIX

Table 2-2 describes the UNIX environment variables required for use with the Java XDK components.

Table 2-2 UNIX Environment Settings for Java XDK Components

Variable	Description
`$CLASSPATH`	Includes the following (note that a single period "." to represent the current directory is not required but may be useful): .:${CLASSPATHJ}:${ORACLE_HOME}/lib/xmlparserv2.jar: ${ORACLE_HOME}/lib/xsu12.jar:${ORACLE_HOME}/lib/xml.jar
`$CLASSPATHJ`	For JDK 1.2 and 1.3, set as follows: CLASSPATHJ=${ORACLE_HOME}/jdbc/lib/classes12.jar: ${ORACLE_HOME}/jlib/orai18n.jar For JDK 1.4, set as follows: CLASSPATHJ=${ORACLE_HOME}/jdbc/lib/ojdbc.jar:${ORACLE_HOME}/jlib/orai18n.jar The `orai18n.jar` is needed to support certain character sets.
`$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`

Testing the Java XDK Environment on UNIX

Table 2-3 describes the command-line utilities included in the Java XDK on UNIX. Before you can use these utilities, you must set up your environment.

Table 2-3 Java XDK 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"
`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"

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

Example 2-2 Testing the Java XDK 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 Java XDK Environment Variables for Windows

Table 2-4 describes the Windows environment variables required for use with the Java XDK components.

Table 2-4 Windows Environment Settings for Java XDK Components

Variable	Notes
`%CLASSPATH%`	Includes the following (note that a single period "." to represent the current directory is not required but may be useful): .;%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
`%CLASSPATHJ%`	For JDK 1.2 and 1.3, set as follows: CLASSPATHJ=%ORACLE_HOME%\jdbc\lib\classes12.jar;%ORACLE_HOME%\jlib\orai18n.jar For JDK 1.4, set as follows: CLASSPATHJ=%ORACLE_HOME%\jdbc\lib\ojdbc.jar;%ORACLE_HOME%\jlib\orai18n.jar The `orai18n.jar` is needed to support certain character sets.
`%JAVA_HOME%`	Installation directory for the Java SDK, Standard Edition. Modify the path that links to the Java SDK.
`%PATH%`	`%JAVA_HOME%\bin`

Testing the Java XDK Environment on Windows

Table 2-3 describes the command-line utilities included in the Java XDK on Windows. Before you can use these utilities, you must set up your environment.

Table 2-5 Java XDK 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"
`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"

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

Example 2-3 Testing the Java XDK Environment on Windows

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

Verifying the Java XDK Components Version

To obtain the version of XDK you are working with, use javac to compile the Java code shown in Example 2-4.

Example 2-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 compiling the source file with javac, run the program on the operating system command line as follows:

java XDKVersion