Oracle Beehive Release 2 (2.0) Java Content Repository API

Oracle Beehive Release 2 (2.0) Java Content Repository (JCR) API implements the Content Repository API for Java Technology specification (Java Specification Request 170, version 1.0). You may find this specification at http://jcp.org/en/jsr/detail?id=170 . The Content Repository API is a common, standardized Java interface for content repositories. With the Oracle Beehive JCR API, you may access and manipulate an Oracle Beehive instance's workspaces and its data like a content repository.

The Content Repository API specification is divided into two compliance levels and a set of additional optional features that repositories of either level may support. Level 1 consists of read functions while level 2 adds additional write functions.

Oracle Beehive JCR API supports the following features specified by the Content Repository API specification:

  • Level 1 Repository Features
    • Retrieval and traversal of nodes and properties
    • Reading values of properties
    • Transient namespace remapping
    • Discovery of available node types
    • Discovery of access control permissions
  • Level 2 Repository Features
    • Adding and removing nodes and properties
    • Writing values of properties
  • Optional Features
    • Versioning
    • Locking

The following topics are covered:

Requirements

To compile the examples in this module, the following .jar files must be in your class path:

  • <Oracle home>/beehive/jlib/beehive_jcr-1.0.jar
  • <Oracle home>/j2ee/home/lib/ejb.jar
  • <Oracle home>/j2ee/home/lib/ejb30.jar
  • <Oracle home>/j2ee/home/lib/oc4j-internal.jar
  • <Oracle home>/j2ee/home/oc4jclient.jar
  • <Oracle home>/lib/xmlparserv2.jar
  • <Oracle home>/opmn/lib/optic.jar

Javadoc

Refer to Oracle Beehive Java Content Repository Java API Reference.

Oracle Beehive Java Content Repository API Operations

The Oracle Beehive JCR API enables you to manipulate an Oracle Beehive instance's workspaces and its data like a content repository as defined by the Content Repository API.

The content repository as a whole is represented by a javax.jcr.Repository object, which is acquired from the oracle.ocs.jcr.RepositoryFactory class. A client connects to the repository by calling Repository.login(). This method takes one argument, an object of type javax.jcr.Credentials (in particular, a SimpleCredentials object). This object contains the user name and password of a user that may look up the JCR service. The login() method returns a Session object with which the client accesses the repository.

Content in a repository, such as folders and documents, are represented by nodes in a tree structure. You may access nodes by traversal access or direct access. Traversal access involves accessing nodes in relation to other nodes. For example, you may call Node.getNodes() to retrieve a NodeIterator, which will enable you to iterate through a given node's child nodes. Direct access involves accessing nodes with absolute paths. If a node is referenceable, you can directly access a node by its Universally Unique Identifier (UUID). For example, you may directly access a node by its absolute path with Session.getItem() or by its UUID with Session.getNodeByUUID().

Connecting to Oracle Beehive through the JCR API

Oracle Beehive JCR API connects to Oracle Beehive through the Oracle Remote Method Invocation (ORMI) protocol. (For more information about ORMI, refer to Chapter 6, "Using Remote Method Invocation" in "Oracle Containers for J2EE Services Guide.")

In your Oracle Beehive JCR API client, you must specify the following information to connect to Oracle Beehive:

  • Initial Context Factory Object: This is used for resolving names during Java Naming and Directory Interface (JNDI) lookup. The samples featured here use oracle.j2ee.rmi.RMIInitialContextFactory.

  • Java Naming Provider URL: This is the location of the Oracle Beehive JCR service. It has the following form:

    opmn:ormi:// <host name>: <port>:BEEAPP/jcr-service

    <port> is the OPMN request port. Obtain the OPMN request port (default value is 6003) by calling the following command:

    <Oracle Beehive home>/opmn/bin/opmnctl status -port

  • Security Principal: Specify oc4jadmin.

  • Security Credentials: Specify the password of oc4jadmin.

