Accessing the CRX Repository

This section describes different ways to access the CRX repository: either the JCR API or the content. Which method you need to use depends on where the repository is and how its communication with the outside world is set up.

The following ways of accessing content and content services hosted in a CRX repository are presented in the following sections:

• Accessing the JCR API. Used when developing JCR applications, leveraging the full set of JCR API calls directly.
• Accessing content via the HTTP protocol. Used when developing generic web applications, especially in Apache Sling framework, or when accessing content from non-Java technologies. All that is required is a web browser or another HTTP client, which is built into most modern application frameworks and programming languages/environments. 
• Accessing content via Network File Servers. Used when working with binary content (files and folders) and when integrating with desktop environments.

You can access the JCR API either via JNDI, JCR remoting via WebDAV, or RMI remoting. Access the JCR API when you have JCR or Java applications that need JCR access to the repository.

With CRX 2.0 and higher, accessing the repository has been greatly simplified.

The Repository object is the front door of the JCR API. Whenever a client application needs to access a content repository, it first needs access to a repository instance through which all the other JCR functionality can be accessed. However, JCR 1.0 did not specify where and how such a repository instance can be found or created, so applications had to use JNDI lookups or implementation-specific initialization code to bootstrap access a content repository.

One of the goals of JCR 2.0 was to specify a standard solution to this bootstrap problem. To achieve this goal, the expert group specified the RepositoryFactory interface that allows an application to convert a Map of configuration options to the corresponding repository instance.

The recommended way to access a RepositoryFactory instance is to use the ServiceLoader class in Java 6 or the equivalent but oddly located ServiceRegistry class in Java 5. As a last resort, one can also instantiate a known RepositoryFactory implementation class using the specified public zero-argument constructor. The following code snippet shows how this works:

The RepositoryFactory approach works well, but it is a bit verbose as shown in the preceding example. To avoid having to rewrite this piece of code in all JCR client applications, a simple JcrUtils.getRepository(Map) utility method in the jackrabbit-jcr-commons library was implemented. With this utility method, you can simplify the preceding code to:

In practice, however, keeping track of the map of configuration options is often a bit complicated. So, the configuration has been narrowed down to a single string like the database URIs used in JDBC: This concept is known as a repository URI.

To do this, a specific repository configuration parameter org.apache.jackrabbit.repository.uri has been defined. All repository factories that want to support repository URIs should look for this parameter in the Map instance given to the getRepository() call. Day modified all the repository factories in Jackrabbit and CRX to support this parameter and added the JcrUtils.getRepository(String) utility method to further simplify client code. For example:

The same mechanism also works for JNDI URLs or file:// URLs to local embedded repositories. You only need to make sure that you have all the correct libraries in your classpath.

The Java Naming and Directory Interface (JNDI) is a Java naming service. The purpose of a naming service is to translate names into addresses, much like a phone book translates names into phone numbers. The idea is that the names are easier to manage than the addresses.

The following code accesses a CRX repository that runs on the same servlet engine as the application, and that is registered using JNDI:

JCR Remoting is based on CRX JCR WebDAV Server, extending from the Jackrabbit JCR WebDAV Server, which provides an end-point for remotely accessing the repository. The JCR remoting protocol, extending WebDAV and adding DAVEx batch operations, is used as one of the possible remoting layers in the overall Apache Jackrabbit client-server SPI Architecture upon which CRX is built. The protocol is based on HTTP and supports JSON format.

The client JCR application needs to include the JCR SPI Client libraries, and then they can access a remote CRX repository. See the sample application that follows for an example client-side setup for remote JCR access to CRX.

To access a repository via SPI remoting, there is a unified JcrUtils.getRepository(url) method that lets you connect to a repository by specifying a URL. The following is an example URL:

JCR Remoting requires that the JCR WebDAV Server is configured and enabled in the CRX instance. This design is by default; please be sure to check the corresponding settings in case of problems with connecting from JCR clients.

The default server's endpoint URL is http://host:port/crx/server. Make sure you adapt the client-side connection URL in case of customized server installation.

The client-side JCR Remoting libraries should generally match the version of the CRX server they connect to.

The CRX server should be accessible from the client machine via the HTTP protocol on the port on which CRX runs (7402 by default). You can always check whether the client machine has access to the CRX server by opening the server's URL in a web browser (or requesting it using a HTTP client, like wget).

