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:

3.1 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 "About 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.

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 inOracle XML Developer's Kit for Java explain how to use these programs to learn about the most important Java features.

See Also:

Table 1-1 for descriptions of individual XDK for Java components

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

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

3.2 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 follows
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.

See Also:

3.3 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:

3.3.1 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"

3.3.2 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"

3.3.3 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"

3.3.4 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

3.4 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.

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

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());
   }
}