Skip Headers

Oracle® XML Developer's Kit Programmer's Guide 10g Release 2 (10.1.2) Part No. B14033-01 |
| Contents | Index

Previous | Next |

# 2 Getting Started with XDK Java Components

This chapter contains these topics:

- XDK Java Components Specifications

- Installing XDK Java Components

- XDK Java Components Directory Structure

- XDK Java Components Environment Settings

- XDK Java Components Globalization Support

- XDK Java Components Dependencies

- Verifying the XDK Java Components Version

## XDK Java Components Specifications

XDK Java components, release 10.1, are built on these specifications:

- XML 1.0 (Second Edition)

- DOM Level 2.0 Specifications

  - DOM Level 2.0 Core

  - DOM Level 2.0 Traversal and Range

  - DOM Level 2.0 Events

- DOM Level 3.0 Specifications

  - DOM Level 3.0 Load and Save (internal draft version 10 October 2003)

  - DOM Level 3.0 Validation (Candidate Recommendation 30 July 2003)

- SAX 2.0 and SAX Extensions

- XSLT/XPath 2.0 Specifications

  - XSL Transformations (XSLT) 2.0 (working draft dated 02 May 2003)

  - XML Path Language (XPath) 2.0 (working draft dated 22 August 2003)

  - XPath 2.0 Data Model (working draft dated 11th November 2002)

- XML Schema Specifications

  - XML Schema Part 0: Primer

  - XML Schema Part 1: Structures

  - XML Schema Part 2: Datatypes

- XML Pipeline Definition Language 1.0

- Java API for XML Processing 1.1 and 1.2 (JAXP)

- Java Architecture for XML Binding 1.0 (JAXB)

### DOM Specifications

In release 10.1, the DOM APIs include support for two new working drafts, DOM Level 3 Validation and DOM Level 3 Load and Save.

Load and Save

The DOM Level 3 Load and Save module enables software developers to load and save XML content inside conforming products. DOM 3.0 Core interface `DOMConfiguration` is referred by DOM 3 Load and Save. Although DOM 3.0 Core is not supported, a limited implementation of this interface is available.

The following configuration parameters are supported by `XMLDOMBuilder` which implements `LSParser`:

- "cdata-sections"

- "validate"

- "validate-if-schema"

- "whitespace-in-element-content"

The following configuration parameters are supported by `XMLDOMWriter` which implements `LSSerializer`:

- "format-pretty-print"

- "xml-declaration"

Validation

DOM 3.0 validation allows users to retrieve the metadata definitions from XML schemas, query the validity of DOM operations and validate the DOM documents or sub-trees against the XML schema.

Some DOM 3 Core functions referred by Validation are implemented, but Core itself is not supported:

`NameList` and `DOMStringList` in DOM core are supported for validation purpose.

Validation is based on XML Schema, DTD needs to be converted to Schema first (use `DTDToSchema` utility).

### XSL Transformations Specifications

The XSLT processor adds support for the current working drafts of XSLT 2.0, XPath 2.0, and the shared XPath/XQuery data model.

For the XPath 2.0 specification, only the new XPath 2.0 grammar and backwards compatibility with XPath 1.0 are supported.

These features of the specifications are not supported in release 10.1:

- The functions in the Functions and Operators specification are not supported. Only the functions from XSLT 1.0 specification are supported.

- The `validate` and `complex` types in `SequenceType` expressions are not supported.

- The new datatypes `fn:yearMonthduration` and `fn:dayTimeDuration` are not supported.

- The Schema Import and Static Typing features are not supported.

- The XSLT instructions `xsl:result-document` and `xsl:namespace` are not supported.

- The XSLT instructions`xsl:text` and `xsl:number` use XSLT 1.0 semantics and syntax.

- The standard attributes are allowed only on `xsl:stylesheet` and literal result elements, except for `default-xpath-namespace` and `version`.

