31 Using Oracle XML DB Content Connector

About the Content Repository API for Java (JCR)

JCR 1.0 defines a standard Java API for applications to interact with content repositories.

JCR models the data in a content repository as a tree of nodes. Each node may have one or more child nodes. Every node has exactly one parent node, except for the root node, which has no parent.

In addition to child nodes, a node may also have one or more properties. A property is a simple name/value pair. For example, a node representing a particular file in the content repository has a property named jcr:created whose value is the date the file was created.

Each property has a property type. For example, the jcr:created property has the DATE property type, requiring its value to be a valid date/time.

Similarly, each node has a node type. For example, a node representing a file has node type nt:file. The node type controls what child nodes and properties the node may have or must have. For example, all nodes of type nt:file must have a jcr:created property.

Because nodes and properties are named, they can be addressed by path. JCR supports both absolute and relative paths. For example, the absolute path

/My Documents/pictures/puppy.jpg/jcr:created

resolves to the jcr:created property of file puppy.jpg. This property can also be addressed relative to the My Documents folder by the following relative path:

pictures/puppy.jpg/jcr:created

Node and property names can be namespace qualified. Like XML, JCR uses colon-delimited namespace prefixes to express namespace-qualified names, for example, jcr:created. Unlike XML, JCR records the namespace prefix-to-URI mappings in a repository-wide namespace registry, which, for example, maps the jcr prefix to the URI http://www.jcp.org/jcr/1.0.

About Oracle XML DB Content Connector

Oracle XML DB Content Connector lets you access Oracle XML DB Repository using the JCR 1.0 Java API. Your applications can run either in a standalone Java Virtual Machine or a J2EE container.

Files and folders in Oracle XML DB Repository are represented as JCR nodes (and properties of those nodes). They can be created, retrieved, and updated using the JCR APIs.

Example of How Files and Folders are Exposed in JCR

The folder MyFolder is stored in the root folder of Oracle XML DB Repository. It contains two files, Address.xml and Car.jpg.

File Address.xml has the following XML content:

<Address country="US">
  <name>Alice Smith</name>
  <street>123 Maple Street</street>
  <city>Mill Valley</city>
  <state>CA</state>
  <zip>90952</zip>
</Address>

File Car.jpg has binary content: a picture of an automobile. It also has the following user-defined XML metadata:

<i:ImageMetadata>
  <Height>640</Height>
  <Width>480</Width>
  <RGB R="44" G="123" B="74"/>
</i:ImageMetadata> 

Oracle XML DB Content Connector exposes MyFolder, Address.xml, and Car.jpg as JCR nodes and properties.

Example 31-1 shows folder MyFolder represented as a tree of JCR nodes and properties. In this representation, bold type indicates a node, italic type indicates a node type, regular type indicates a property, and italic type with angle brackets (<>) indicates omitted data, such as binary data.

