3 Getting Started with Java XDK Components

This chapter contains these topics:

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 Examples media. Refer to "Installing the XDK" for installation instructions and a description of the XDK directory structure.

Example 3-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 3-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
         xml2.jar
         xmlcomp.jar
         xmlcomp2.jar
         xmldemo.jar
         xmlmesg.jar
         xmlparserv2.jar
         xschema.jar
         xsqlserializers.jar
         xsu12.jar
    | - jlib/
         orai18n.jar
         orai18n-collation.jar
         orai18n-mapping.jar
         orai18n-utility.jar
    | - jdbc/
         | - lib/
              ojdbc5.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 version 5 and version 6. Earlier versions of Java are no longer supported. Figure 3-1 shows the dependencies of Java XDK components when using JDK 5.

Figure 3-1 Java XDK Component Dependencies for JDK 5

Description of Figure 3-1 follows
Description of "Figure 3-1 Java XDK Component Dependencies for JDK 5"

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

Table 3-1 Java Libraries for XDK Components

Library Directory Includes . . .

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.

ojdbc5.jar, ojdbc6.jar

$ORACLE_HOME/jdbc/lib

Oracle JDBC drivers for Java 5, 6. 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 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 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.


See Also:

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

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

Table 3-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 5, set as follows:

CLASSPATHJ=${ORACLE_HOME}/jdbc/lib/ojdbc5.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 3-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 3-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 3-2 should generate version and usage information for the utilities.

Example 3-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 3-4 describes the Windows environment variables required for use with the Java XDK components.

Table 3-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 5, set as follows:

CLASSPATHJ=%ORACLE_HOME%\jdbc\lib\ojdbc5.jar:%ORACLE_HOME%\lib\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 3-5 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 3-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 3-3 at the system prompt to generate version and usage information for the utilities.

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

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