- The processor does not honor the following attributes:

  - `[required]` on `xsl:param`

  - [XML Schema related attributes, like `xsl:validation` and `xsl:type`, etc.

- Regular expression functions are not supported.

- Parameters are not passed through built-in templates.

- `xsl:sequence` is not supported

## Installing XDK Java Components

XDK Java components are included with the Oracle database and with the Oracle application server. You can download the latest beta or production version of XDK Java components from OTN as part of the XDK. The XDK Java components and JavaBeans are now bundled together.

If you installed XDK with the Oracle database or the Oracle application server, you can use this chapter as a reference.

If you download the XDK from OTN, follow these steps:

- Go to the URL:

      http://www.oracle.com/technology/tech/xml/xdk/content.html

- Click the Software link on the right-side of the page.

- Logon with your OTN username and password (registration is free if you do not already have an account).

- Select the Windows or UNIX download.

- Select the appropriate download for your operating system.

- Accept all terms of the licensing agreement and then download the software by clicking the appropriate distribution.

- Extract the files in the distribution:

  - Choose a directory under which you want the `./xdk` directory and subdirectories to go.

  - Change to that directory and then extract the XDK Java components download archive file. For UNIX:

        tar xvfz xdk_XXXX.tar.gz       # UNIX. XXXX is the release name
        Use WinZip visual archive extraction tool in Windows

## XDK Java Components Directory Structure

After installing the XDK, the directory structure is:

    -$XDK_HOME
        | - bin: executable files and setup script or batch files.
        | - lib: library files.
        | - xdk:
             | - admin: (Administration): SQL script and XSL Servlet Configuration
                         file (XSQLConfig.xml).
             | - demo/java: demonstration code
             | - doc/java: documents including release notes and Javadoc HTML.

All the XDK Java components are certified and supported with JDK 1.2, JDK 1.3, and JDK 1.4. Make sure that your CLASSPATH includes all the necessary libraries:

Table 2-1 XDK Java Components Libraries

Component | Library | Notes
--- | --- | ---
XML Parser, XSL Processor | `xmlparserv2.jar` | XML Parser V2 for Java, which includes JAXP 1.1, DOM, SAX and XSLT APIs.
Message files for XML Parser. | `xmlmesg.jar` | If you want to use XML Parser with a language other than English, you need to set this JAR file in your `CLASSPATH`.
XML Schema Processor | `xschema.jar` | XML Schema Processor for Java.
XML SQL Utility | `xsu12.jar` | XML SQL Utility for JDK 1.2 and later.
XSQL Servlet | `oraclesql.jar` | Oracle XSQL Servlet.
XSQL | `xsqlserializers.jar` | Oracle XSQL Serializers for FOP/PDF Integration.
JAXB Class Generator, Pipeline Processor, Differ | `xml.jar` | Class Generator for Java.
JavaBeans | `xmlcomp.jar` `xmlcomp2.jar` | JavaBeans Utilities.
TransX Utility | `transx.zip` | Oracle TransX Utility.

In addition, XML SQL Utility, XSQL Servlet, and TransX Utility all depend on JDBC and globalization support libraries, which are listed in Table 2-2:

Table 2-2 JDBC and Globalization Support Libraries for XDK Java Components

Component | Library | Notes
--- | --- | ---
JDBC | `classes12.zip` | JDBC for JDK 1.2 and later.
Globalization Support | `orai18n.jar` | Globalization support for JDK 1.2 and later.
XMLType | `xdb.jar` | XMLType Java APIs in `$ORACLE_HOME/rdbms/jlib/`
JDeveloper Runtime | `jdev-rt.zip` | Java GUI libraries.

## XDK Java Components Environment Settings

The UNIX and Windows environment settings are listed:

### UNIX Environment Settings for XDK Java Components

This file sets up the environment:

`$XDK_HOME/bin/env.csh`

Table 2-3 lists the UNIX environment variables, with the ones that must be customized each marked with "Yes":

Table 2-3 UNIX Environment Settings for XDK Java Components

Variable | Notes | Yes/No
--- | --- | ---
`$JDBCVER` | JDBC version. For JDK 1.2 and later, set to 12. | Yes
`$JDKVER` | JDK version obtained by `JDK -version.`Default value is 1.2.2_07. | Yes
`$INSTALL_ROOT` | Installation root of XDK which is the directory `$XDK_HOME`. | No
`$JAVA_HOME` | Directory where the Java JDK, Standard Edition is installed. | Yes
`$CLASSPATHJ` | `{ORACLE_HOME}/jdbc/lib/classes${JDBCVER}.zip:` `${ORACLE_HOME}/jdbc/lib/nls_charset${JDBCVER}.jar` If you are running the XSU on a system different from where the Oracle database is installed, you have to update your `CLASSPATHJ` setting with the correct locations of the JDBC library `(classes12.jar`). The `orai18n.jar` is needed to support certain character sets. See "XDK Java Components Globalization Support". Note that if you do not have these libraries on your system, these are both available on OTN (`http://www.oracle.com/technology`), as part of the JDBC driver download. | Yes
`$CLASSPATH` | Include the following: .`:${CLASSPATHJ}:${INSTALL_ROOT}/lib/xmlparserv2.jar:` `${INSTALL_ROOT}/lib/xschema.jar:` `${INSTALL_ROOT}/lib/xsu${JDBCVER}.jar:` `${INSTALL_ROOT}/lib/oraclexsql.jar:` `${INSTALL_ROOT}/lib/classgen.jar` | No
`$PATH` | `${JAVA_HOME}/bin:${PATH}:${INSTALL_ROOT}/bin` | No
`$LD_LIBRARY_PATH` | For OCI JDBC connections: `${ORACLE_HOME}/lib:${LD_LIBRARY_PATH}` | No

