2 Getting Started with XDK Java Components

Oracle Application Server (OracleAS)

OracleAS 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.

OracleAS Oracle Containers for Java (OC4J) Servlet Container

The easiest way to install XSQL Servlet in the OracleAS OC4J servlet container is to install it as an application. Assuming your OC4J installation home is C:\j2ee\home, and that you have extracted the XDK distribution into the C:\xdk directory, here are the setup steps:

1. 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

2. Copy the following additional JAR files from C:\xdk\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

3. Copy the C:\xdk\admin\XSQLConfig.xml configuration file to the C:\j2ee\home\default-web-app\WEB-INF\classes directory.

4. 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 is 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.

1. Edit the file:

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

2. 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.101/xsql/" />
       ...
      etc
       ...
   </orion-web-app>
   
   

3. Then, you can browse the demos using the URL:

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

Apache/JServ 1.0 or 1.1

1. Set up the server CLASSPATH correctly for the XSQL Servlet. This is done by editing the JServ configuration file named jserv.properties.

2. Assuming that 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
   
   

3. To use the Oracle JDBC 2.0 Driver, the entries are:

   # 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
   
   

4. 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
   
   

5. 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\"
   
   

6. Restart the Apache server and browse the URL:

   http://localhost/xsql/index.html
   

Jakarta Tomcat 3.1 or 3.2

Do the following steps:

1. 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 the appropriate entries onto the system CLASSPATH before the Tomcat server is started.

   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
   
   

2. Map the .xsql File Extension to the XSQL Servlet:

   Tomcat supports creating any number of configuration contexts to better organize the Web applications that 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 file./jakarta-tomcat/conf/server.xml).

   The root context

   /examples

   /test

   /admin

   Install XSQL Servlet into one of these, but for simplicity 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.

   
   

3. Map an /xsql Virtual Directory:

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

   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%