Repositories and Workspaces
At the core of the specification is the concept of the repository. A repository contains any number of workspaces. While a simple repository usually only contains one workspace, a repository can contain any number of workspaces. A workspace is essentially a view into the repository. The same content items may appear in multiple workspaces, some content items may only be present in one workspace. Workspaces can be thought of work-in-progress areas of a repository, much like a scrapbook. Content is always created in a workspace and may then be propagated into another workspace.
There are many potential uses for multiple workspaces. For example, one can use workspaces in a similar way to branches in a source control system (even though as we will see later, the JCR provides versioning separately). A group of content editors work locally in a workspace and when their work is completed, the finished work can be submitted into a central workspace.
Workspaces could potentially also be used to differentiate between in-progress, QA, and live environments, where changes are propagates from one workspace to the other as they go through the editorial workflow.
Let’s consider the following example. A repository contains two workspaces, Workspace 1 and Workspace 2. Both work spaces contain the common content nodes 00,01,02, and 04. Both work spaces contain new nodes which are not present in the other (05 and 03). Since we have not formally defined the notion of a content node yet, think of the nodes as web pages on a web site for now.
The JCR provides a Java API within the package javax.jcr. The main entry point is through the class Repository which allows the caller to query the repository for its capabilities as well as to obtain a session to interact with the content. The JCR defines two levels of features. The level 1 repository is a read-only repository which allows the retrieval and traversal of content, export to XML, querying the content, as well as introspection of the defined content types. A level 2 repository further adds the capability of writing content back to the repository. Either repository may support a variety of optional features. Whether a vendor supports these advanced features can be queried via the method Repository.getDescriptor, as this following example illustrates using the Apache Jackrabbit’s TransientRepository implementation:
The Repository provides method to log in to the repository using credentials and an optional workspace name and yields a Session object. The Session object is then bound to these credentials and workspace, i.e. a session cannot span multiple workspaces.
The JCR does not provide methods to manage workspaces (such as adding and removing), these are specific to the repository implementation being used. The JCR further does not provide methods for managing users or managing authentication and authorization (e.g. content access permissions); While JSR 170 provides a basic API check whether permissions are present on given content, JSR 283 greatly improves on the feature set in this area as we will later see.
The following code creates a simple JackRabbit repository, obtains a session and queries the default workspace for its name: