Oracle9i XML Database Developer's Guide - Oracle XML DB Release 2 (9.2) Part Number A96620-01 |
|
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:
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.
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.
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.
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).
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.
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:
Oracle XML DB Resource API for Java/JNDI operates as follows:
lookup()
method, to locate an existing Oracle XML DB resource.Additionally, you can perform these operations:
XMLType
to access and modify parts of the XMLType
object.save()
method to write changes to the database.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:
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.
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.
Table 17-1 lists the parameters supported by Oracle XML DB Resource API for Java/JNDI.
Oracle XML DB Resource API for Java/JNDI has two main components:
lookup,
bind,
rename,
unbind, move,
and list
functions.Oracle XML DB implementation of JNDI provides a context factory class XDBContextFactory()
. This implements the initialContextFactory
interface used by JNDI to create initial contexts.
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.
JNDI's Context module returns various objects based on the following:
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 DBoracle.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 |
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:
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:
The object type is dependent on the document stored and the environment returned.
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.
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.
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.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 hierarchyjavax.naming.NotContextException
: The object is not a context.javax.naming.ContextNotEmptyException:
The context being deleted is not empty.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.
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:
The outputs of the JNDI objects component are:
Exceptions will be thrown by these classes:
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();
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. |
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.
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();
|
Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|