A
XDK for Java: Specifications and Quick References

This appendix describes the XDK for Java specifications and quick references for each XML component for Java. The quick references list the main APIs, classes, and associated methods for each XDK for Java component.

This appendix contains the following sections:

• XML Parser for Java Quick Reference
• XML Parser for Java Specifications
• XDK for Java: XML Schema Processor
• XDK for Java: XML Class Generator for Java
• XDK for Java: XSQL Servlet
• XSQL Servlet Specifications

XML Parser for Java Quick Reference

XML Parser for Java Specifications

The Oracle XML Parser for Java, Version 2 specifications follow:

• New high performance architecture
• Integrated support for W3C XSLT 1.0 Recommendation
• Supports validation and non-validation modes
• Built-in Error Recovery until fatal error
• Integrated Document Object Model (DOM) Level 1.0 and 2.0 API
• Integrated SAX 1.0 and 2.0 API
• Supports W3C Recommendation for XML Namespaces

Requirements

Operating Systems: Any with Java 1.1.x support

JAVA: JDK 1.1.x. or later.

The contents of both the Windows and UNIX versions are identical. They are simply archived differently for operating system compatibility and your convenience.

Online Documentation

Documentation for Oracle XML Parser for Java is located in the doc/ directory in your install area.

Release Specific Notes

The readme.html file in the root directory of the archive contains release specific information including bug fixes, API additions, and so on.

Oracle XML Parser is an early adopter release and is written in Java. It will check if an XML document is well-formed and, optionally, if it is valid. The parser will construct a Java object tree which can be accessed. It also contains an integrated XSLT processor for transforming XML documents.

Standards Conformance

The parser conforms to the following W3C Recommendations:

• Extensible Markup Language (XML) 1.0 http://www.w3.org/TR/1998/REC-xml-19980210
• Namespaces in XML at http://www.w3.org/TR/REC-xml-names/
• Document Object Model Level 1 1.0 http://www.w3.org/TR/REC-DOM-Level-1/
• Document Object Model Level 2 http://www.w3.org/TR/DOM-Level-2-Core/
• XML Path Language (XPath) 1.0 http://www.w3.org/TR/1999/REC-xpath-19991116
• XML Transformations (XSLT) 1.0 http://www.w3.org/TR/1999/REC-xslt-19991116

The parser also conforms to the following W3C Proposed Recommendations:

• XML Schema Part 1: Structures http://www.w3.org/TR/xmlschema-1
• XML Schema Part 2: Datatypes http://www.w3.org/TR/xmlschema-2

In addition, the parser implements the following interfaces defined by the XML development community:

• Simple API for XML (SAX) 1.0 and 2.0 at http://www.megginson.com/SAX/index.html

Supported Character Set Encodings

The XML Parser for Java (and the XSQL Servlet) currently support:

Default:

UTF-8 is the default encoding if none is specified. Any other ASCII or EBCDIC based encodings that are supported by the JDK may be used.However, they must be specified in the format required by the JDK instead of as official character set names defined by IANA.

Error Recovery

The parser also provides error recovery. It will recover from most errors and continue processing until a fatal error is encountered.

XDK for Java: XML Schema Processor

XDK for Java: XML Class Generator for Java

Oracle XML Class Generator for Java requires Oracle XML Parser for Java. The XML Document, printed by the generated classes, confirms to the W3C recommendation for Extensible Markup Language (XML) 1.0. Oracle XML Class Generator can optionally generate validating Java source files. It also optionally generates Javadoc comments in the source files.

Oracle XML Class Generator supports the following encodings for printing the XMLDocument:

UTF-8, UTF-16, ISO-10646-UCS-2, ISO-10646-UCS-4, US-ASCII, EBCDIC-CP-US, ISO-8859-1, and Shift_SJIS.

ASCII is the default encoding if none is specified. Any other ASCII or EBCDIC based encodings that are supported by the JDK can be used.

XDK for Java: XSQL Servlet

Downloading and Installing XSQL Servlet

Downloading XSQL Servlet from OTN

You can download XSQL Servlet distribution from:

http://otn.oracle.com/tech/xml/xsql_servlet

1. Click the 'Software' icon at the top of the page:
2. Log in with your OTN username and password (registration is free if you do not already have an account).
3. Selecting whether you want the NT or Unix download (both contain the same files)
4. Acknowledge the licensing agreement and download survey
5. Clicking on xsqlservlet_v1.0.2.0.tar.gz or xsqlservlet_v1.0.2.0.zip

Extracting the Files in the Distribution

To extract the contents of XSQL Servlet distribution, do the following:

1. Choose a directory under which you would like the .\xsql directory and subdirectories to go, for example, C:\
2. Change directory to C:\, then extract the XSQL downloaded archive file there. For example:

   UNIX:

       tar xvfz xsqlservlet_v1.0.2.0.tar.gz
   
   

   Windows NT:

       pkzip25 -extract -directories xsqlservlet_v1.0.2.0.zip
   
   

   using the pkzip25 command-line tool or the WinZip visual archive extraction tool.

Windows NT: Starting the Web-to-Go Server

XSQL Servlet comes bundled with the Oracle Web-to-go server that is pre-configured to use XSQL Pages. The Web-to-go web server is a single-user server, supporting the Servlet 2.1 API, used for mobile application deployment and for development. This is a great way to try XSQL Pages out on your Windows machine before delving into the details of configuring another Servlet Engine to run XSQL Pages.

Windows NT users can get started quickly with XSQL Pages by following these steps:

1. Running the xsql-wtg.bat script in the .\xsql directory.
2. Browsing the URL http://localhost:7070/xsql/index.html

If you get an error starting this script, edit the xsql-wtg.bat file to properly set the two environment variables JAVA and XSQL_HOME to appropriate values for your machine.

    REM ----------------------------------------------
    REM Set the 'JAVA' variable equal to the full path
    REM of your Java executable.
    REM ----------------------------------------------
    set JAVA=J:\java1.2\jre\bin\java.exe
    set XSQL_HOME=C:\xsql
    REM ----------------------------------------------
    REM Set the 'XSQL_HOME' variable equal to the full
    REM path of where you install the XSQL Servlet 
    REM distribution.
    REM ----------------------------------------------

Then, repeat the two preceding steps.

If you get an error connecting to the database when you try the demos, you'll need to go on to the next section, then try the preceding steps again after setting up your database connection information correctly in the XSQLConfig.xml file.

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 (that is, 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 .\xsql\lib\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>

UNIX: 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 3 basic steps:

1. Include the list of XSQL Java archives as well as the directory where XSQLConfig.xml resides (by default ./xsql/lib) in the server CLASSPATH.

   Note: For convenience, the xsqlservlet_v1.0.2.0.tar.gz and xsqlservlet_v1.0.2.0.zip distributions include the .jar files for the Oracle XML Parser for Java (V2), the Oracle XML SQL Utilities for Java, and the 8.1.6 JDBC driver in the .\lib subdirectory, along with Oracle XSQL Pages' own .jar archive.

2. Map the .xsql file extension to the oracle.xml.xsql.XSQLServlet servlet class
3. Map a virtual directory /xsql to the directory where you extracted the XSQL files (to access the on-line help and demos)

XSQL Servlet Specifications

The following lists the XSQL servlet specifications:

• Produce dynamic XML documents based on one or more SQL queries
• Optionally transforms the resulting XML document in the server or client using XSLT
• Supports W3C XML 1.0 Recommendation
• Supports Document Object Model (DOM) Level 1.0 and 2.0 API
• Support the W3C XSLT 1.0 Recommendation
• Supports W3C Recommendation for XML Namespaces