20
Writing Oracle XML DB Applications in Java

This chapter describes how to write Oracle XMl DB applications in Java. It includes design guidelines for writing Java applications including servlets, and how to configure the Oracle XML DB servlets.

It contains these sections:

• Introducing Oracle XML DB Java Applications
• Design Guidelines: Java Inside or Outside the Database?
• Writing Oracle XML DB HTTP Servlets in Java
• Configuring Oracle XML DB Servlets
• HTTP Request Processing for Oracle XML DB Servlets
• The Session Pool and XML DB Servlets
• Native XML Stream Support
• Oracle XML DB Servlet APIs
• Oracle XML DB Servlet Example

Introducing Oracle XML DB Java Applications

Oracle XML DB provides two main architectures for the Java programmer:

• In the database using the Java Virtual Machine (VM)
• In a client or application server, using the Thick JDBC driver

Because Java in the database runs in the context of the database server process, the methods of deploying your Java code are restricted to one of the following ways:

• You can run Java code as a stored procedure invoked from SQL or PL/SQL or
• You can run a Java servlet.

Stored procedures are easier to integrate with SQL and PL/SQL code, and require using Oracle Net Services as the protocol to access Oracle9i database.

Servlets work better as the top level entry point into Oracle9i database, and require using HTTP as the protocol to access Oracle9i database.

Which Oracle XML DB APIs Are Available Inside and Outside the Database?

In this release, some of Oracle XML DB APIs are only available to applications running in the server. Table 20-1 illustrates which Oracle XML DB APIs are available in each architecture in this release. The "NO" fields will become "YES" in a forthcoming release.

Oracle XML DB APIs AVailable Inside and Outside Oracle9i Database

Table 20-1 Oracle XML DB APIs Inside and Outside Oracle9i Database

Java Oracle XML DB APIs Description	Inside the Database:Java Servlets/Stored Procedures	Outside the Database: Using Thick JDBC (OCI) Drivers
JDBC support for XMLType	YES	YES
XMLType class	YES	YES
Java DOM implementation	YES	YES

Design Guidelines: Java Inside or Outside the Database?

When choosing an architecture for writing Java Oracle XML DB applications, consider the following guidelines:

HTTP: Accessing Java Servlets or Directly Accessing XMLType Resources

If the downstream client wants to deal with XML in its textual representation, using HTTP to either access the Java servlets or directly access XMLType resources, will perform the best, especially if the XML node tree is not being manipulated much by the Java program.

The Java implementation in the server can natively move data from the database to the network without converting character data through UCS-2 Unicode (which is required by Java strings), and in many cases copies data directly from the database buffer cache to the HTTP connection. There is no need to convert data from the buffer cache into the SQL serialization format used by Oracle Net Services, move it to the JDBC client, and then convert to XML. The load-on-demand and LRU cache for XMLType are most effective inside the database server.

Accessing Many XMLType Object Elements: Use JDBC XMLType Support

If the downstream client is an application that will programmatically access many or most of the elements of an XMLType object using Java, using JDBC XMLType support will probably perform the best. It is often easier to debug Java programs outside of the database server, as well.

Use the Servlets to Manipulate and Write Out Data Quickly as XML

Oracle XML DB servlets are intended for writing "HTTP stored procedures" in Java that can be accessed using HTTP. They are not intended as a platform for developing an entire Internet application. In that case, the application servlet should be deployed in Oracle9iAS application server and access data in the database either using JDBC, or by using the java.net.* or similar APIs to get XML data through HTTP.

They are best used for applications that want to get into the database, manipulate the data, and write it out quickly as XML, not to format HTML pages for end-users.

Writing Oracle XML DB HTTP Servlets in Java

Oracle XML DB provides a Protocol Server that supports FTP, HTTP 1.1, WebDAV, and Java Servlets. The support for Java Servlets in this release is not complete, and provides a subset designed for easy migration to full compliance in a following release. Currently, Oracle XML DB supports Java Servlet version 2.2, with the following exceptions:

• The Servlet WAR file (web.xml) is not supported in its entirety. Some web.xml configuration parameters must be handled manually. For example, creating roles must be done using the SQL CREATE ROLE command.
• RequestDispatcher and associated methods are not supported.
• HTTPServletRequest.getCookies() method is not supported.
• Only one ServletContext (and one web-app) is currently supported.
• Stateful servlets (and thus the HttpSession class methods) are not supported. Servlets must maintain state in the database itself.

Configuring Oracle XML DB Servlets

Oracle XML DB servlets are configured using the /xdbconfig.xml file in the Repository. Many of the XML elements in this file are the same as those defined by the Java Servlet 2.2 specification portion of Java 2 Enterprise Edition (J2EE), and have the same semantics. Table 20-2 lists the XML elements defined for the servlet deployment descriptor by the Java Servlet specification, along with extension elements supported by Oracle XML DB.

Table 20-2 XML Elements Defined for Servlet Deployment Descriptors  