JCR methods supported via JCR Remoting. The JCR client repository is a JCR 2 (JSR 283)-compliant repository. However, the underlying SPI architecture, and the remoting protocol might not implement all the methods and calls.

SPI architecture and the JCR Remoting are a part of the Jackrabbit reference implementation of the JCR standard. The current status of implementation can be tracked in Jackrabbit issue tracker:

• Status of implementing the new JCR 2 API calls in SPI/remoting, issue JCR-2003
• General status of JCR remoting implementation in jackrabbit-spi2dav Jackrabbit component

As of CRX 2.1, the JCR remoting suppports the JCR 1 (JSR 170) API calls (with the exception of impersonation; see JCR-2538) and parts of JCR 2. Some of the new JCR 2 calls have not been added to the remoting yet, such as the following:

• AccessControl Management
  
• LifeCycle Management
• NodeType Registration
• Retention Management
• Shareable Nodes
• Versioning: Activities & Configuration
• Versioning: Simple
• Workspace Management

For an example of the full setup and all necessary libraries, an example application and the libraries are provided for you in crx-quickstart/opt/examples/davex-client. The example stand-alone application connects to a CRX repository via the DavEx remoting protocol and prints the repository descriptors to the console.

The libraries are available at crx-quickstart/opt/examples/davex-client/lib.