[root] (nt:folder)
  jcr:created="2001-01-01T00:00:00.000Z"
  jcr:content (nt:resource)
    jcr:data=null
    jcr:lastModified="2001-01-01T00:00:00.000Z"
    ojcr:owner="SYS"
    ojcr:creator="SYS"
    ojcr:lastModifier="SYS"
    ojcr:displayName=""
    ojcr:language="en-US"
  MyFolder (nt:folder)
    jcr:created="2001-01-01T00:00:00.000Z"
    jcr:content (nt:resource)
      jcr:data=null
      jcr:lastModified="2001-01-01T00:00:00.000Z"
      ojcr:owner="ALICE"
      ojcr:creator="BOB"
      ojcr:lastModifier="CHARLIE"
      ojcr:author="BOB"
      ojcr:comment="An application folder"
      ojcr:displayName="MyFolder"
      ojcr:language="en-US"
      ojcr:links (ojcr:links)
        ojcr:folderLink (ojcr:linkProperties)
          ojcr:linkType="Hard"
          ojcr:linkSource=<RESID of the root folder>
          ojcr:linkTarget=<RESID of folder MyFolder>
          ojcr:linkName="MyFolder"
    Address.xml (nt:file)
      jcr:created="2005-09-01T12:34:56.789Z"
      jcr:content (nt:resource)
        jcr:encoding="UTF-8"
        jcr:mimeType="text/xml"
        jcr:data=<binary representation of the XML content>
        jcr:lastModified="2005-09-01T12:34:56.789Z"
        ojcr:owner="ALICE"
        ojcr:creator="BOB"
        ojcr:lastModifier="CHARLIE"
        ojcr:author="BOB"
        ojcr:displayName="Address.xml"
        ojcr:language="en-US"
        ojcr:xmlContent (nt:unstructured)
          Address
            country="US"
            name
              jcr:xmltext
                jcr:xmlcharacters="Alice Smith"
            street
              jcr:xmltext
                jcr:xmlcharacters="123 Maple Street"
            city
              jcr:xmltext
                jcr:xmlcharacters="Mill Valley"
            state
              jcr:xmltext
                jcr:xmlcharacters="CA"
            zip
              jcr:xmltext
                jcr:xmlcharacters="90952"
        ojcr:links (ojcr:links)
          ojcr:folderLink (ojcr:linkProperties)
            ojcr:linkType="Hard"
            ojcr:linkSource=<RESID of folder MyFolder>
            ojcr:linkTarget=<RESID of file Address.xml>
            ojcr:linkName="Address.xml"
    Car.jpg (nt:file)
      jcr:created="2004-02-12T16:15:23.247Z"
      jcr:content (nt:resource)
        jcr:mimeType="image/jpeg"
        jcr:data=<binary content of file Car.jpg>
        jcr:lastModified="2004-02-12T17:20:25.314Z"
        ojcr:owner="ALICE"
        ojcr:creator="BOB"
        ojcr:lastModifier="CHARLIE"
        ojcr:author="BOB"
        ojcr:displayName="A shiny red car!"
        ojcr:language="en-US"
        i:ImageMetadata
          Height
            jcr:xmltext
              jcr:xmlcharacters="640"
          Width
            jcr:xmltext
              jcr:xmlcharacters="480"
          RGB
            R="44"
            G="123"
            B="74"
        ojcr:links (ojcr:links)
          ojcr:folderLink (ojcr:linkProperties)
            ojcr:linkType="Hard"
            ojcr:linkSource=<RESID of folder MyFolder>
            ojcr:linkTarget=<RESID of file Car.jpg>
            ojcr:linkName="Car.jpg"

Oracle Extensions to JCR Node Types

Oracle XML DB Content Connector augments the definitions of node types nt:file, nt:folder, and nt:resource to include additional information held in Oracle XML DB Repository. Node type ojcr:folder is added as a supertype of nt:folder, and node type ojcr:resource is added as a supertype of nt:resource. All Oracle extensions are in the namespace http://xmlns.oracle.com/jcr/1.0, which is mapped to namespace prefix ojcr.

In addition, node type mix:referenceable is added as a supertype of nt:file and nt:folder to allow all files and folders to be accessed by their resource id.

Binary and XML Content

Property jcr:data contains the binary content of a file. Note that jcr:data is a property not of node nt:file, but rather of its child node jcr:content.For files containing XML content, node jcr:content has a child node ojcr:xmlContent, under which the XML content can be accessed as a set of JCR nodes and properties. File Address.xml, referenced in Example 31-1, is such a file. The XML content of an XML file in the repository is mapped to JCR nodes and properties using the document view serialization defined by JCR, in which:

• XML elements are exposed as JCR nodes.

• XML attributes are exposed as JCR properties.

• XML text is exposed as JCR properties named jcr:xmlcharacters within nodes named jcr:xmltext.

System-Defined Metadata

Oracle XML DB Repository maintains metadata for each repository file and folder. In database views RESOURCE_VIEW and PATH_VIEW, this metadata is represented as a set of XML elements within XMLType column RES. In JCR, this metadata is mapped to properties in namespaces jcr and ojcr. Table 31-1 describes this mapping.

User-Defined Metadata

User-defined XML metadata is exposed as JCR nodes and properties under the jcr:content child node of the repository file or folder. As with XML file content, XML metadata is mapped to JCR nodes and properties using the document view serialization that is defined by JCR. See "Binary and XML Content" for a description of this serialization.

In Example 31-1, file Car.jpg has this user-defined metadata:

<i:ImageMetadata>
  <Height>640</Height>
  <Width>480</Width>
  <RGB R="44" G="123" B="74"/>
</i:ImageMetadata> 

The following JCR path retrieves the Width value:

/My Folder/Car.jpg/jcr:content/i:ImageMetadata/
   Width/jcr:xmltext/jcr:xmlcharacters

Hard Links and Weak Links

In JCR, each node and property has exactly one parent node, except for the root node, which has no parent. Consequently, there is exactly one absolute path to each JCR node or property.

However, in Oracle XML DB Repository, a resource (file or folder) can be linked to more than one parent folder, either by hard links, which control the life span of the child, or by weak links, which do not. Consequently, there can be more than one path to a resource, and a resource can have more than one parent.

In resolving a path, Oracle XML DB Content Connector traverses both hard and weak links. If there is more than one path to a resource, JCR method getPath() returns the path by which that resource was first discovered, subsequent to the most recent call to either save() or refresh(boolean) by that session. JCR method getParent() returns the folder targeted by that path.

It is often useful to obtain a list of all parents of a resource, if the resource is the target of more than one link and therefore has more than one parent folder. Oracle XML DB Content Connector presents this as nodes of type ojcr:linkProperties with path jcr:content/ojcr:links/ojcr:folderLink relative to node nt:file or nt:folder. There is one ojcr:folderLink node for each parent of the resource.

Node ojcr:folderLink has the following properties:

• ojcr:linkType: Link type (Hard or Weak)

• ojcr:linkSource: Resource id of the parent folder

• ojcr:linkTarget: Resource id of the child file or folder

• ojcr:linkName: Name of the child file or folder in that parent

Setting CLASSPATH

Oracle XML DB Content Connector requires the following entries in the Java CLASSPATH variable:

• $ORACLE_HOME/lib/jcr-1.0.jar

• $ORACLE_HOME/lib/ojcr.jar

• $ORACLE_HOME/lib/xmlparserv2.jar

• $ORACLE_HOME/jlib/xquery.jar

Obtaining the JCR Repository Object

In Oracle XML DB Content Connector, oracle.jcr.OracleRepository implements the JCR interface javax.jcr.Repository, which provides the entry point to a JCR repository. The code fragment in Example 31-2 shows how to obtain a Repository object for Oracle XML DB Repository.

import oracle.jcr.OracleRepository;
import oracle.jcr.OracleRepositoryFactory;
import oracle.jcr.xdb.XDBRepositoryConfiguration;
import oracle.jdbc.pool.OracleDataSource;
...
XDBRepositoryConfiguration configuration =
  new XDBRepositoryConfiguration();
OracleDataSource ods =
  (OracleDataSource)configuration.getDataSource();
// databaseURL is a JDBC database URL.
ods.setURL(databaseURL);
// OracleRepository implements javax.jcr.Repository.
OracleRepository repository =
  OracleRepositoryFactory.createOracleRepository(configuration);

OracleRepository implements both java.io.Serializable and javax.naming.Referenceable. This lets you create and configure an OracleRepository object upon application deployment, and store the ready-to-use OracleRepository object in a JNDI directory. At run-time, your application can retrieve the preconfigured OracleRepository object from the JNDI directory. This approach, recommended by the JCR specification, separates deployment and run-time concerns.

In Oracle XML DB Content Connector, the set of prefix-to-URI mappings forming the JCR namespace registry is stored as part of the OracleRepository configuration.

Sample Code to Upload File

Example 31-3 is a Java program that uploads a file from the local file system to Oracle XML DB Repository using Oracle XML DB Content Connector.

import java.io.FileInputStream;
 
import javax.jcr.Node;
import javax.jcr.Session;
import javax.jcr.SimpleCredentials;
 
import oracle.jcr.OracleRepository;
import oracle.jcr.OracleRepositoryFactory;
 
import oracle.jcr.xdb.XDBRepositoryConfiguration;
 
import oracle.jdbc.pool.OracleDataSource;
 