XML Element Name	Defined By	Supported?	Description	Comment
auth-method	Java	no	Specifies an HTTP authentication method required for access	--
charset	Oracle	yes	Specifies a IANA character set name	For example: "ISO8859", "UTF8"
charset-mapping	Oracle	yes	Specifies a mapping between a filename extension and a charset	--
context-param	Java	no	Specifies a parameter for a web application	Not yet supported
description	Java	yes	A string for describing a servlet or Web application	Supported for servlets
display-name	Java	yes	A string to display with a servlet or web app	Supported for servlets
distributable	Java	no	Indicates whether or not this servlet can function if all instances are not running in the same Java virtual machine	All servlets running in the Oracle9i database MUST be distributable.
errnum	Oracle	yes	Oracle error number	See Oracle9i Database Error Messages
error-code	Java	yes	HTTP error code	Defined by RFC 2616
error-page	Java	yes	Defines a URL to redirect to if an error is encountered.	Can be specified through an HTTP error, an uncaught Java exception, or through an uncaught Oracle error message
exception-type	Java	yes	Classname of a Java exception mapped to an error page	--
extension	Java	yes	A filename extension used to associate with MIME types, character sets, and so on.	--
facility	Oracle	yes	Oracle facility code for mapping error pages	For example: "ORA", "PLS", and so on.
form-error-page	Java	no	Error page for form login attempts	Not yet supported
form-login-config	Java	no	Config spec for form-based login	Not yet supported
form-login-page	Java	no	URL for the form-based login page	Not yet supported
icon	Java	Yes	URL of icon to associate with a servlet	Supported for servlets
init-param	Java	Yes	Initialization parameter for a servlet	--
jsp-file	Java	No	Java Server Page file to use for a servlet	Not supported
lang	Oracle	Yes	IANA language name	For example: "en-US"
lang-mapping	Oracle	Yes	Specifies a mapping between a filename extension and language content	--
large-icon	Java	Yes	Large sized icon for icon display	--
load-on-startup	Java	Yes	Specifies if a servlet is to be loaded on startup	--
location	Java	Yes	Specifies the URL for an error page	Can be a local path name or HTTP URL
login-config	Java	No	Specifies a method for authentication	Not yet supported
mime-mapping	Java	Yes	Specifies a mapping between filename extension and the MIME type of the content	--
mime-type	Java	Yes	MIME type name for resource content	For example: "text/xml" or "application/octet-stream"
OracleError	Oracle	Yes	Specifies an Oracle error to associate with an error page	--
param-name	Java	Yes	Name of a parameter for a Servlet or ServletContext	Supported for servlets
param-value	Java	Yes	Value of a parameter	--
realm-name	Java	No	HTTP realm used for authentication	Not yet supported
role-link	Java	Yes	Specifies a role a particular user must have in order to access a servlet	Refers to a database role name. Make sure to capitalize by default!
role-name	Java	Yes	A servlet name for a role	Just another name to call the database role. Used by the Servlet APIs
security-role	Java	No	Defines a role for a servlet to use	Not supported. You must manually create roles using the SQL CREATE ROLE
security-role-ref	Java	Yes	A reference between a servlet and a role	--
servlet	Java	Yes	Configuration information for a servlet	--
servlet-class	Java	Yes	Specifies the classname for the Java servlet	--
servlet-language	Oracle	Yes	Specifies the programming language in which the servlet is written.	Either "Java", "C", or "PL/SQL". Currently, only Java is supported for customer-defined servlets.
servlet-mapping	Java	Yes	Specifies a filename pattern with which to associate the servlet	All of the mappings defined by Java are supported
servlet-name	Java	Yes	String name for a servlet	Used by Servlet APIs
servlet-schema	Oracle	Yes	The Oracle Schema in which the Java class is loaded. If not specified, the schema is searched using the default resolver specification.	If this is not specified, the servlet must be loaded into the SYS schema to ensure that everyone can access it, or the default Java class resolver must be altered. Note that the servlet-schema is capitalized unless the value is quoted with double-quotes.
session-config	Java	No	Configuration information for an HTTPSession	HTTPSession is not supported
session-timeout	Java	No	Timeout for an HTTP session	HTTPSession is not supported
small-icon	Java	Yes	Small icon to associate with a servlet	--
taglib	Java	No	JSP tag library	JSPs currently not supported
taglib-uri	Java	No	URI for JSP tag library description file relative to the web.xml file	JSPs currently not supported
taglib-location	Java	No	Pathname relative to the root of the web application where the tag library is stored	JSPs currently not supported
url-pattern	Java	Yes	URL pattern to associate with a servlet	See Section 10 of Java Servlet 2.2 spec
web-app	Java	No	Configuration for a web application	Only one web application is currently supported
welcome-file	Java	Yes	Specifies a welcome-file name	--
welcome-file-list	Java	Yes	Defines a list of files to display when a folder is referenced through an HTTP GET	Example: "index.html"

HTTP Request Processing for Oracle XML DB Servlets

Oracle XML DB handles an HTTP request using the following steps:

