Skip Headers
Oracle® XML DB Developer's Guide
11g Release 1 (11.1)

Part Number B28369-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

31 Using Oracle XML DB Content Connector

This chapter describes how to use Oracle XML DB Content Connector to access Oracle XML DB Repository.

Oracle XML DB Content Connector implements Content Repository API for Java (sometimes referred to as JCR), a Java API standard developed by the Java community as JSR-170.

This chapter contains these topics:

Overview of JCR and Oracle XML DB Content Connector

This section contains the following topics:

About the Content Repository API for Java (JCR)

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

See Also:

Java Community Process, "Content Repository for Java technology API", http://jcp.org/en/jsr/detail?id=170. Chapter 4 of the JSR-170 specification provides a concise introduction to JCR 1.0

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.

Note:

For this release, using Oracle XML DB Content Connector in the database Oracle JVM (the Java Virtual Machine available within a database process) is not supported. To use the content connector in the database tier, you must use either 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.

How Oracle XML DB Repository Is Exposed in JCR

Oracle XML DB Content Connector represents data in Oracle XML DB Repository as JCR nodes and properties. Files and folders are represented as nodes of type nt:file and nt:folder, respectively. Their content and metadata is exposed as nodes of node type nt:resource.

This section contains the following topics:

An 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.

Example 31-1 JCR Node Representation of MyFolder

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.

Table 31-1 Oracle XML DB Resource to JCR Mappings

XPath Relative Path From Node nt:file or nt:folder

/Resource/CreationDate

jcr:created

/Resource/ModificationDate

jcr:content/jcr:lastModified

/Resource/Author

jcr:content/ojcr:author

/Resource/DisplayName

jcr:content/ojcr:displayName

/Resource/Comment

jcr:content/ojcr:comment

/Resource/Language

jcr:content/ojcr:language

/Resource/CharacterSet

jcr:content/jcr:encoding

/Resource/ContentType

jcr:content/jcr:mimeType

/Resource/Owner

jcr:content/ojcr:owner

/Resource/Creator

jcr:content/ojcr:creator

/Resource/LastModifier

jcr:content/ojcr:lastModifier


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. 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

How to Use Oracle XML DB Content Connector

This section describes how to use Oracle XML DB Content Connector to access information in Oracle XML DB Repository. It has the following topics:

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

  • $ORACLE_HOME/jdbc/lib/ojdbc14.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.

Example 31-2 Code Fragment Showing How to Get a Repository Object

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.

See Also:

Oracle Database XML Java API Reference, package oracle.jcr

Sample Code to Upload File

Example 31-3 contains a Java program that uploads a file from the local file system to Oracle XML DB Repository using Oracle XML DB Content Connector. Compile and run this example from the command line. The program requires these 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

For example:

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

javac UploadFile.java

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

Example 31-3 Using Oracle XML DB Content Connector to Upload a File

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

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.

Default Workspace Name

A single workspace is supported. In calling the login(Credentials, String) or login(String) methods of javax.jcr.Repository, the workspace name must be either an empty-string ("") or NULL.

Operations Restricted to Specific Node Types

Methods save() and refresh() of javax.jcr.Item can be called only on nodes whose type is nt:file or nt:folder. Method move() of javax.jcr.Session and methods copy() and move() of javax.jcr.Workspace can be called only on nt:file and nt:folder nodes.

Determining the State of Files or Folders

Methods isNew() and isModified() of javax.jcr.Item return the state of the file or folder containing the item, not the item itself. Method isNew() returns true if the file or folder has been created in the JCR transient layer but not saved. Method isModified() returns true if the file or folder has been changed in the transient layer but not saved.

Interaction Between Binary and XML Content

The jcr:data property contains the binary-format content of a file. If the file content is XML, there is also an ojcr:xmlContent node under which its XML content is exposed as JCR nodes and properties. Changes you make to the ojcr:xmlContent subtree are not reflected in the jcr:data property until those changes are saved. If you change both the jcr:data property and the ojcr:xmlContent subtree, then the ojcr:xmlContent subtree takes precedence when those changes are saved.