public class UploadFile
{
  public static void main(String[] args)
    throws Exception
  {
    String databaseURL = args[0];
    String userName = args[1];
    String password = args[2];
    String parentPath = args[3];
    String fileName = args[4];
    String mimeType = args[5];
    
    // Get the JCR Repository object.
    XDBRepositoryConfiguration configuration =
      new XDBRepositoryConfiguration();
 
    OracleDataSource ods =
      (OracleDataSource)configuration.getDataSource();
 
    ods.setURL(databaseURL);
    
    OracleRepository repository =
      OracleRepositoryFactory.createOracleRepository(configuration);
    
    // Create a JCR Session.
    SimpleCredentials sc =  
      new SimpleCredentials(userName, password.toCharArray());
 
    Session session = repository.login(sc);
 
    // Get the parent node.
    Node parentNode = (Node)session.getItem(parentPath);
    
    // Get the child contents.
    FileInputStream inputStream = new FileInputStream(fileName);
    
    // Create child node.
    Node node = parentNode.addNode(fileName, "nt:file");
    Node contentNode = node.getNode("jcr:content");
    contentNode.setProperty("jcr:mimeType", mimeType);
    contentNode.setProperty("jcr:data", inputStream);
    
    // Save changes and logout.
    session.save();
    session.logout();
  }
}
 
// EOF

You can compile and run Example 31-3 from the command line. The program requires the following command-line arguments:

• JDBC database URL

• User ID

• User password

• Folder in Oracle XML DB Repository into which to upload the file

• File to be uploaded

• MIME type

Example 31-4 illustrates this.

export CLASSPATH=.:$ORACLE_HOME/lib/jcr-1.0.jar:$ORACLE_HOME/lib/ojcr.jar:$ORACLE_HOME/lib/xmlparserv2.jar:$ORACLE_HOME/jlib/xquery.jar

javac UploadFile.java

java UploadFile jdbc:oracle:oci:@ quine password /public MyFile.txt text/plain

Additional Code Samples

You can find additional sample code at the following location:

$ORACLE_HOME/xdk/demo/java/jcr

For each code sample, a README file describes its purpose and use.

Logging API for Oracle XML DB Content Connector

Oracle XML DB Content Connector uses the standard java.util.logging framework. You can use the logging API provided by that framework to control logging behavior. For example, the following Java code fragment disables all logging.

import java.util.logging.LogManager;
...
LogManager.getLogManager().reset();

Supported JCR Compliance Levels

The JSR-170 standard, which defines JCR version 1.0, defines two compliance levels and a set of optional features. Oracle XML DB Content Connector supports Level 1 (read functions) and Level 2 (write functions).

Oracle XML DB Content Connector Restrictions

This section describes certain restrictions of Oracle XML DB Content Connector.

Why Register XML Schemas for Use with JCR?

XML data can be stored in Oracle XML DB Repository as either file content or user-defined metadata. In either case, the XML data can be based on an XML schema. XML schema-based data is validated against an XML schema that has been registered with Oracle XML DB.

By default, the JCR nodes corresponding to XML document content and user-defined metadata are of node type nt:unstructured, a generic node type defined by JCR, even if the XML data is XML schema-based. Oracle XML DB Repository still validates any changes made through the Oracle XML DB Content Connector against the XML schema, but it is not possible to access or specify typing metadata through JCR.

However, Oracle XML DB Content Connector lets XML schemas be registered for use in JCR. This causes the content connector to generate JCR node types for the XML-schema simple types, complex types, and global element declarations in the registered XML schema.

In exposing XML data as JCR nodes, the content connector determines whether the XML data conforms to an XML schema registered for JCR use, based on the value of XML attribute xsi:schemaLocation or xsi:noNamespaceSchemaLocation of its root element. If the XML data conforms to a JCR registered XML schema, then the XML data is exposed as JCR nodes of the node types generated from the XML schema, instead of using the generic node type nt:unstructured.

You can also use the generated JCR node types to create or update XML document content and user-defined metadata.

Example 31-5 shows an XML document with XML schema-based content.

<Address country="US"
   xmlns:xsi=
     "http://www.w3.org/2001/XMLSchema-instance"
   xsi:noNamespaceSchemaLocation=
     "http://www.example.com/Address">
  <name>Alice Smith</name>
  <street>123 Maple Street</street>
  <city>Mill Valley</city>
  <state>CA</state>
  <zip>90952</zip>
</Address>

The content of Example 31-5 is valid with respect to the XML schema shown in Example 31-6.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:complexType name="USAddress">
    <xsd:sequence>
      <xsd:element name="name"   type="xsd:string"/>
      <xsd:element name="street" type="xsd:string"/>
      <xsd:element name="city"   type="xsd:string"/>
      <xsd:element name="state"  type="xsd:string"/>
      <xsd:element name="zip"    type="xsd:long"/>
    </xsd:sequence>
    <xsd:attribute name="country" type="xsd:NMTOKEN"
                   fixed="US"/>
  </xsd:complexType>