1. If a connection has not yet been established, Oracle listener hands the connection to a shared server dispatcher.
2. When a new HTTP request arrives, the dispatcher wakes up a shared server.
3. The HTTP headers are parsed into appropriate structures.
4. The shared server attempts to allocate a database session from the XML DB session pool, if available, but otherwise will create a new session.
5. A new database call is started, as well as a new database transaction.
6. If HTTP has included authentication headers, the session will be authenticated as that database user (just as if they logged into SQL*Plus). If no authentication information is included, and the request is GET or HEAD, Oracle XML DB attempts to authenticate the session as the ANONYMOUS user. If that database user account is locked, no unauthenticated access is allowed.
7. The URL in the HTTP request is matched against the servlets in the xdbconfig.xml file, as specified by the Java Servlet 2.2 specification.
8. The XML DB Servlet Container is invoked in the Java VM inside Oracle. If the specified servlet has not been initialized yet, the servlet is initialized.
9. The Servlet reads input from the ServletInputStream, and writes output to the ServletOutputStream, and returns from the service() method.
10. If no uncaught Oracle error occurred, the session is put back into the session pool.

    See Also: Chapter 19, "Using FTP, HTTP, and WebDAV Protocols"

The Session Pool and XML DB Servlets

The Oracle database keeps one Java VM for each database session. This means that a session reused from the session pool will have any state in the Java VM (Java static variables) from the last time the session was used.

This can be useful in caching Java state that is not user-specific, such as, metadata, but DO NOT STORE SECURE USER DATA IN JAVA STATIC MEMORY! This could turn into a security hole inadvertently introduced by your application if you are not careful.

Native XML Stream Support

The DOM Node class has an Oracle-specific method called write(), which takes the following arguments, returning void:

• java.io.OutputStream stream: A Java stream to write the XML text to
• String charEncoding: The character encoding to write the XML text in. If null, the database character set is used
• Short indent The number of characters to indent nested XML elements

This method has a shortcut implementation if the stream provided is the ServletOutputStream provided inside the database. The contents of the Node are written in XML in native code directly to the output socket. This bypasses any conversions into and out of Java objects or Unicode (required for Java strings) and provides very high performance.

Oracle XML DB Servlet APIs

The APIs supported by Oracle XML DB servlets are defined by the Java Servlet 2.2 specification, the Javadoc for which is available, as of the time of writing this, online at: http://java.sun.com/products/servlet/2.2/javadoc/index.html

Table 20-3 lists non-implemented Java Servlet 2.2 methods. In this release they result in runtime exceptions.

Table 20-3 Non-Implemented Java 2.2 Methods

Interface	Methods
HttpServletRequest	getSession(), isRequestedSessionIdValid()
HttpSession	ALL
HttpSessionBindingListener	ALL

Oracle XML DB Servlet Example

The following is a simple servlet example that reads a parameter specified in a URL as a path name, and writes out the content of that XML document to the output stream.

Example 20-1 Writing an Oracle XML DB Servlet

The servlet code looks like:

/* test.java */
import javax.servlet.http.*;
import javax.servlet.*;
import java.util.*;
import java.io.*;
import javax.naming.*;
import oracle.xdb.dom.*;

public class test extends HttpServlet
{
  protected void doGet(HttpServletRequest req, HttpServletResponse resp)
    throws ServletException, IOException
  {
    OutputStream os = resp.getOutputStream();
    Hashtable    env = new Hashtable();
    XDBDocument  xt;

    try
    {
      env.put(Context.INITIAL_CONTEXT_FACTORY,
              "oracle.xdb.spi.XDBContextFactory");
      Context ctx = new InitialContext(env);
      String [] docarr  = req.getParameterValues("doc");
      String doc;

      if (docarr == null || docarr.length == 0)
        doc = "/foo.txt";
      else
        doc = docarr[0];
      xt = (XDBDocument)ctx.lookup(doc);
      resp.setContentType("text/xml");
      xt.write(os, "ISO8859", (short)2);
    }
    catch (javax.naming.NamingException e)
    {
      resp.sendError(404, "Got exception: " + e);
    }
    finally
    {
      os.close();
    }
  }
}

Installing the Oracle XML DB Example Servlet

To install this servlet, compile it, and load it into Oracle9i database using commands such as:

% loadjava -grant public -u scott/tiger -r test.class

Configuring the Oracle XML DB Example Servlet

To configure Oracle XML DB servlet, update the /xdbconfig.xml file by inserting the following XML element tree in the <servlet-list> element:

<servlet>
  <servlet-name>TestServlet</servlet-name>
  <servlet-language>Java</servlet-language>
  <display-name>XML DB Test Servlet</display-name>
  <servlet-class>test</servlet-class>
  <servlet-schema>scott</servlet-schema>
</servlet>

and update the /xdbconfig.xml file by inserting the following XML element tree in the <servlet-mappings> element:

<servlet-mapping>
  <servlet-pattern>/testserv</servlet-pattern>
  <servlet-name>TestServlet</servlet-name>
</servlet-mapping>

You can edit the /xdbconfig.xml file with any WebDAV-capable text editor, or by using the updateXML() SQL operator.

Testing the Example Servlet

To test the example servlet, load an arbitrary XML file at /foo.xml, and type the following URL into your browser, replacing the hostname and port number as appropriate:

http://hostname:8080/testserv?doc=/foo.xml