Skip Headers

Oracle9i XML Database Developer's Guide - Oracle XML DB
Release 2 (9.2)

Part Number A96620-01
Go To Documentation Library
Go To Product List
Book List
Go To Table Of Contents
Go To Index

Master Index


Go to previous page Go to next page

Oracle XML DB Resource API for Java/JNDI

This chapter describes the Oracle XML DB Resource API for Java. It includes the JNDI interface for accessing and manipulating the Repository data.

This chapter contains these sections:

Introducing Oracle XML DB Resource API for Java/JNDI

What Is JNDI?

Oracle XML DB supports Java Naming and Directory Interface (JNDI) as the standard navigational access Application Program Interface (API). JNDI is a Sun programming interface. It connects Java programs to naming and directory services such as Domain Name Server (DNS), Lightweight Directory Access Protocol (LDAP), and Network Directory Service (NDS). JNDI is most commonly used as a client interface to LDAP servers and can also be used to access local operating system files.

See Also:

Oracle9i XML API Reference - XDK and Oracle XML DB

JNDI Support in Oracle XML DB

Oracle XML DB uses JNDI to locate resources and manage collections. JNDI returns XMLType objects that support both a Java Bean and Document Object Model (DOM) interface. Most typical file system operations (rename, link, delete, and so on) are provided through the JNDI interface. JNDI also provides a simple interface for accessing attribute data (as do DOM and Java Beans), which is not as powerful as the other APIs.

See Also:

"Java Bean API for XMLType"

Once an XMLType object is retrieved (using either JNDI or JDBC/SQL), it can be cast to the matching Java Bean class or the DOMNode class. Oracle XML DB tracks any changes to the XMLType object that you make in memory through Java Bean methods or DOM APIs, and you can save those incremental changes back to the database with the save() method on XMLType. Alternatively, you can bind XMLType objects into SQL statements to modify an entire XMLType object at once or to alter individual pieces with UPDATE_VAL() in SQL.


The application writes to the JNDI API. The directory drivers are written to the JNDI SPI (Service Provider Interface). Classes in package oracle.xdb.spi implement service provider drivers.

WebDAV Support

Package oracle.xdb.spi contains Oracle-specific extensions to the JNDI public standard. oracle.xdb.spi also provides support for WebDAV (Web Distributed Authoring and Versioning).

See Also:

Chapter 19, "Using FTP, HTTP, and WebDAV Protocols"

Oracle XML DB Resource API for Java/JNDI Features

Oracle XML DB Resource API for Java/JNDI provides application programs with the following features:

Oracle XML DB Resource API for Java/JNDI is implemented as a wrapper over C functions using Java Native Interface (JNI). Because the Oracle Java layer is very thin, all the performance benefits of the underlying C implementation are achieved.

Use With Java API for XMLType

The JNDI API can be embedded in any Java application that can also use the Java API for XMLType to perform database operations such as:

Using Oracle XML DB Resource API for Java/JNDI

Oracle XML DB Resource API for Java/JNDI operates as follows:

Additionally, you can perform these operations:

The Oracle XML DB Resource API for Java includes a set of subinterfaces that indicate resource type information as follows:

Oracle XML DB Resource API for Java includes interfaces for objects such as workspaces, branches, and baselines (as defined by the WebDAV versioning specification). Context and Resource are Java bean-based accessors. Since they are XMLType subclasses, they can implement the Java API for XMLType.

JNDI SPI resides in Oracle9i database in the internal SYS schema in the package. The package xdb.jar.xdb.jar can also be used by applications for further development. Applications developed to use Oracle XML DB Resource API for Java/JNDI must also be loaded in Oracle9i database in order to use the JNDI API.

Calling Sequence for Oracle XML DB Resource API for Java/JNDI

Get started with JNDI by creating an initial context or folder. This corresponds to the root directory of Oracle XML DB. To create an initial context, pass a hashtable with parameters (name/value pairs) to indicate how JNDI is to be configured.

Parameters for Oracle XML DB Resource API for Java/JNDI

Table 17-1 lists the parameters supported by Oracle XML DB Resource API for Java/JNDI.

Table 17-1 Oracle XML DB Resource API for Java/JNDI: Parameters  
Parameter Name Description


The start path from which objects are to be returned.


The context factory to be used to generating contexts - always "oracle.xdb.spi.XDBContextFactory".


Determines what data is returned to the application by default when a path name is resolved:

  • "Resource": A resource class will be returned.
  • "XMLType": The contents of the resource will be returned.

In this release, Oracle XML DB has implemented only the javax.naming package. Oracle XML DB has an extension to this package, an extension to the lookup() method. The extension (an overload) also takes a Boolean (indicating that a row lock should be grabbed) to indicate a "lookup FOR UPDATE" and a String with an XPath to define a fragment of the document to load immediately (rather than relying on the lazy manifest facility).

Oracle XML DB Resource API for Java/JNDI has two main components:

Using JNDI Contexts - XDBContextFactory()

Oracle XML DB implementation of JNDI provides a context factory class XDBContextFactory(). This implements the initialContextFactory interface used by JNDI to create initial contexts.

Initial Context

