The following pages contain a primer on the Java Content Repository specification. In about July of ’08 I decided it would be awesome to write a book about object-oriented content architectures. Aside an impressive outline, I wrote a lot of the basic introductory chapters. Then life caught up with me. So while I might finish the rest of my book some day, I decided that I should take the JCR part as a primer on the Java JSR 170 and JSR 283 specifications. There are just no in-depth manuals out there that I have seen.

This guide is divided into two parts. Firstly, the actual deep dive on the JSR with lots of example code. Secondly, separate for reference, a summary of the Compact Node Definition language: CND in a nutshell.

JCR Overview

JSR170, the Java Content Repository, constitutes an extremely complex specification. The successor, JCR 2.0 / JSR 283, specification adds even more complexity. However, the JCR REPRESENTS a very generic and object-oriented content repository which touches almost all features known in the space. The content repository is not a full-fledged content management system or a content management API. It is only the small subset of a content repository, a storage engine, which a content management system can be built on top of. In summary, the major features set are as follows:

Content type definition

The JCR allows the developer to define a flexible object-oriented node type schema which uses a pre-defined number of property types which can be assigned as properties to node types. The JCR has built-in support for a variety of node types such as String, Binary, and Reference properties. The latter provides a mechanism to model references between nodes, keeping referential integrity intact across move, delete, and copy operations. Mixin types provide a flexible way to add fields and semantics to nodes as part of the node type definition or on the fly.

Read more details in the CND in a nutshell guide.

Content storage and discovery (via browsing and querying)

Content is stored as a graph of typed nodes, adhering to the defined node type schema. A node is defined to have properties as well as child nodes. Each node is defined to have exactly one parent node, i.e. there can be no inaccessible (orphan) nodes in the repository. JSR 283 further introduces the concept of shareable nodes which allows multiple paths of access to a node, providing the ability to implement faceted navigations through content.

Content can be browsed through the API, starting with the root node and its child nodes. A more elegant way to browse through the entire repository, or a subtree thereof, is the built-in support for the visitor pattern.

The query manager allows the programmer to write queries in XPath or SQL expressions which are then executed against the repository.

Observation through events

In a repository which supports observation, every action, such as adding nodes or changing properties, translates to an event. Workspace-wide event listeners can be registered to record all changes. JSR 283 further introduces the concept of journaled listeners which can ask the repository to re-play all events after a certain timestamp.

This event-based architecture allows the easy integration of third-party systems which are kept up to date as the repository content changes.


A repository which supports versioning provides a plethora of options to version nodes and their properties throughout the content lifecycle. A version history may be tracked which allows archival and rollback to previous versions.


Nodes may be locked for exclusive access by a user.


JSR 170 utilizes JAAS for authentication. Authorization is not explicitly outlined, the specification leaves it up to the repository vendor to implement a specific permission model. While the API defines a rudimentary permission check for node operations, there is no way to set permissions based on users, groups, and roles. JSR283 greatly improves in this area.

XML import and export

XML import and export are natively built into the specification, easily allowing the integration of other software components.


Jump on the the next section and dive straight into the details:

>> The Java Content Repository Deep Dive

>> CND in a Nutshell

Further Resources

The following links might be helpful:

>> Apache JackRabbit: An Open Source Implementation of the JSR

>> JSR 170 API Documentation