17
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
• Using Oracle XML DB Resource API for Java/JNDI
• Calling Sequence for Oracle XML DB Resource API for Java/JNDI
• Parameters for Oracle XML DB Resource API for Java/JNDI
• Oracle XML DB Resource API for Java/JNDI Examples

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.

• Oracle XML DB Resource API for Java/JNDI allows Java applications in the server or client to access and manipulate objects stored in Oracle XML DB Repository.
• JNDI is flexible enough to allow an object to be returned for a given path without imposing the limitations of current file systems on the interface. The object returned is commonly a Java bean with methods for each element and attribute of the XML element loaded.
• The bean also implements DOM interfaces so that dynamic data can be accessed easily as well. Server access to data is centralized in LDAP servers as well as the database with the same API. In JNDI, folders are called Contexts. The two terms are used interchangeably in this chapter.
• Oracle XML DB Resource API for Java/JNDI supports JNDI Service Provider Interface (SPI).

  Note: In this release, Oracle XML DB's implementation of JNDI SPI only supports the javax.naming interface. Directory, attribute, and event operations are not yet supported.

oracle.xdb.spi

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:

• Resource manipulation. You can create, update, remove, rename, and move an Oracle XML DB resource, and look up an Oracle XML DB resource by name.
• Folder manipulation. You can create, update, remove, rename, move, and list the contents of a folder.
• Retrieve contents of the Oracle XML DB resource. Using Oracle extensions, you can update the properties of the Oracle XML DB resource.
• Save contents to the database.

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:

• Opening connections to the database
• Committing or rolling back operations. Oracle XML DB Resource API for Java/JNDI does not perform commits by itself

  See Also: Chapter 9, "Java and Java Bean APIs for XMLType", "Java Bean API for XMLType"

Using Oracle XML DB Resource API for Java/JNDI

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

• JNDI is used, typically through the context lookup() method, to locate an existing Oracle XML DB resource.
• Alternatively, JDBC is used to access the Oracle XML DB resource view to retrieve and modify resources.
• JNDI can return:
  • An instance of the Oracle XML DB Resource interface
  • An instance of the Java bean (if registered) or XMLDocument for the contents of the XML data

Additionally, you can perform these operations:

• Use the Java API for XMLType to access and modify parts of the XMLType object.
• Use the save() method to write changes to the database.
• Use the JNDI bind() family to bind the Oracle XML DB resource to a new path name.

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

• Context (used for folders). This is for JNDI.
• Versioning. This is for WebDAV.

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
PROVIDER_URL	The start path from which objects are to be returned.
INITIAL_CONTEXT_FACTORY	The context factory to be used to generating contexts - always "oracle.xdb.spi.XDBContextFactory".
XDB_RESOURCE_TYPE	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:

• Context module. This implements the JNDI Context interface, which accesses the Oracle XML DB Repository using the lookup, bind, rename, unbind, move, and list functions.
• A set of classes/interfaces. These are returned from operations performed on the Context module. These classes/interfaces are:
  • Enumerators. These enumerate name/classname pairs or name/object pairs.
  • Other classes returned by the Context module. These can be:
    • A resource. A leaf in Oracle XML DB Repository that implements methods to modify the properties of the Oracle XML DB resources and folders.
    • XMLType/Bean/org.w3c.Document interface. These operate on XML documents stored in Oracle XML DB Repository.

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:

• Operation
• Path
• Environment variables

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

• oracle.xdb.XDBResource: Returned by lookup when the environment variable is set to resource. The environment variables are described in Oracle9i XML API Reference - XDK and Oracle XML DB
• This class implements methods to manipulate the metadata of the objects in the hierarchy.
• oracle.xdb.XMLType, Java Bean: Implements the methods defined by the SQL XMLType API. This can also be obtained from the Resource if it does not point to a folder (that is, a leaf). This can also handle non-XML data using the Binary schema.

  See Also: Chapter 9, "Java and Java Bean APIs for XMLType" which explains the XMLType interface and Oracle XML DB's DOM support.

  A Java bean is a class specific to XML documents for which an XML schema has been registered. The lookup/list methods that return objects will determine if the document returned is an XML object for which an XML schema has been registered.

• javax.naming.NamingEnumeration: Provides a means for enumerating the contents of the Oracle XML DB Folder as a name/class name pair. The class name is one of the following:
  • oracle.xdb.XDBContext (if object is a folder)
  • A bean
  • oracle.xdb.XMLType

  The class name is dependent on the document stored and the environment returned. It also provides a high-level overview of the processing flows and associated inputs and outputs among the major functional components. It includes the processing flows to the external sources for the external inputs and outputs that cross into and out of the system domain.

• javax.naming.BindingEnumeration: Provides a way to enumerate the contents of the Oracle XML DB folder as a name/object pair. The object is one of the following:
  • oracle.xdb.XDBContext (if object is a folder)
  • A bean
  • oracle.xdb.XMLType

  The object type is dependent on the document stored and the environment returned.

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
Context.PROVIDER_URL	path string, "/" for example	Contains the starting path from which name resolution is to begin.
Context.INITIAL_CONTEXT_FACTORY	oracle.xdb.spi.XDBContextFactory	The value of the context factory to be used for generating the initial context object.
XDBContext.RETURN_OBJECT_TYPE	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.
XDBContext.COUNTRY	The country name string	Determines the locale to be used for error messages. The default is database locale.
XDBContext.LANGUAGE	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:

• XDBResource(): Class generated as a result of a lookup operation if RETURN_OBJECT_TYPE is set to Resource.
• XMLType(): Class generated as a result of the lookup operation if RETURN_OBJECT_TYPE is set to Contents.
• NamingEnumeration: Returned as a result of the list method.
• BindingEnumeration: Returned as a result of the listBindings operation.
• Bean: Generated as a result of the lookup operation if the object being looked up is an XML schema-based XML document and a bean for the XML schema has been generated.

JNDI Context Module Error Messages

The following are exceptions thrown by JNDI Context APIs:

• javax.naming.NamingException: A naming exception has occurred.
• javax.naming.NameAlreadyBoundException: The name is already bound.
• javax.naming.NameNotFoundException: The name cannot be located in the hierarchy
• javax.naming.NotContextException: The object is not a context.
• javax.naming.ContextNotEmptyException: The context being deleted is not empty.

JNDI Objects

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

• XDBResource class
• XDBDocument class/bean class

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

• JNDI objects input

  The input to this module is the cstate which has been obtained by the Context from the various methods for the given path.

  The important methods in XDBClassEnumeration() class are:

  • hasMore(): The derived classes of the XDBClassEnumeration class use this method from the base class directly without any modification.
  • next(). This gives you the next object in the enumeration. The object can be either a ClassName pair or a ListBinding.
• JNDI objects output

  The outputs of the JNDI objects component are:

  • XDBResource: Result of XDBBindingEnumeration.
  • XDBDocument: Result of XDBBindingEnumeration.
  • NameClassPair: Result of NamingEnumeration.
  • Binding: Result of BindingEnumeration.
• JNDI Objects Error Messages

  Exceptions will be thrown by these classes:

  • NamingException: General naming exception.
  • NoSuchNameException: Attempt to get next when none is available.

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();
env.put(Context.INITIAL_CONTEXT_FACTORY,"oracle.xdb.spi.XDBContextFactory");

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();

Note: 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");

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