### Windows Environment Settings for XDK Java Components

This file sets up the environment:

`%XDK_HOME%\bin\env.bat`

Table 2-4 lists the Windows environment variables with the ones that must be customized each marked with "Yes":

Table 2-4 Windows Environment Settings for XDK Java Components

Variable | Notes | Yes/No
--- | --- | ---
`%JDBCVER%` | JDBC version. If using JDK 1.2 and later, it should be set to 12. | Yes
`%JDKVER%` | JDK version which you can get from: `JDK -version.`Default value is 1.2.2_07. | Yes
`%INSTALL_ROOT%` | Installation root of XDK, which is the directory `%XDK_HOME%`. | No
`%JAVA_HOME%` | Directory where the Java SDK, Standard Edition is installed. | Yes
`%CLASSPATHJ%` | `CLASSPATHJ=%ORACLE_HOME%\jdbc\lib\classes%JDBCVER%.zip;` `%ORACLE_HOME%\jdbc\lib\nls_charset%JDBCVER%.jar` | Yes
`%CLASSPATH%` | `.;%CLASSPATHJ%;%INSTALL_ROOT%\lib\xmlparserv2.jar;` `%INSTALL_ROOT%\lib\xschema.jar;` `%INSTALL_ROOT%\lib\xsu%JDBCVER%.jar;` `%INSTALL_ROOT%\lib\oraclexsql.jar;%INSTALL_ROOT%\lib\classgen.jar` | No
`%PATH%` | `PATH=%JAVA_HOME%\bin;%ORACLE_HOME%\bin;%PATH%;%INSTALL_ROOT%\bin` | No

## XDK Java Components Globalization Support

Here is a summary on the settings that relate to Globalization Support:

- Using `xmlmesg.jar`: If you are using a language other than English you need to set the `xmlmesg.jar` into your `CLASSPATH` to let the parser get correct messages in your language.

- Using `orai18n.jar`: If you are using a multibyte character set other than one of the following,

  - UTF-8

  - ISO8859-1

  - JA16SJIS

  then you must set this JAR file into your Java `CLASSPATH` so that JDBC can convert the character set of the input file to the database character set during the loading of XML files using either XSU, TransX or XSQL Servlet.

## XDK Java Components Dependencies

Figure 2-1 shows the dependencies of XDK Java Components when using JDK 1.2 and higher:

Figure 2-1 XDK Java Components Dependencies Using JDK 1.2.x and Higher

Description of the illustration adxdk110.gif

After you correctly setup the environment, include all the necessary JAR files in your CLASSPATH. You can then start writing your Java programs and compiling them with the`javac` command:

    javac your_program.java

If the compilation finishes without errors, then you can just test your program using the command line or the Web Server.

See Also: Chapter 3, "XML Parser for Java" for further discussion of the XDK Java components

## Verifying the XDK Java Components Version

To obtain the version of XDK you are working with, compile and run the following Java code (`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());
       }

    }