Set these parameters in the Oracle Beehive repository (represented by the class BeehiveRepositoryConfigruation) in one of the following ways:

  • In a map that contains these connection attributes:

    Hashtable env = new Hashtable();
    env.put(Context.INITIAL_CONTEXT_FACTORY, "oracle.j2ee.rmi.RMIInitialContextFactory");
    env.put(Context.SECURITY_PRINCIPAL, "oc4jadmin");
      env.put(Context.SECURITY_CREDENTIALS, "Welcome1");
    env.put(Context.PROVIDER_URL, "opmn:ormi://example.com:6003:BEEAPP/jcr-service");
    BeehiveRepositoryConfiguration config = new BeehiveRepositoryConfiguration(env);
    
  • Through the setter methods in a BeehiveRepositoryConfiguration object:

    BeehiveRepositoryConfiguration config = new BeehiveRepositoryConfiguration();
    config.setInitialContextFactory("oracle.j2ee.rmi.RMIInitialContextFactory");
    config.setSecurityPrincipal("oc4jadmin");
    config.setSecurityCredentials("Welcome1");
    config.setConnectionUrl("opmn:ormi://example.com:6003:BEEAPP/jcr-service");
    
  • In the BeehiveRepositoryConfiguration constructor:

     BeehiveRepositoryConfiguration config = new BeehiveRepositoryConfiguration(
      "oracle.j2ee.rmi.RMIInitialContextFactory",
      "oc4jadmin",
      "Welcome1",
      "opmn:ormi://example.com:6003:BEEAPP/jcr-service");
    

Using ORMI Tunneling through HTTP

Oracle Beehive JCR clients may connect to Oracle Beehive with HTTP/HTTPS by using ORMI tunneling through HTTP. This is useful if your Oracle Beehive instance is behind a firewall and you do not want to open the ORMI port in your firewall.

Use the following for the Java Naming Provider URL:

ormi:http:// <host name>: <HTTP/HTTPS port>/jcr-service

You may use https in place of http if you have configured it for your Oracle Beehive instance. If you are using default HTTP/HTTPS ports (such as 80/443), you may omit the HTTP/HTTPS port number.

Refer to "Configuring ORMI Tunneling through HTTP" in Chapter 6, "Using Remote Method Invocation" for more information.

Using Non-oc4jadmin User for EJB Lookup on Oracle Beehive JCR Server

You may create and configure a non-oc4jadmin user for EJB lookup and executing remote methods of the Oracle Beehive JCR server. The following steps create a non-oc4jadmin user named jcruser with the password Welcome1:

  1. Create a role with RMI login permission:

                                        prompt> cd  
                                       <Oracle Beehive home>/j2ee/home
                                        prompt> java -Doracle.j2ee.home=
                                       <Oracle Beehive home>/j2ee/BEEAPP -jar jazn.jar -addrole jazn.com jcrrmi
                                        prompt> java -Doracle.j2ee.home=
                                       <Oracle Beehive home>/j2ee/BEEAPP -jar jazn.jar -grantperm jazn.com -role jcrrmi com.evermind.server.rmi.RMIPermission login
                                    
  2. Create a user and assign the newly created role

                                        prompt> java -Doracle.j2ee.home=<ORACLE_HOME>/j2ee/BEEAPP -jar jazn.jar -adduser jazn.com jcruser Welcome1
                                        prompt> java -Doracle.j2ee.home=<ORACLE_HOME>/j2ee/BEEAPP -jar jazn.jar -grantrole jcrrmi jazn.com jcruser
                                    
  3. Configure security-role-mapping in the file <Oracle Beehive home>/j2ee/BEEAPP/application-deployments/jcr-service/orion-application.xml as follows:

    <namespace-access>
      <read-access>
        <namespace-resource root="">
          <security-role-mapping name="&lt;jndi-user-role&gt;">
            <user name="
                                       jcruser"/>
          </security-role-mapping>
        </namespace-resource>
      </read-access>
    
      <write-access>
        <namespace-resource root="">
         <security-role-mapping name="&lt;jndi-user-role&gt;">
            <user name="
                                       jcruser"/>
          </security-role-mapping>
        </namespace-resource>
      </write-access>
    </namespace-access>
                                    
  4. Restart the BEEAPP component with the following command:

    <Oracle Beehive home>/beehive/bin/beectl restart --component <Identifier of the BEEAPP component>

Using a Non-oc4jadmin user for EJB Lookup on Oracle Beehive JCR Server