The initial context describes the starting point in the Repository hierarchy from which all name resolutions happens, with the exception of absolute names which begin with "/". Oracle XML DB does not differentiate between initialContexts and Contexts since it stores the initial path of the application in an environment variable in the class. Thus, initialContextFactory generates an XDBContext class that implements the Context interface. initialContextFactory also takes in as parameters the Language and the Country names for Globalization support.

XDBContext class return results in the form of a pointer to the data. The JNI implementation passes this pointer and other relevant data back to the Java Context API, which generates the appropriate objects from the pointer and other data. This information is then returned to the application program, which can further make calls on these objects. The implementation is very fast.

How JNDI's Context Module Returns Objects

JNDI's Context module returns various objects based on the following:

The following objects are created by the Context module's operation:

JNDI Context Module's Inputs

InitialContextFactory() inputs a java.util.Hashtable class, which contains the input parameters to control the creation of the context.

Table 17-2 describes these input parameters, their valid values, and their uses.

Table 17-2 Oracle XML DB Resource API for Java: JNDI Context Input Parameters  
JNDI Input Parameters Name Valid Values Description


path string, "/" for example

Contains the starting path from which name resolution is to begin.



The value of the context factory to be used for generating the initial context object.


Resource, contents

Determines if the caller is interested in the resource (the metadata object) or the actual contents. For example, a database application which is interested only in the data might not be interested in the metadata. The default is Contents.


The country name string

Determines the locale to be used for error messages. The default is database locale.


The language name strings

Controls the error message language, and so on. The default is database language.

JNDI Context Processing

The first class in the Oracle XML DB SPI that JNDI invokes for the application is XDBContextFactory().

NamingManager calls getInitialContext() method of XDBContextFactory(). XDBContextFactory() is part of oracle.xdb.spi package.

XDBContextFactory is defined as follows:

public class XDBContextFactory implements InitialContextFactory
public Context getInitialContext(Hashtable env) throws NamingException;

RETURN_OBJECT_TYPE lets you specify the intent of the application, that is, the kind of data you are interested in.

The purpose of InitialContextFactory()is to generate the initial object from which the child objects can be obtained.

XDBContext() class implements javax.naming.Context interface. It is part of oracle.xdb.spi package.

Context interface implements a method, close() which implements cleanup operations for the object.

See Also:

Oracle9i XML API Reference - XDK and Oracle XML DB

JNDI Context Module Outputs

The following is the output generated by the methods of the JNDI Context module:

JNDI Context Module Error Messages

The following are exceptions thrown by JNDI Context APIs:

JNDI Objects

JNDI objects are constructed on calling various methods on the Context interface. The Context lookup method generates either of the following:

The listBinding() method also generates a BindingEnumeration() class, which has methods to generate these classes.

Oracle XML DB Resource API for Java/JNDI Examples

Example 17-1 Resource API JNDI: Using JNDI to Determine Purchase Order Properties

Here is a way to find out properties of an Oracle XML DB purchase order object using JNDI alone. JNDI allows properties to be looked up using a string property name. This API is useful when the properties to be retrieved are not known at compile time, as well as to provide the same interface as JNDI service providers other than Oracle XML DB, like an LDAP directory.

This example retrieves a string property title and a Boolean property isCurrent from an XMLType resource:

import javax.naming.*;
import java.util.*;

Hashtable env = new Hashtable();

DirContext    ctx = new InitialDirContext(env);
Attributes    po = ctx.getAttributes("/orders/123.xml");
String        title = (String)po.get("title");
boolean       isCurrent = ((Boolean)po.get("isCurrent")).booleanValue();

Example 17-2 Resource API JNDI: Using DOM to Determine Purchase Order Properties

Here is a JNDI example using DOM for attribute access. The environment setup is the same as in the previous example and omitted here:

Context  ctx = new InitialContext(env);
Document po = (Document)ctx.lookup("/orders/123.xml");
Node     n;

n = po.getElementsByTagName("Title").item(1);
String  title = n.getNodeValue();
n = po.getElementsByTagName("IsCurrent").item(1);
boolean isCurrent = new Boolean(n.getNodeValue()).booleanValue();


The DOM example requires a type conversion from a string to a Boolean to get the desired data. This adversely affects performance.

Example 17-3 Resource API Java Beans: Using JNDI to Determine Purchase Order Properties

Here is a Java Bean version of the DOM example. It uses JNDI to locate the object with the same setup:

Context       ctx = new InitialContext(env);
PurchaseOrder po = ctx.lookup("/orders/123.xml");
Boolean       isCurrent = po.isCurrent();
String        title = po.getTitle();

Note how simple the Java Bean API is. In this case, the return of lookup() is simply cast to the corresponding Bean class. The application must already have knowledge of the datatype at a particular filename or else it must use methods defined on XMLType to determine what class to cast to.

Example 17-4 Resource JDBC: Using SQL To Determine Purchase Order Properties

Here is an example using SQL instead of JNDI to find the object. This example uses XMLType to access the resource. JDBC is not as fast as JNDI, but it provides the power of SQL SELECT potentially using criteria other than path name to find the XMLType object.

PreparedStatement pst = con.prepareStatement(
"SELECT r.RESOLVE_PATH('/companies/oracle') FROM XDB$RESOURCE r");

XMLType po = (XMLType)pst.getObject(1);
Document podoc = (Document) po.getDOM();

Go to previous page Go to next page
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Go To Product List
Book List
Go To Table Of Contents
Go To Index

Master Index