Order in Which Changes Are Saved

The save method of class javax.jcr.Session or class javax.jcr.Item saves changes made in the transient layer. If more than one node or property has been changed, then JCR does not specify the order in which the changes are stored. Oracle XML DB Content Connector saves changes in the following:

  1. Apply updates to existing files and folders, in path-sorted order.

  2. Create new files and folders, in path-sorted order.

  3. Move existing files and folders, in reverse path-sorted order.

  4. Delete existing files and folders, in reverse path-sorted order.

Undefined Properties

Properties that have definitions of type UNDEFINED are stored as STRING values.

Node Type nt:base Is Abstract

Node type nt:base is abstract and cannot be specified as the type of a new node.

Node jcr:content Is Created Automatically

When you create a node of type nt:file or nt:folder, a jcr:content node is created automatically as a child.

Saving Normalizes Node jcr:xmltext

Saving combines successive jcr:xmltext nodes, which represent text within XML content or user-defined metadata, into a single jcr:xmltext node.

Node Type mix:referenceable

Node types nt:file, nt:folder, and nt:resource are subtypes of mix-in node type mix:referenceable. Consequently, all nt:file, nt:folder, and nt:resource nodes can be referenced by UUID. You cannot add mix:referenceable to nodes of any type.

Full-Text Indexing

You can create a full-text index on file content using PL/SQL package DBMS_XDBT. This lets queries apply function jcr:contains to property jcr:data of a jcr:content node. Full-text indexes on other properties are not supported.

Using XML Schemas with JCR

Oracle XML DB Content Connector can create JCR node types from XML schemas.

This section has the following topics:

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-4 shows an XML document with XML schema-based content.

Example 31-4 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-4 is valid with respect to the XML schema shown in Example 31-5.

Example 31-5 XML Schema

<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-6.

Example 31-6 JCR Representation of XML Content Not Registered for JCR Use

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-7.

Example 31-7 JCR Representation of XML Content Registered for JCR Use

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-8. Then, register it for use with JCR, using Oracle XML DB Content Connector Java APIs, as shown in Example 31-9.

Example 31-8 Registering an XML Schema for Use with Oracle XML DB

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

Note:

Only globally registered XML schemas (local=>false) can be used with JCR.

Example 31-9 Registering an XML Schema for Use with JCR

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.

See Also:

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.

Built-In Simple Types

A JCR node type is provided for each XML Schema built-in type. For example, the JCR node type xsd:decimal corresponds to the built-in type xsd:decimal.

The inheritance hierarchy of the JCR node types follows that of the built-in types. For example, xsd:integer is a subtype of xsd:decimal.

Each XML Schema built-in type maps to a JCR property value type, which is used to represent values of that type in JCR.

Table 31-2  XML Schema Built-In Types Mapped to JCR Property Value Types

XML Schema Built-in Type JCR Property Value Type

xsd:anySimpleType

STRING

xsd:anyURI

STRING

xsd:base64Binary

BINARY

xsd:boolean

BOOLEAN

xsd:byte

LONG

xsd:date

DATE (1)

xsd:dateTime

DATE (1)

xsd:decimal

DOUBLE (2)

xsd:double

DOUBLE

xsd:duration

STRING

xsd:ENTITIES

STRING (3)

xsd:ENTITY

STRING

xsd:float

DOUBLE

xsd:gDay

STRING

xsd:gMonth

STRING

xsd:gMonthDay

STRING

xsd:gYear

STRING

xsd:gYearMonth

STRING

xsd:hexBinary

BINARY

xsd:ID

STRING

xsd:IDREF

STRING

xsd:IDREFS

STRING (3)

xsd:int

LONG

xsd:integer

LONG (2)

xsd:language

STRING

xsd:long

LONG

xsd:Name

STRING

xsd:NCName

STRING

xsd:negativeInteger

LONG

xsd:NMTOKEN

STRING

xsd:NMTOKENS

STRING (3)