If you are not using a user with OC4J administrator privileges for EJB lookup, perform the following additional steps:

  1. Provision the jcrrmi role with subject.propagation privileges. Add the highlighted text in the <Oracle Beehive home>/j2ee/BEEAPP/config/system-jazn-data.xml file:

    <grant>
      <grantee>
        <principals>
          <principal>
            <realm-name>jazn.com</realm-name>
            <type>role</type>
            <class>oracle.security.jazn.spi.xml.XMLRealmRole</class>
            <name>jcrrmi</name>
          </principal>
        </principals>
      </grantee>
    
      <permissions>
        <permission>
          <class>com.evermind.server.rmi.RMIPermission</class>
          <name>login</name>
        </permission>
         
                                       <permission>       <class>com.evermind.server.rmi.RMIPermission</class>       <name>subject.propagation</name>     </permission>
      </permissions>
    </grant>
                                    
  2. Restart the BEEAPP component with the following command:

    <Oracle Beehive home>/beehive/bin/beectl restart --component <Identifier of the BEEAPP component>

Oracle Beehive Java Content Repository API Samples

This section lists the following samples:

Sample of Level 1 Operations

The sample EntList.java initializes the repository and performs a high-level traversal of the repository.

The following is the output of EntList.java. The output will vary depending on the content of your repository:

Root node path: /
Root node name: /
Traversing workspace...
-------------------------------
/
  oracle
    doc
    beeadmin's Personal Workspace
      INBOX
      Documents
      Notifications
      Public Documents
      Subscriptions
      Workspace Trash
-------------------------------
DONE

Sample of Level 2 Operations

The sample JcrClient.java performs the following:

  • Initializes the repository
  • Adds a folder node and saves it
  • Adds a content node and accesses it
  • Removes the content node

Note: The path specified by docFolderPath must exist in your repository.

The following is the output of JcrClient.java:

Successfully logged in. Session Object oracle.ocs.jcr.client.impl.SessionImpl@1dc0e7a
Added Folder Node to Workspace Node
About to add file NewFile1197504256484
Setting property of type BEEHIVE_CONTENT
Added the file and updated the content
Content = I got updated
Removed node

Sample of Invoking JCR API in a Servlet Application

The servlet ListEntNode.java lists the enterprise node:

You should see text similar to the following in a browser when you access the servlet:

Oracle Beehive Java Content Repository Test

Retrieved the repository object from the repository factory

Finished setting credentials

Retrieved session: oracle.ocs.jcr.client.impl.SessionImpl@6d1750

Retrieved root node of the workspace: /

User ID used to acquire the session: beeadmin

List of nodes in the oracle node:

  • doc
  • beeadmin's Personal Workspace

Sample of Retrieving Repository by Performing JNDI Lookup

The sample RepositoryTest.java performs the following:

  • Initialize BeehiveRepositoryConfigruationwith connection attributes as strings
  • Retrieve the repository
  • Store the repository object in com.sun.jndi.fscontext.RefFSContext
  • Retrieve the repository from com.sun.jndi.fscontext.RefFSContext by JNDI lookup
  • Login to Oracle Beehive
  • List the enterprise

Notes:

  • This sample requires that fscontext.jar and providerutil.jar be present in your class path. You may obtain these .jar files from JDeveloper or the File System service provider from Java Naming and Directory Interface (JNDI). (Refer to Java Naming and Directory Interface (JNDI) Service Providers for a list of JNDI service providers, including File System.)

  • In RepositoryTest.java, refer to the following line of code:

    hashtableEnvironment.put(Context.PROVIDER_URL,"file://c:/jndi");
    

    Ensure that the directory C:/jndi exists in your computer, or create a directory, then set the full path name of that directory in the Context.PROVIDER_URL parameter with this line of code.

The following is the output of RepositoryTest.java:

Stored the repository object Root node name: /
Retrieved the repository object by JNDI lookup
Listing the enterprise
====================================
    doc
    beeadmin's Personal Workspace
====================================
DONE

Sample of JCR XPath Search

This release of Oracle Beehive JCR supports XPath searches. The sample JcrSearch.java demonstrates how to perform XPath searches.

Notes Regarding Oracle Beehive JCR XPath Search

  1. XPath expressions containing the OR predicate are not supported

  2. Exact and child nodes path constraints are not supported

  3. Column specifier is not supported

  4. Order by clause is not supported on user defined properties and beehive:path property

  5. Searching multi-valued properties is not supported

  6. jcr:contains() function is not supported

