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 "Figure 2-1 XDK Java Components Dependencies Using JDK 1.2.x and Higher"

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

}