</xsd:schema>

Initially, this XML schema is not registered for JCR use. The JCR nodes and properties representing the XML content are shown in Example 31-7.

ojcr:xmlContent (nt:unstructured)
   Address (nt:unstructured)
     country="US" (String)
     name (nt:unstructured)
       jcr:xmltext(ojcr:xmltext)
         jcr:xmlcharacters="Alice Smith" (String)
     street (nt:unstructured)
       jcr:xmltext(ojcr:xmltext)
         jcr:xmlcharacters="123 Maple Street" (String)
     city (nt:unstructured)
       jcr:xmltext(ojcr:xmltext)
         jcr:xmlcharacters="Mill Valley" (String)
     state (nt:unstructured)
       jcr:xmltext(ojcr:xmltext)
         jcr:xmlcharacters="CA" (String)
     zip (nt:unstructured)
       jcr:xmltext (ojcr:xmltext)
         jcr:xmlcharacters="90952" (String)

The XML schema is then registered for JCR use. The JCR nodes and properties are shown in Example 31-8.

ojcr:xmlContent (nt:unstructured)
  Address (USAddress)
    country="US" (String)
    name (xsd:string)
      jcr:xmltext(ojcr:xmltext)
        jcr:xmlcharacters="Alice Smith" (String)
    street (xsd:string)
      jcr:xmltext(ojcr:xmltext)
        jcr:xmlcharacters="123 Maple Street" (String)
    city (xsd:string)
      jcr:xmltext(ojcr:xmltext)
        jcr:xmlcharacters="Mill Valley" (String)
    state (xsd:string)
      jcr:xmltext(ojcr:xmltext)
        jcr:xmlcharacters="CA" (String)
    zip (xsd:long)
      jcr:xmltext (ojcr:xmltext)
        jcr:xmlcharacters="90952" (Long)

Node Address now has node type USAddress. Similarly, nodes name, street, city, and state have node type xsd:string. Node zip has node type xsd:long, and the jcr:xmlcharacters property of its jcr:xmltext child is a LONG property type.

How to Register an XML Schema with JCR

Before you register an XML schema for use with JCR, you must register it for use with Oracle XML DB, using PL/SQL procedure DBMS_XMLSCHEMA.registerSchema. For example, to register an XML schema with location http://www.example.com/Address, first register it for use with Oracle XML DB, as shown in Example 31-9. Then, register it for use with JCR, using Oracle XML DB Content Connector Java APIs, as shown in Example 31-10.

BEGIN
  DBMS_XMLSCHEMA.registerSchema(
    schemaurl=>'http://www.example.com/Address',
    schemadoc=>bfileContainingSchema,
    local=>false,
    enablehierarchy=>DBMS_XMLSCHEMA.ENABLE_HIERARCHY_RESMETADATA);
END;
/

import oracle.jcr.nodetype.OracleNodeTypeManager;...
OracleNodeTypeManager ntm = (OracleNodeTypeManager)
  session.getWorkspace().getNodeTypeManager();
 
ntm.registerXMLSchema("http://www.example.com/Address", null);

The list of XML schemas registered for use with JCR is stored in the OracleRepository object. You can save this registration data by storing the OracleRepository object in a JNDI directory, as recommended by the JCR specification.

JCR requires that each node type have a unique name. By default, Oracle XML DB Content Connector generates JCR nodes types that correspond to a registered XML schema in the target namespace of the XML schema. If you wish to register two XML schemas with the same namespace, and the XML schemas declare types with the same names, you can avoid a name clash by overriding the namespace into which the JCR node types are generated. Refer to the Javadoc of method registerXMLSchema() for details.

How JCR Node Types are Generated from XML Schemas

This section describes how Oracle XML DB Content Connector generates JCR node types from XML schemas that are registered for JCR use.

The type models of JCR and XML Schema are similar but not equivalent. Some aspects of XML Schema have no representation in JCR. For example, some constraining facets of an XML-schema simple type are not discoverable through JCR. They are enforced by Oracle XML DB Content Connector nonetheless.

More generally, the JCR node types generated from an XML schema do not augment, detract, or alter the XML schema validation performed when XML data that conforms to that XML schema is created or updated, whether through JCR or other interfaces.