Oracle Beehive JCR Samples Files

The package jcr_samples.zip contains the following files:

  • Sample of Level 1 Operations:
    • EntList.java
  • Sample of Level 2 Operations:
    • JcrClient.java
  • Sample of Invoking JCR API in a Servlet Application:
    • ListEntNode.java
  • Sample of Retrieving Repoistory by Performing JNDI Lookup
    • RepositoryTest.java
  • Sample of JCR XPath Search
    • JcrSearch.java

Compiling and Running Samples

This section covers the following topics:

Compiling and Running Standalone Applications

To compile and run "Sample of Level 1 Operations", "Sample of Level 2 Operations", or "Sample of Retrieving Repository by Performing JNDI Lookup", ensure that all the .jar files listed in "Requirements" are in your class path. Compile these samples with JDK 1.5 or later.

Configuring Client Computer

Edit the hosts file of the client computer (that will access the Oracle Beehive JCR server) and add the IP address and the host name (but not domain) of the Oracle Beehive JCR server. For Windows XP, the location of this file is C:\WINDOWS\system32\drivers\etc\hosts For Linux and UNIX-based operating systems, it is /etc/hosts.

For example, if the IP address and host name of your Oracle Beehive JCR server is 10.20.30.40 and example.com, respectively, add the following line to the hosts file (without the .com):

10.20.30.40   example

Deploying Servlets on OC4J

The following steps describe how to deploy the sample listed in "Sample of Invoking JCR API in a Servlet Application" on standalone OC4J.

Requirements

  • JDK 1.5 or later
  • Oracle OC4J 10.1.3 or later
  • The .jar files listed in "Requirements" including beehive_jcr-1.0.jar

Steps to Deploy JCR API Servlet in Standalone OC4J

  1. Copy ListEntNode.java to <OC4J install directory>/j2ee/home/default-web-app/WEB-INF/classes/ .

  2. Copy the .jar files listed in "Requirements" to <OC4J install directory>/j2ee/home/default-web-app/WEB-INF/lib/ .

  3. Create the file <OC4J install directory>/j2ee/home/default-web-app/WEB-INF/web.xml with the following contents:

    <?xml version="1.0" encoding="ISO-8859-1"?>
    
      <servlet>
        <servlet-name>ListEntNode</servlet-name>
        <servlet-class>oracle.sample.jcr.ListEntNode</servlet-class>
      </servlet>
    
      <servlet-mapping>
        <servlet-name>ListEntNode</servlet-name>
        <url-pattern>/listnodes/ListEntNode</url-pattern>
      </servlet-mapping>
    </web-app>
    
  4. Compile ListEntNode.java. Ensure the following is in your class path:

    • <OC4J install directory>/j2ee/home/default-web-app/WEB-INF/lib/ejb.jar
    • <OC4J install directory>/j2ee/home/default-web-app/WEB-INF/lib/ejb30.jar
    • <OC4J install directory>/j2ee/home/default-web-app/WEB-INF/lib/oc4j-internal.jar
    • <OC4J install directory>/j2ee/home/default-web-app/WEB-INF/lib/beehive_jcr-1.0.jar
    • <OC4J install directory>/j2ee/home/default-web-app/WEB-INF/lib/optic.jar
    • <OC4J install directory>/j2ee/home/default-web-app/WEB-INF/lib/xmlparserv2.jar
    • <OC4J install directory>/j2ee/home/default-web-app/WEB-INF/classes/ListNode.class

    Ensure that the compiled ListEntNode.class file appears in the <OC4J install directory>/j2ee/home/default-web-app/WEB-INF/classes/ directory.

  5. Start OC4J with the following command:

    <OC4J install directory>/bin/oc4j -start

  6. Access the servlet at http:// <OC4J host name>: <port number>/servlet/listnodes/ListEntNode (the default port number is 8888).

Deploying Servlets on Apache Tomcat

The following steps describe how to deploy the sample listed in "Sample of Invoking JCR API in a Servlet Application" on Apache Tomcat.

Requirements

  • JDK 1.5 or later
  • Apache Tomcat 5.5.2 or later
  • The .jar files listed in "Requirements" are available in the Apache Tomcat library path