xsd:nonNegativeInteger

LONG

xsd:nonPositiveInteger

LONG

xsd:normalizedString

STRING

xsd:NOTATION

STRING

xsd:positiveInteger

LONG

xsd:QName

STRING

xsd:short

LONG

xsd:string

STRING

xsd:time

DATE (1)

xsd:token

STRING

xsd:unsignedByte

LONG

xsd:unsignedInt

LONG

xsd:unsignedLong

LONG

xsd:unsignedShort

LONG


Notes for Table 31-2:

  1. The JCR DATE property type is accessed using java.util.Calendar objects. Since Calendar requires all fields to be set, a mask of 1970-01-01T00:00:00.000+00:00 is used to supply default values for missing fields when Property.getDate() or Value.getDate() is called. This includes omitted hour/minute/second values (for xsd:date), year/month/day values (for xsd:time), or time-zone values (for xsd:date, xsd:time, and xsd:dateTime). Calling Property.getString() or Value.getString() returns the unparsed string representation. Similarly, Property.setValue(String) or Property.setValue(valueFactory.createValue(String)) may be used to set DATE properties without applying the mask.

  2. The value space of xsd:decimal and xsd:integer exceeds that of the corresponding JCR types, DOUBLE and LONG (accessed as Java double and long values). Consequently, some xsd:decimal and xsd:integer values can only be accessed in JCR as strings. For example, bigIntegerProperty.getLong() will throw a javax.jcr.ValueFormatException, but bigIntegerProperty.getString() will return the unparsed string representation. Similarly, Property.setValue(String) or Property.setValue(valueFactory.createValue(String)) may be used to set DOUBLE or LONG properties to values outside the JCR value space.

  3. xsd:ENTITIES, xsd:IDREFS, and xsd:NMTOKENS are represented in JCR as multi-valued STRING properties.

XML Schema-Defined Simple Types

A JCR node type is created for each simple type defined in an XML schema. The inheritance hierarchy of the JCR node types follows that of the XML schema types.

A derived-by-list simple type is represented by a multi-valued JCR property definition.

A derived-by-union simple type is represented by a JCR property definition with property type UNDEFINED.

The JCR node type corresponding to an anonymous simple type has a synthetic name anonymousNodeType#sequenceNumber. Your application should not rely on the synthesized name. It is not guaranteed to be the same across sessions, and it may change when an XML schema is registered or deregistered for JCR use or the definition of a registered XML schema is changed.

Complex Types

A JCR node type is created for each complex type defined in an XML schema. The inheritance hierarchy of the JCR node types follows that of the XML schema types.

For a JCR node type corresponding to an XML schema complex type:

  • A property definition is created for each attribute declaration of the complex type. Attribute declarations or attribute groups referenced by name in a complex type are treated as though they were defined in line.

  • A residual property definition is created if the complex type has an attribute wildcard.

  • A child node definition is created for each uniquely-named element declaration in the complex type's content model. Element declarations or module groups referenced by name are treated as though they were defined in line. If an element declaration is the head of a substitution group, a child node definition is also created for each element declaration within the substitution group.

  • A residual child node definition is created if the complex type has an element wildcard.

  • A jcr:xmltext child node definition is created if the complex type permits XML text, either because xsd:mixed=true or it is an xsd:simpleContent definition.

The JCR node type for a complex type supports child node ordering.

It is not possible to determine whether a type was derived by extension or restriction using JCR.

The JCR node type corresponding to an anonymous complex type has a synthetic name anonymousNodeType#sequenceNumber. Your application should not rely on the synthesized name. It is not guaranteed to be the same across sessions, and it may change when an XML schema is registered or deregistered for JCR use or the definition of a registered XML schema is changed.

Global Element Declarations

A JCR node type is created for each global element declaration in an XML schema. The local name of the generated node type is formed by prepending an underscore (_) to the local name of the global element declaration. For example, in a namespace-qualified purchase order XML schema, a node type named po:_purchaseOrder is created for global element named po:purchaseOrder.