Building the sample application. The sample comes with an Apache Ant build file (http://ant.apache.org/) for building and running.

To start the example application, you first need to build it:

With the Ant binaries on the path, type ant build to build the application. This creates a build directory, which contains a runnable jar file.

Running the sample application. Before running the application, make sure that there is a running CRX instance at http://localhost:7402/. Type ant run or java -jar build/davex-client.jar to run the application.

RMI interoperability with CRX 1.x repositories. Due to the nature of the RMI connection, the server and client must use the same (or close enough) versions of the RMI and JCR jars. Connecting from JCR 2.0 to JCR 1.0 or vice versa over RMI will not work. Use WebDAV instead for
cross-version remoting.

We generally recommend to use WebDAV remoting for CRX 2.x.

The CRX repository can be accessed accessed using JCA (Java Connector Architecture) by using the Jackrabbit JCA Resource Adapter module. The JCA Resource Adapter module has been extended in Jackrabbit 2.1 to support any JCR 2-compliant repository, and as such it can also be used for CRX.

For information on how to configure Jackrabbit's JCA Resource Adapter module with CRX repository, see the blog post on JCA connector for JCR content repositories on dev.day.com.

You can access the CRX repository content via an HTTP request. This allows you to integrate CRX content in any application that supports an HTTP interface and to display files in a Web browser.  

REST stands for "Representational State Transfer" and is a style of software architectures for distributed hypermedia systems, introduced by Dr. Roy Fielding, Day Chief Scientist, in 2000. The best known example of a system running according to REST principles is the World Wide Web. 

CRX integrates Apache Sling as its web application development and content delivery framework in the CQ5 Platform component of the product. Sling is a RESTful web application framework, leveraging CRX's JCR repository as a content storage platform and providing an extensible, scriptable, web application content delivery platform, running inside an OSGi framework runtime (Apache Felix project).

Sling provides RESTful access to repository resources via HTTP protocol. You can learn more about the Apache Sling and the OSGi from the Developer's Getting Started Guide.

This section presents only examples of how CRX content can be accessed in a RESTful way using the Sling framework. To understand how Sling works, see the links in the next subsection.

One of the fundamental capabilities of the Sling framework is its mapping of JCR content nodes into RESTful resources, each identified by a URI constructed from the node's JCR path for the sake of clarity. The resources can then have different representations (renditions), which a client application can choose by specifying the URL that includes a rendition extension (for example, .html for an HTML representation) and potentially more fine-grained selector (for example, .print for a representation of content suitable for printing).

The next sections present some examples of how to request specific built-in renditions of resources, and also point out links to information on how to create your own renditions. To understand how Sling works and how it processes requests, you have the following resources available:

• Short introduction to OSGi and Sling for CRX developers
• Details of Sling Request Processing in CQ5 documentation. Note that the basic Sling processing is not CQ5 specific, and applies to any applications built on top of Sling.
• Various blog posts on Day developer portal tagged with "sling"
• Finally, resources on the Apache Sling project site

You access content in a variety of ways by typing the appropriate URL into your web browser's address bar. Basically, you can access differert renditions of a given resource, or JCR node - either provided out of the box by Sling, or created by you - by specifying the appropriate URL in the HTTP GET call (for example, by entering it in your browser).

We will use the node /content in our examples. The node's JCR view is presented in the CRXDE Lite development environment:

The following types of renditions are available:

• text
• HTML
  
• JSON
• XML

You can also create your own custom renditions.

The following URL is the generic way to access a rendition (representation) of a content node in CRX. The path corresponds to the JCR path of the node, and the extension indicates the type of rendition that you are interested in:

For example:

For some renditions, you can specify additional selectors in the URL to get a more specific rendering, for example by adding the .1 selector to the JSON rendition, you can instruct the rendering script responsible for this rendition to render the resource itself, as well as one level of child nodes:

A txt (text) rendition displays basic information about the node including the node's path, metadata, type, and properties.

For example, to access the content node on your local copy of CRX, type the following in the web browser address bar:

The web browser displays the following information:

An HTML rendition displays basic information about the node including the node's path, metadata, type, and properties.

For example, to access the content node on your local copy of CRX, type the following in the web browser address bar:

The web browser displays the page in HTML format:

A JSON rendition of content provides its representation in JavaScript Object Notation, a lightweight data interchange format especially suited for developing web applications. The JSON rendering displays information that is similar to what you would see in the metadata. 

For example, to request a JSON representation for the /content node on your local copy of CRX, type the following in the web browser address bar:

If the web browser - in this case Firefox - has the JSONView extension installed, it displays the page directly in the browser:

If the browser does not recognize the JSON format, it offers to download it to a file and looks like this:

When requested with an .xml extension, the resource is rendered as XML directly in your browser.

For example, to request an xml representation for the /content node on your local copy of CRX, type the following in the web browser address bar:

The web browser displays the page in xml format:

 You can create your own custom renditions of JCR resources. See examples of how to do it here:

• Create a "print" rendition of a blog page or an "RSS Feed" rendition of the latest entries in a simple blog example.
• Understanding how script URLs are resolved in Sling blog post helps you understand the details of Sling script resolution.
• Rendering content as PDF + XFDF blog post shows you how to render content as a PDF document.
• Rendering content as CSV blog post shows you how to render content as CSV.
  
• Rendering content as HTML and SVG blog post shows you how to render content as HTML and SVG.
  
• There are also various posts on the dev.day.com blog about using CRX content from various programming languages or products, including Open Office, Adobe Acrobat, and others.

Working with different renditions is but one of the many aspects of Sling application development. Follow the information and code examples in First Steps with CRX to learn the basics of Sling application development using CRX development tools.

The CRX web application supports access to the content using HTTP. It is not as comprehensive and extensive as the recommended RESTful access using CRX's CQ5 Platform components (Apache Sling) as described in the preceding sections, but it is documented here for the sake of completeness.

The CRX web application (/crx) returns the following information if you request an item (node or property) via HTTP:

• If you request a property, CRX returns the property.
• If you request a node that has a primary item, CRX displays the primary item.
• If you request a node that does not have a primary item, CRX displays a list of the sub items.

You can access nodes, files, and folders via the CRX web application itself.

To find the path to a node, proceed as follows:  

1. Open the CRX content explorer.

2. In the node list (left), click the node you want to access via HTTP.

3. In the node properties pane (lower right), the Path shows the path to the node (without the CRX Web application path).

4. Click the path to open it in the browser. The browser address bar shows the full path (including the CRX Web application path).

To find the path to a property:  

1. Find the page to the node (see previous procedure).

2. Add the property name to the node path.

The HTTP access works well for nodes of the type file and folder. For folders, it displays a list of the folder content (that you can click), and for files, it displays the file content.  

This means that files are folders are displayed and work like the HTTP view of an FTP directory, or like other Web folders.

Most operating systems provide some kind of access to the file system. CRX supports this file system integration, so you can access files and folders through CIFS and WebDAV.

WebDAV access lets you display and edit the repository content. Setting up WebDAV gives you direct access to the content repository through your desktop. Office and PDF files that are dropped into the repository through the WebDAV connection are automatically full-text indexed and can be searched with the standard search interfaces through the standard Java APIs.

CIFS is a Microsoft-based network file sharing system that CRX can use to give you direct access to the content repository through the desktop. It is similar to WebDAV.