Steps to Deploy JCR API Servlet

  1. Create the directory jcrtest to hold the files of the servlet.

  2. In the directory jcrtest, create the directory WEB-INF.

  3. In the WEB-INF directory, create the following directory structure:

    • classes

    • lib

    • src

  4. In the src directory, create the nested directory oracle/sample/jcr. Save the file ListEntNode.java in the jcr directory.

  5. Copy the .jar files listed in "Requirements" to the lib directory.

  6. In the WEB-INF directory, create a file named web.xml that contains the following:

    <?xml version="1.0" encoding="ISO-8859-1"?>
    
      <servlet>
        <servlet-name>ListEntNode</servlet-name>
        <servlet-class>oracle.sample.jcr.ListEntNode</servlet-class>
      </servlet>
    
      <servlet-mapping>
        <servlet-name>ListEntNode</servlet-name>
        <url-pattern>/listnodes</url-pattern>
      </servlet-mapping>
    </web-app>
    
  7. Compile ListEntNode.java as described in "Compiling and Running Standalone Applications". Ensure that the compiled ListEntNode.class file appears in the classes/oracle/sample/jcr directory.

  8. Copy the jcrtest directory to <Apache Tomcat install directory>/webapps . Restart Apache Tomcat. Apache Tomcat will automatically deploy the servlet for you. Access the servlet with http://localhost:8080/jcrtest/listnodes (assuming that you are running Apache Tomcat on port 8080.

Configuring Oracle Beehive JCR Service

For a list of configuration properties for the Oracle Beehive JCR service, run the command beectl list_properties --component _JcrServletService:

beectl list_properties --component _JcrServletService

----------------------+---------------------------------------------------------
Property name         | Property value
----------------------+---------------------------------------------------------
Alias                 | _JcrServletService
----------------------+---------------------------------------------------------
AuthenticationScheme  | BASIC
----------------------+---------------------------------------------------------
JCRServerEnabled      | true
----------------------+---------------------------------------------------------
JcrSessionTimeout     | 960
----------------------+---------------------------------------------------------
MaxDownloadBufferSize | 261888
----------------------+---------------------------------------------------------
ServiceApplication    | svcapp_jcr-service
----------------------+---------------------------------------------------------
ServiceInstances      | instance_jcr-service_BEEAPP_mysite.example.com
----------------------+---------------------------------------------------------
Site                  | _CURRENT_SITE
----------------------+---------------------------------------------------------
Status                | ENABLED
----------------------+---------------------------------------------------------
UploadBufferSize      | 260096
----------------------+---------------------------------------------------------

The following table lists the parameters you may change with the beectl utility:

Name Description
JCRServerEnabled If set to true, the Oracle Beehive JCR service will service clients, otherwise, it will throw an exception. Default value: true.
UploadBufferSize Size of buffer to use in piecewise copies between streams during document uploads to the Oracle Beehive JCR service. For example, if its value is 1, then one byte at a time is copied from the input stream. Default value is listed in the output of beectl list_properties --component _JcrServletService.
MaxDownloadBufferSize Maximum buffer size to use in piecewise copies between streams during document downloads from the Oracle Beehive JCR service. Default value is listed in the output of beectl list_properties --component _JcrServletService.
AuthenticationScheme If set to DIGEST, the Oracle Beehive JCR service digest authentication to authenticate the client. If set to BASIC, it uses basic authentication. Default value: DIGEST.
JcrSessionTimeout Length of time (in minutes) before the client session expires.

You may not configure the following properties:

  • Alias
  • ServiceApplication
  • ServiceInstances
  • Site
  • Status

To modify a property, call the beectl modify_property command. Afterwards, call the beectl actiavte_configuration to commit your changes.

Redeploying Oracle Beehive JCR Service

  1. Upgrade the service with an archive file. Call the command beectl upgrade_service_application --archive <Path to Oracle Beehive JCR service EAR file>

    <Path to Oracle Beehive JCR service EAR file> is the full path name of the archive file jcr-service.ear.

  2. Retrieve the component identifier for the component JcrServletServiceInstance with the command beectl list_components.

  3. Call the command beectl upgrade_service_instance --service_instance_id --component <Identifier of JcrServletServiceInstance>