JCR API

Overview

Bloomreach Content uses the Java Content Repository (JCR) API, as defined by JSR-170, to access its content repository. This page provides practical examples for interacting with the repository using the JCR API. For a complete overview of the JCR API, refer to the official specification or additional resources.

Accessing the Repository

All repository operations require a JCR Session object. A session is not thread-safe and is used to read and modify repository content. Changes made in a session are isolated until explicitly saved.

To obtain a session, first acquire a reference to the repository. This step is outside the JCR standard and uses Bloomreach-specific APIs.

HippoRepository repository = HippoRepositoryFactory.getHippoRepository("vm://");
copy

This approach requires your application to run in the same JVM as the repository. To connect remotely, use RMI:

HippoRepository repository = HippoRepositoryFactory.getHippoRepository("rmi://localhost:1099/hipporepository");
copy

To enable remote access, configure the repository to start as an RMI server. Set the start-remote-server parameter in the Tomcat context.xml:

<Parameter name="start-remote-server" value="true" override="false"/>
copy

Or set the parameter in the CMS web application's web.xml under the RepositoryServlet configuration:

<init-param>
  <param-name>start-remote-server</param-name>
  <param-value>true</param-value>
</init-param>
copy

Info: RMI and its related parameters (repository-address and start-remote-server) are no longer supported as of version 17.0.0.

Hippo-specific extensions to the JCR API (see Examples 2 and 3) are not available over RMI connections.

Obtaining a Session

To log in and obtain a session, provide valid credentials:

Session session = repository.login("admin", "admin".toCharArray());
copy

Within the CMS and HST-based sites, an active session is already available. Repository managed components also receive an active session. If you are developing outside these contexts, use the example above. Otherwise, use the existing session. In the CMS, retrieve the session as follows:

Session session = UserSession.get().getJcrSession();
copy

Example 1: Retrieve a Document

JCR repositories use a tree structure. Each node can have properties and child nodes. Node types, defined in Content Node Definitions (CND), determine allowed properties and sub-nodes.

A document is a subtree of nodes. Retrieve a document using its path:

Node node = session.getRootNode().getNode("content/articles/myarticle");
Node document = node.getNode(node.getName());
if (document.isNodeType("hippo:document") && document.isNodeType("hippotranslation:translated")) {
    System.out.println("This document is written in the language "
                   + document.getProperty("hippotranslation:locale").getString());
} else {
    System.out.println("This document is not in a specific language");
}
copy

Use isNodeType to check node types, as type definitions are inherited. All documents in Bloomreach Content must derive from hippo:document. Mix-in types, such as hippotranslation:translated, extend document capabilities.

Example 2: Access Document Workflow

Bloomreach Content extends the JCR API to support workflows on documents. Use the WorkflowManager to access workflows. Workflows are configurable and pluggable, so a generic workflow interface is returned. Multiple workflows may be active on a document; select by category (for example, "default").

Node document = ...;
HippoWorkspace ws = (HippoWorkspace) document.getSession().getWorkspace();
Workflow wf = ws.getWorkflowManager().getWorkflow("default", document);
if (wf instanceof DefaultWorkflow) {
    ((DefaultWorkflow)wf).delete();
}
copy

This example requires a VM connection (vm://). It does not work over RMI (rmi://).

Example 3: Restore an Older Document Version

Workflows also provide versioning capabilities beyond standard JCR versioning. The versioning workflow includes application-specific logic, such as tracking document status and versioning only published documents.

The following example retrieves the versioning workflow and restores the earliest published version as the current unpublished version:

Node node = ...;
HippoWorkspace ws = (HippoWorkspace) node.getSession().getWorkspace();
DocumentWorkflow wf = (DocumentWorkflow) ws.getWorkflowManager().getWorkflow("default", node);
SortedMap<Calendar, Set<String>> versions = wf.listVersions();
wf.restoreVersion(versions.keySet().iterator().next());
copy

This example requires a VM connection (vm://). It does not work over RMI (rmi://).

Example 4: Query for Latest News Articles

You can retrieve documents by executing queries. Construct a query object using either XPATH or SQL-like syntax. The following example retrieves news articles, ordered by date descending:

Query q = session.getWorkspace().getQueryManager().createQuery(
                  "SELECT * FROM myproject:news " +
                  "ORDER BY myproject:date DESC", Query.SQL);
QueryResult r = q.execute();
for (NodeIterator i = r.getNodes(); i.hasNext(); ) {
    System.err.println("document " + i.nextNode().getPath() + " matches");
}
copy