2
Getting Started with XDK for Java and JavaBeans

This chapter contains the following sections:

Installation of the XDK for Java

XDK for Java contains the basic building blocks for reading, manipulating, transforming and viewing XML documents.

Note:

The XDKs for Java and JavaBeans are now bundled together.

Oracle XDK for Java consists of the following components:

XML Parser: supports parsing XML documents with both the DOM or SAX interfaces.
XSL Processor: is included as part of the XML Parser and supports transforming XML documents.
XML Schema Processor: supports parsing and validating XML files against an XML Schema definition file (default extension .xsd).
Class Generator: generates a set of Java source files based on an input DTD or XML Schema.
XML SQL Utility: generates an XML Document from SQL queries and inserts the document into the database.
TransX Utility: makes it easier to load translated seed data and messages into the database.
XSQL Servlet: produces dynamic XML documents based on one or more SQL queries.

Installation Steps for XDK for Java

XDK for Java comes with the Oracle database and with the application server. Or, you can download the latest beta or production version of XDK for Java from OTN.

If you installed XDK with Oracle database or iAS, you can skip the following steps and change into the XDK home directory ($XDK_HOME).

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

Go to the URL:

http://otn.oracle.com/tech/xml/xdk_java/content.html

Click on the `Software' icon at the left side of the page.

Logon with your OTN username and password (registration is free if you do not already have an account).
Select the version you want to download.

Accept all terms of the licensing agreement and download the software. Here are the instructions found on the download site for Solaris^TM Operating Environment:

Oracle XML Developer's Kit for Java on Sun Solaris^TM Operating Environment- 9i
   Download the Complete File

   xdk_java_9_0_1_1_0A.tar.gz 
   Directions

   Install  GNU gzip.

   Download the Oracle XDK for Java in .tar format

   Extract the distribution package into a directory. 
   (Ex: #gzip -dc xdk_java.tar | tar xvf -)

   The result should be the following files and directories:
          /bin - xdk executables and utilities
          /lib - directory for libraries
          /xdk - top xdk directory
          /xdk/demo - directory for demo files
          /xdk/doc - directory for documentation 
          /xdk/admin - direcory for dband config files
          /xdk/*html. - doc navigation files
          /xdk/license.html - copy of license agreement

For Windows NT, choose a directory under which you would like the .\xdk directory and subdirectories to go (for example, C:\ on NT), change the directory to C:\ then extract the files using the WinZip visual tool.

What Are the XDK for Java Components?

After installing the XDK, the directory structure is:

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

All the packages in XDK for Java are certified and supported with JDK 1.2 or JDK 1.1.8, so make sure that your CLASSPATH includes all the necessary libraries:

Table 2-1 XDK for Java Libraries

Component	Library	Notes
XML Parser XSL Processor	xmlparserv2.jar xmlmesg.jar	XML Parser V2 for Java, which includes JAXP 1.1, DOM, SAX and XSLT APIs. Message files for XML Parser. 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 xsu111.jar	XML SQL Utility for JDK 1.2 and above XML SQL Utility for JDK 1.1.1
XSQL Servlet	oraclesql.jar xsqlserializers.jar classgen.jar transx.zip	Oracle XSQL Servlet Oracle XSQL Serializers for FOP/PDF Integration XML Class Generator for Java Oracle TransX Utility

In addition, XML SQL Utility, XSQL Servlet and TransX Utility all depend on JDBC, which is listed in the following table:

Table 2-2 XDK Libraries for Java

Component	Library	Notes
JDBC	classes12.zip classes111.zip	JDBC for JDK 1.2 and above JDBC for JDK 1.1.8
Globalization	nls_charset12.jar nls_charset111.jar	Globalization support for JDK 1.2 and above Globalization support for JDK 1.1.8

Component

Library

Notes

JDBC

classes12.zip

classes111.zip

JDBC for JDK 1.2 and above

JDBC for JDK 1.1.8

Globalization

nls_charset12.jar

nls_charset111.jar

Globalization support for JDK 1.2 and above

Globalization support for JDK 1.1.8

Environment Settings for XDK for Java

These files will set up the environment:

UNIX: $XDK_HOME/bin/env.csh

NT: $XDK_HOME/bin/env.bat

The following tables list the environment variables, with the ones that must be customized marked with "Y":

Table 2-3 NT Environment Settings

Variable	Notes	Y/N
%JDBCVER%	Directory where the Java^TM 2 SDK, Standard Edition, version 1.3.1 is installed	Y
%JDKVER%	Include the following: .;%XDK_HOME%\lib\xmmlparserv2.jar;%XDK_HOME%\lib\xsu12.jar;	Y
%INSTALL_ROOT%	Installation root of XDK which is the directory we refer to as %XDK_HOME%.	N
%JAVA_HOME%	JAVA_HOME=C:\JDK%JDKVER%	Y
%CLASSPATHJ%	CLASSPATHJ=%ORACLE_HOME%\jdbc\lib\classes%JDBCVER%.zip; %ORACLE_HOME%\jdbc\lib\nls_charset%JDBCVER%.jar	Y
%PATH%	PATH=%JAVA_HOME%\bin;%ORACLE_HOME%\bin;%PATH%;%INSTALL_ROOT%\bin	N
%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	N

The following table shows the UNIX environment variables (the ones that must be customized are marked with "Y"):

Table 2-4 UNIX Environment Settings

Variable	Notes	Y/N
$JDBCVER	JDBC Version. If using JDK 1.2 and above, it should be set to 12. If using JDK 1.1.8, it should be set to 111	Y
$JDKVER	JDK Version which you can get from: Java -version For example, the default value is: 1.2.2_07	Y
$INSTALL_ROOT	Installation root of XDK, which is the directory referred to as $XDK_HOME.	N
$JAVA_HOME	Directory where the Java SDK, Standard Edition is installed.	Y
$CLASSPATHJ	Path linked to the Java SDK needs to be modified. ${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 then where the Oracle RDBMS is installed, you will have to update CLASSPATHJ path with the correct locations of the JDBC library (classes12.jar). The nls_charset12.jar is needed to support certain character sets. Refer to Globalization setup with XDK for Java Note that if you don't have these libraries on your system, these are both available on OTN (http://otn.oracle.com) -- part of JDBC driver download	Y
$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	N
$PATH	${JAVA_HOME}/bin:${PATH}:${INSTALL_ROOT}/bin	N
$LD_LIBRARY_PATH	For OCI JDBC connections. ${ORACLE_HOME}/lib:${LD_LIBRARY_PATH}	N

XSU Setup

XSU installation is discussed in "Installation of XDK for PL/SQL".

XSQL Servlet Setup

The XSQL Servlet is designed to run on any Java VM, using any JDBC driver, against any database. In practice, we are able to test it against only the most popular configurations; we document the supported configurations that have been tested in the Oracle labs.

XSQL Pages and XSQL Servlet have been successfully tested only with:

JDK 1.1.8
JDK 1.2.2
JDK 1.3

These are the only three JDK versions that we know work correctly.

Note:

Numerous users have reported problems using XSQL Pages and XSQL Servlet with JDK 1.1.7. These problems are in the character set conversion routines for UTF-8 and make JDK 1.1.7 unusable for processing XSQL Pages.

Supported Servlet Engines

This XSQL Servlet has been tested with the following servlet engines:

Oracle9iAS Apache/JServ Servlet Engine
Oracle9iAS OC4J Servlet Engine
Allaire JRun 2.3.3 and 3.0.0
Apache 1.3.9 with JServ 1.0 and 1.1
Apache 1.3.9 with Tomcat 3.1 or 3.2 Servlet Engine
Apache Tomcat 3.1 or 3.2 Web Server + Servlet Engine
Caucho Resin 1.1
Java Web Server 2.0
Weblogic 5.1 Web Server
NewAtlanta ServletExec 2.2 and 3.0 for IIS/PWS 4.0
Oracle8i Lite Web-to-Go Server
Oracle8i 8.1.7 Oracle Servlet Engine
Sun JavaServer Web Development Kit (JSWDK) 1.0.1 Web Server

Supported JSP Implementations

JavaServer Pages can use <jsp:forward> and/or <jsp:include> to collaborate with XSQL Pages as part of an application. The following JSP platforms have been tested:

Oracle9iAS Apache/JServ Servlet Engine
Oracle9iAS OC4J Servlet Engine
Apache 1.3.9 with Tomcat 3.1 or 3.2 Servlet Engine
Apache Tomcat 3.1 or 3.2 Web Server + Tomcat 3.1 or 3.2 Servlet Engine
Caucho Resin 1.1 (Built-in JSP 1.0 Support)
NewAtlanta ServletExec 2.2 and 3.0 for IIS/PWS 4.0 (Built-in JSP 1.0 Support)
Oracle8i Lite Web-to-Go Server with Oracle JSP 1.0
Oracle8i 8.1.7 Oracle Servlet Engine
Any Servlet Engine with Servlet API 2.1+ and Oracle JSP 1.0

In general, it should work with any servlet engine supporting the Servlet 2.1 Specification or higher, and the Oracle JSP 1.0 reference implementation or functional equivalent from another vendor.

JDBC Drivers and Databases

The Oracle XSQL Page processor has been designed to exploit the maximum set of features against the Oracle JDBC drivers, but gracefully works against any database with a reasonable JDBC driver. While numerous users have reported successfully using XSQL Pages with many other JDBC drivers, the ones that we have tested in-house are:

Oracle8i 8.1.5 Driver for JDBC 1.x
Oracle8i 8.1.6 Driver for JDBC 1.x
Oracle8i 8.1.7 Driver for JDBC 1.x
Oracle8i Lite 4.0 Driver for JDBC 1.x
Oracle8i 8.1.6 Driver for JDBC 2.0
Oracle8i 8.1.7 Driver for JDBC 2.0
Oracle9i 9.0.1 Driver for JDBC 2.0

Setting Up the Database Connection Definitions for Your Environment

The demos are set up to use the SCOTT schema on a database on your local machine (the machine where the web server is running). If you are running a local database and have a SCOTT account whose password is TIGER, then you are all set. Otherwise, you need to edit the .\xdk\admin\XSQLConfig.xml file to correspond to your appropriate values for username, password, dburl, and driver values for the connection named demo:

<?xml version="1.0" ?>
<XSQLConfig>
     :
  <connectiondefs>
    <connection name="demo">
      <username>scott</username>
      <password>tiger</password>
      <dburl>jdbc:oracle:thin:@localhost:1521:ORCL</dburl>
      <driver>oracle.jdbc.driver.OracleDriver</driver>
    </connection>
    <connection name="lite">
      <username>system</username>
      <password>manager</password>
      <dburl>jdbc:Polite:POlite</dburl>
      <driver>oracle.lite.poljdbc.POLJDBCDriver</driver>
    </connection>
  </connectiondefs>
      :
</XSQLConfig>

Setting Up Your Servlet Engine to Run XSQL Pages

UNIX users and any user wanting to install the XSQL Servlet on other Web servers should continue with the instructions below depending on the Web server you're trying to use. In every case, there are these basic steps:

Include the list of XSQL Java archives:
- xsu12.jar - Oracle XML SQL Utility
- xmlparserv2.jar - Oracle XML Parser for Java V2
- oraclexsql.jar- Oracle XSQL Pages
- xsqlserializers.jar - Oracle XSQL Serializers for FOP/PDF Integration
- classes12.jar - Oracle JDBC Driver or the JAR file for the JDBC driver you will be using instead
- Include as well as the directory where XSQLConfig.xml resides (by default ./xdk/admin) in the server CLASSPATH.
Map the .xsql file extension to the oracle.xml.xsql.XSQLServlet servlet class.
Map a virtual directory /xsql to the directory where you extracted the XSQL files (to access the online help and demos).

Oracle Internet Application Server

Oracle IAS release 1.0 and higher comes preconfigured to run XSQL Servlet. By default its Apache JServ servlet engine contains all of the wrapper.classpath entries in jserv.conf to include the necessary Java archives to run XSQL. The XSQLConfig.xml file is found in the ./xdk/admin subdirectory of the IAS installation home.

Oracle 9iAS Oracle Containers for Java (OC4J) Servlet Container

The easiest way to install XSQL Servlet in the Oracle9iAS OC4J servlet container is to install it as a global application. Assuming your OC4J installation home is C:\j2ee\home, and that you've extracted the XDK distribution into the C:\xdk902 directory, here are the setup steps:

Verify that the following JAR files are already in your C:\j2ee\home\lib directory (they should come pre-installed):
- xmlparserv2.jar - Oracle XML Parser for Java V2
- classes12.jar - Oracle JDBC Driver
Copy the following additional JAR files from C:\xdk902\lib to C:\j2ee\home\lib.
- xsu12.jar - Oracle XML SQL Utility
- oraclexsql.jar - Oracle XSQL Pages
- xsqlserializers.jar - Oracle XSQL Serializers for FOP/PDF Integration
Copy the C:\xdk\admin\XSQLConfig.xml configuration file to the C:\j2ee\home\default-web-app\WEB-INF\classes directory.

Edit the C:\j2ee\home\config\global-web-application.xml server configuration file to add a <servlet> and <servlet-mapping> entry as child elements of the <web-app> element as follows:

<orion-web-app ...and so on... >
  :
 etc
  :
  <web-app>
    <servlet>
      <servlet-name>xsql</servlet-name>
      <servlet-class>oracle.xml.xsql.XSQLServlet</servlet-class>
    </servlet>
    <servlet-mapping>
      <servlet-name>xsql</servlet-name>
      <url-pattern>/*.xsql</url-pattern>
    </servlet-mapping>
     :
    etc
     :
  </web-app>
</web-app>

At this point, you can refer to any XSQL page in any virtual path and it will be processed by the XSQL Servlet. If you want to try the XSQL built-in samples, demos, and online help, then you need to perform the following additional step to map a virtual path of /xsql/ to the C:\xdk\demo\java\xsql directory.

Edit the file:

c:\j2ee\home\application-deployments\default\defaultWebApp\orion-web.xml

to add the following <virtual-directory> entry:

<orion-web-app ...and so on...>
    :
   etc
    :
   <virtual-directory
   virtual-path="/xsql"
   real-path="/c:/xdk/xdk/demo/java/xsql/" />
    :
   etc
    :
</orion-web-app>

Then, you can browse the demos using the URL:

 http://yoursever:yourport/xsql/index.html

Apache JServ 1.0 or 1.1

Setup the server CLASSPATH correctly for the XSQL Servlet. This is done by editing the JServ configuration file named jserv.properties. Assuming you installed the XSQL Servlet files into C:\, you need to add the following entries to use the Oracle JDBC 1.x Driver:

# Oracle XML SQL Utility (XSU)
wrapper.classpath=C:\xdk902\lib\xsu111.jar
# Oracle XSQL Servlet
wrapper.classpath=C:\xdk902\lib\oraclexsql.jar
# Oracle JDBC (8.1.6) -- JDBC 1.x driver
wrapper.classpath=directory_where_JDBC_Driver_resides\classes111.zip
# Oracle XML Parser V2 (with XSLT Engine)
wrapper.classpath=C:\xdk902\lib\xmlparserv2.jar
# XSQLConfig.xml File location
wrapper.classpath=directory_where_XSQLConfig.xml_resides
# FOR Apache FOP Generation, Add
# wrapper.classpath=C:\xdk902\lib\xsqlserializers.jar
# wrapper.classpath=FOPHOME/fop.jar
# wrapper.classpath=FOPHOME/lib/batik.jar

To use the Oracle JDBC 2.0 Driver, the list looks like:

# Oracle XML SQL Utility (XSU)
wrapper.classpath=C:\xdk902\lib\xsu12.jar
# Oracle XSQL Servlet
wrapper.classpath=C:\xdk902\lib\oraclexsql.jar
# Oracle JDBC (8.1.6) -- JDBC 2.0 driver
wrapper.classpath=directory_where_JDBC_Driver_resides\classes12.zip
# Oracle XML Parser V2 (with XSLT Engine)
wrapper.classpath=C:\xdk902\lib\xmlparserv2.jar
# XSQLConfig.xml File location
wrapper.classpath=directory_where_XSQLConfig.xml_resides
# FOR Apache FOP Generation, Add
# wrapper.classpath=C:\xdk902\lib\xsqlserializers.jar
# wrapper.classpath=FOPHOME/fop.jar
# wrapper.classpath=FOPHOME/lib/w3c.jar

Map the .xsql file extension to the XSQL Servlet

To do this, you need to edit the JServ configuration file named jserv.conf (in JServ 1.0 this was named mod_jserv.conf on some platforms). Add the following lines:

# Executes a servlet passing filename with proper extension in PATH_TRANSLATED 
# property of servlet request.
# Syntax: ApJServAction [extension] [servlet-uri]
# Defaults: NONE

ApJServAction .xsql /servlets/oracle.xml.xsql.XSQLServlet

Map an /xsql/ virtual directory

In this step, we want to map the virtual path \xsql\ to C:\xdk902\xdk\demo\java\xsql\ (or wherever you installed the XSQL Servlet files). To do this, you need to edit the Apache configuration file named httpd.conf and add the following line:

Alias /xsql/ "C:\xdk902\xdk\demo\java\xsql\"

Restart the Apache server and browse the URL:

http://localhost/xsql/index.html

Jakarta Tomcat 3.1 or 3.2

Set up the Server CLASSPATH for the XSQL Servlet

This is done by editing the Tomcat startup script named tomcat.bat in ./jakarta-tomcat/bin and adding five lines to append the appropriate entries onto the system CLASSPATH before the Tomcat server is started as shown below:

For Oracle JDBC 1.x Driver:

rem Set up the CLASSPATH that we need

set cp=%CLASSPATH%

set CLASSPATH=.
set CLASSPATH=%TOMCAT_HOME%\classes
set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\webserver.jar
set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\jasper.jar
set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\xml.jar
set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\servlet.jar
set CLASSPATH=%CLASSPATH%;%JAVA_HOME%\lib\tools.jar

REM Added for Oracle XSQL Servlet
REM -----------------------------
set CLASSPATH=%CLASSPATH%;C:\xdk902\lib\xsu111.jar
set CLASSPATH=%CLASSPATH%;C:\xdk902\lib\oraclexsql.jar
set CLASSPATH=%CLASSPATH%;C:\xdk902\lib\xmlparserv2.jar
set CLASSPATH=%CLASSPATH%;directory_where_JDBC_Driver_resides\classes111.zip
set CLASSPATH=%CLASSPATH%;directory_where_XSQLConfig.xml_resides
REM FOR Apache FOP Generation, Add
REM set CLASSPATH=%CLASSPATH%;C:\xdk902\lib\xsqlserializers.jar
REM set CLASSPATH=%CLASSPATH%;FOPHOME/fop.jar
REM set CLASSPATH=%CLASSPATH%;FOPHOME/lib/batik.jar

For Oracle JDBC 2.0 Driver:

rem Set up the CLASSPATH that we need

set cp=%CLASSPATH%

set CLASSPATH=.
set CLASSPATH=%TOMCAT_HOME%\classes
set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\webserver.jar
set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\jasper.jar
set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\xml.jar
set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\servlet.jar
set CLASSPATH=%CLASSPATH%;%JAVA_HOME%\lib\tools.jar

REM Added for Oracle XSQL Servlet
REM -----------------------------
set CLASSPATH=%CLASSPATH%;C:\xdk902\lib\xsu12.jar
set CLASSPATH=%CLASSPATH%;C:\xdk902\lib\oraclexsql.jar
set CLASSPATH=%CLASSPATH%;C:\xdk902\lib\xmlparserv2.jar
set CLASSPATH=%CLASSPATH%;directory_where_JDBC_Driver_resides\classes12.zip
set CLASSPATH=%CLASSPATH%;directory_where_XSQLConfig.xml_resides
REM FOR Apache FOP Generation, Add
REM set CLASSPATH=%CLASSPATH%;C:\xdk902\lib\xsqlserializers.jar
REM set CLASSPATH=%CLASSPATH%;FOPHOME/fop.jar
REM set CLASSPATH=%CLASSPATH%;FOPHOME/lib/batik.jar

Map the .xsql File Extension to the XSQL Servlet

Tomcat supports creating any number of configuration contexts to better organize the web applications your site needs to support. Each context is mapped to a virtual directory path, and has its own separate servlet configuration information. XSQL Servlet comes with a preconfigured context file to make XSQL Servlet setup easier.

By default, Tomcat 3.1 and 3.2 come preconfigured with the following contexts (defined by <Context> entries in the ./jakarta-tomcat/conf/server.xml file).

The root context
/examples
/test
/admin

We could install XSQL Servlet into one of these, but for simplicity we'll create a new context just for the XSQL Servlet that maps to the directory where you installed the XSQL Servlet distribution.

Edit the ./jakarta-tomcat/conf/server.xml file to add the following <Context> entry with path= "/xsql".

<Context path="/test" docBase="webapps/test" debug="0" reloadable="true" /> 

<!--
 |  Define a Servlet context for the XSQL Servlet  
 |  
 |  The XSQL Servlet ships with a .\WEB-INF directory
 |  with its web.xml file preconfigured for C:\xdk902\xdk\demo\java\xsql
 |  installation.
 +-->
<Context path="/xsql" docBase="C:\xdk902\xdk\demo\java\xsql"/>

Note that the docBase= "C:\xsql" points to the physical directory where you installed the XSQL Servlet distribution. You then need to create a WEB-INF subdirectory in the C:\xdk902\xdk\demo\java\xsql directory and save the following ./WEB-INF/web.xml file in it:

<?xml version = '1.0' encoding = 'UTF-8'?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 
2.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
<web-app>
   <servlet>
      <servlet-name>oracle-xsql-servlet</servlet-name>
      <servlet-class>oracle.xml.xsql.XSQLServlet</servlet-class>
   </servlet>
    <servlet-mapping>
      <servlet-name>oracle-xsql-servlet</servlet-name>
      <url-pattern> *.xsql </url-pattern>
   </servlet-mapping>
</web-app>

Note:

To add the XSQL Servlet to an existing context, add the servlet and servlet-mapping entries that you find in the web.xml file preceding, into the web.xml file for the context in question.

Map an /xsql/ Virtual Directory

This is already achieved by creating the /xsql context preceding.

Restart the Tomcat server and browse the URL:

http://localhost:8080/xsql/index.html

If you use Tomcat with an XML Parser (such as the Sun Crimson Parser) that only supports DOM Level 1 interfaces, then you must edit tomcat.bat to insure that the Oracle XML Parser's archive xmlparser.jar comes before the DOM Level 1 parser's archive in the CLASSPATH. For example, you could edit tomcat.bat to add the following lines:

REM NEED TO PUT xmlparserv2.jar FIRST before parser.jar
set CP=C:\xdk902\lib\xmlparserv2.jar;%CP%

just before the lines:

echo Using CLASSPATH: %CP%
echo.
set CLASSPATH=%CP%

XDK for Java with Globalization Support

Here is a summary on the setting that related to Globalization Support.

Using xmlmesg.jar: If you are using the language other than English you would need to set the xmlmesg.jar into your CLASSPATH to let the parser get correct messages in your language.
Using nls_charset12.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 Dependencies

The following figure shows the dependencies of XDK when using JDK 1.2 and higher:

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

Text description of adxml110.gif follows

Text description of the illustration adxml110.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 4, "XML Parser for Java" for further discussion of the XDK for Java components

Installation of the XDK for JavaBeans

The XDK for JavaBeans permit easily adding visual or non-visual interfaces to XML applications. The bean encapsulation includes documentation and descriptors that can be accessed directly from Java Integrated Development Environments like JDeveloper.

Note:

The XDKs for Java and JavaBeans are now bundled together.

Oracle XDK for JavaBeans consists of the following components:

DOMBuilder Bean encapsulates the DOMParser and provides asynchronous XML document parsing.
TreeViewer Bean displays XML formatted files graphically as a tree. These branches and leaves of this tree can be manipulated with a mouse.
SourceViewer Bean displays XML and XSL formatted files with color syntax highlighting for easy viewing and editing.
Transformer Bean accepts an input XML document and applies the transformation specified by an input XSL stylesheet to create an output file.
TransPanel Bean encapsulates the preceding beans in an application component for retrieving, transforming, and viewing XML files.
DBAccess Bean can be used for programmatic access to all features that XMLTransformPanel offers in interactive mode with support of XMLType.
DBView Bean can be used in any application that requires visualization of database information using XML and stylesheet transformations.
XMLDiff Utility can be used to compare two XML files and represent the difference visually, or by the generated XSL code.
XMLCompression Utility: can used to serialize XML document in Compressed format.

XDK for JavaBeans comes with Oracle Database or iAS application server. You can also download the latest versions of XDK for JavaBeans from OTN.

If you installed XDK with Oracle Database or iAS application server, you can skip the following steps and direct to refer to the XDK home directory (we will refer to this directory as $XDK_HOME).

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

Use this URL in your browser:

http://otn.oracle.com/tech/xml/xdk_jbeans/index.html

Click on the Software icon at the left-hand side of the page.

Log in with your OTN username and password (registration is free if you don not already have an account).
Select the version you want to download.

Accept all the terms of the licensing agreement and download the software. Here are the instructions found on the download site for Solaris^TM Operating Environment:

Oracle XML Developer's Kit for Java on Sun Solaris^TM Operating Environment- 
9i 
Download the Complete File
xdk_java_9_0_2_0_0C.tar.gz

Directions 

      Install GNU gzip. 
      Download the Oracle XDK for JavaBeans in .tar format 
      Extract the distribution package into a directory. 

(Ex: #gzip -dc xdk_java.tar | tar xvf -)

The result should be the following files and directories:
/bin - xdk executables and utilities 
/lib - directory for libraries 
/xdk - top xdk directory 
/xdk/demo - directory for demo files 
/xdk/doc - directory for documentation 
/xdk/admin - direcory for dband config files 
/xdk/*html - doc navigation files 
/xdk/license.html - copy of license agreement

For Windows NT, choose a directory under which you would like the .\xdk directory and subdirectories to go (for example, \C: on NT), change the directory to \C: then extract the files using the WinZip visual tool.

XDK for JavaBeans Components

After installing the XDK, the directory structure is:

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

All the packages in XDK for JavaBeans are certified and supported with JDK 1.2 or 1.1.8, so make sure that your CLASSPATH includes all the necessary libraries.

For JDK versions lower that JDK 1.2, you will need to include the JDK library in your CLASSPATH, as well as the Swing library, swingall.jar at "Java Foundation Classes (JFC)/Swing 1.0.3" in page

http://java.sun.com/products/archive/index.html

The following table lists the libraries of XDK for JavaBeans:

Table 2-5 XDK for JavaBeans 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.
	xmlmesg.jar	Messages for XML Parser. 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 above
	xsu111.jar	XML SQL Utility for JDK 1.1.8
	oraclexsql.jar	Oracle XSQL Servlet
	xsqlserializers.jar	Oracle XSQL Serializers for FOP/PDF Integration
Class Generator	classgen.jar	Class Generator for Java
TransX Utility	transx.zip	Oracle TransX Utility
JavaBeans	xmlcomp.jar xmlcomp2.jar	Oracle JavaBeans Utilities

In addition, XML SQL Utility, XSQL Servlet and TransX Utility all depend on other components, whose libraries are listed in the following table:

Table 2-6 XDK for JavaBeans: Dependent Libraries

Component	Library	Notes
JDBC	classes12.zip	JDBC for JDK 1.2 and above
	classes111.zip	JDBC for JDK 1.1.8
Globalization	nls_charset12.jar	Globalization support for JDK 1.2 and above
	nls_charset111.jar	Globalization support for JDK 1.1.8
XMLType	xdb_g.jar	XMLType Java APIs. $ORACLE_HOME/rdbms/jlib
Jdev Runtime	jdev-rt.zip	Java GUI libraries

Setting Up the XDK for JavaBeans Environment

Use this script file provided on UNIX:

$XDK_HOME/bin/env.csh

For Windows, use this provided batch file:

%XDK_HOME/bin/env.bat

The following tables list the environment variables needed during XDK setup. Variables that must be customized before running the script or batch file are marked as "Y" in the column "Customize".

Table 2-7 JavaBeans Environment Settings for UNIX

Variable Name	Values	Customize
$JDBCVER	JDBC version. If using JDK 1.2 and above, set to 12.	Y
$JDKVER	JDK version (default is 1.2.2_07), obtained by: `Java -version`	Y
$INSTALL_ROOT	Installation root of XDK, the directory referred to as $XDK_HOME	N
$JAVA_HOME	Directory where the Java SDK, Standard Edition is installed. The path linked to the Java SDK must be modified.	Y
$CLASSPATHJ	${ORACLE_HOME}/jdbc/lib/classes${JDBCVER}.zip: ${ORACLE_HOME}/jdbc/lib/nls_charset${JDBCVER}.jar f you are running the XSU on a system other than where the Oracle RDBMS is installed, you will have to update CLASSPATHJ path with the correct locations of the JDBC library (classes12.jar). The nls_charset12.jar is needed to support certain character sets. Refer to Globalization Support setup with XDK for JavaBeans Note that if you do not have these libraries on your system, these are both available on OTN: (http://otn.oracle.com) which is part of the JDBC driver download.	Y
$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	N
$PATH	${JAVA_HOME}/bin:${PATH}:${INSTALL_ROOT}/bin	N
$LD_LIBRARY_PATH	For OCI JDBC connections. ${ORACLE_HOME}/lib:${LD_LIBRARY_PATH}	N

For Windows NT see the following table for the settings:

Table 2-8 JavaBeans Environment Settings for Windows NT

Variable Name	Values	Customize
%JDBCVER%	DBC Version. If using JDK 1.2 and above, it is 12. If using JDK 1.1.8, it is 111.	Y
%JDKVER%	JDK version (default is 1.2.2_07), obtained by: `Java -version`	Y
%INSTALL_ROOT%	Installation root of XDK, which is the directory referred to as %XDK_HOME%	N
%JAVA_HOME%	Directory where the Java SDK, Standard Edition, is installed. The path linked to the Java SDK must be modified.	Y
%CLASSPATHJ%	CLASSPATHJ=%ORACLE_HOME%\jdbc\lib\classes%JDBCVER%.zip; %ORACLE_HOME%\jdbc\lib\nls_charset%JDBCVER%.jar	Y
%PATH%	PATH=%JAVA_HOME%\bin;%ORACLE_HOME%\bin;%PATH%;%INSTALL_ROOT%\bin	N
%CLASSPATH%	.;%CLASSPATH%;%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	N

XDK for JavaBeans with Globalization Support

Here is a summary of the settings that are related to Globalization Support.

If you use languages other than English, set the xmlmesg.jar into your Java CLASSPATH to let the parser obtain the correct messages in your language.
If you use a multibyte character set other than one of the following,
- UTF-8
- ISO8859-1
- JA16SJIS
then set nls_charset12.jar into your Java CLASSPATH so that JDBC can convert the character set of the input file to the database character set during loading of XML files.

See Also:
Chapter 10, "XDK JavaBeans" for further discussion of the XDK for JavaBeans components

2 Getting Started with XDK for Java and JavaBeans

Installation of the XDK for Java

Installation Steps for XDK for Java

What Are the XDK for Java Components?

Table 2-1 XDK for Java Libraries

Table 2-2 XDK Libraries for Java

Environment Settings for XDK for Java

Table 2-3 NT Environment Settings

Table 2-4 UNIX Environment Settings

XSU Setup

XSQL Servlet Setup

Supported Servlet Engines

Supported JSP Implementations

JDBC Drivers and Databases

Setting Up the Database Connection Definitions for Your Environment

Setting Up Your Servlet Engine to Run XSQL Pages

Oracle Internet Application Server

Oracle 9iAS Oracle Containers for Java (OC4J) Servlet Container

Apache JServ 1.0 or 1.1

Map the .xsql file extension to the XSQL Servlet

Map an /xsql/ virtual directory

Jakarta Tomcat 3.1 or 3.2

Set up the Server CLASSPATH for the XSQL Servlet

Map the .xsql File Extension to the XSQL Servlet

Map an /xsql/ Virtual Directory

XDK for Java with Globalization Support

XDK Dependencies

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

Installation of the XDK for JavaBeans

XDK for JavaBeans Components

Table 2-5 XDK for JavaBeans Libraries

Table 2-6 XDK for JavaBeans: Dependent Libraries

Setting Up the XDK for JavaBeans Environment

Table 2-7 JavaBeans Environment Settings for UNIX

Table 2-8 JavaBeans Environment Settings for Windows NT

XDK for JavaBeans with Globalization Support

2
Getting Started with XDK for Java and JavaBeans