ModeShape Guide-v5-20150918_1708

8/17/2019 ModeShape Guide-v5-20150918_1708

1/423

ModeShape 3

JBoss Community Documentation Page of 1 424

ModeShape Guide

Exported from at 2015-09-18 17:08:06 EDTJBoss Community Documentation EditorCopyright 2015 JBoss Community contributors.

https://docs.jboss.org/author/display/MODEhttps://docs.jboss.org/author/display/MODE


2/423

ModeShape 3


Table of Contents1 Introduction to JCR __________________________________________________________________ 8

1.1 Why use a repository _____________________________________________________________ 81.1.1 Lots of choices for storing data _______________________________________________ 91.1.2 What are repositories good at? _______________________________________________ 91.1.3 What are repositories bad at? _______________________________________________ 121.1.4 What kinds of applications use repositories? ____________________________________ 13

1.2 Concepts _____________________________________________________________________ 131.2.1 Repository ______________________________________________________________ 141.2.2 Workspace and Sessions ___________________________________________________ 141.2.3 Node, children, names, and paths ____________________________________________ 151.2.4 Node types and mixins _____________________________________________________ 191.2.5 Events _________________________________________________________________ 231.2.6 Queries _________________________________________________________________ 23

1.3 Features _____________________________________________________________________ 251.3.1 Discovering support _______________________________________________________ 27

1.4 Repository and Session _________________________________________________________ 271.4.1 Getting a Repository ______________________________________________________ 281.4.2 Getting a Session _________________________________________________________ 291.4.3 Making and persisting changes ______________________________________________ 321.4.4 Logging out _____________________________________________________________ 32

1.5 Reading content _______________________________________________________________ 321.6 Writing content ________________________________________________________________ 321.7 Workspace operations ___________________________________________________________ 321.8 Defining custom node types ______________________________________________________ 32

1.8.1 Compact Node Definition (CND) _____________________________________________ 331.8.2 CND example ____________________________________________________________ 381.8.3 Built-in node types ________________________________________________________ 401.8.4 Registering custom node types ______________________________________________ 40

1.9 Query languages _______________________________________________________________ 421.9.1 Query grammars _________________________________________________________ 42

1.9.2 Query API _______________________________________________________________ 421.9.3 Creating a query __________________________________________________________ 441.9.4 Executing the query _______________________________________________________ 441.9.5 Use the query results ______________________________________________________ 44

1.10 Using JTA Transactions _________________________________________________________ 481.10.1 EJBs with container-managed transactions _____________________________________ 491.10.2 EJBs with bean-managed transactions ________________________________________ 511.10.3 Explicit JTA transactions ___________________________________________________ 51

1.11 Patterns and Best Practices ______________________________________________________ 531.11.1 Use unstructured primary types ______________________________________________ 53

1.11.2 Storing files and folders ____________________________________________________ 531.11.3 Mixin characteristics with mixins _____________________________________________ 61


3/423

ModeShape 3


1.11.4 Prefer hierarchies _________________________________________________________ 611.11.5 Sessions in web applications ________________________________________________ 621.11.6 Verify supported features ___________________________________________________ 631.11.7 Import and export _________________________________________________________ 641.11.8 Sessions and Listeners ____________________________________________________ 64

2 Introduction to ModeShape ___________________________________________________________ 672.1 Architecture ___________________________________________________________________ 67

2.1.1 ModeShape engine _______________________________________________________ 672.1.2 Repository configuration ___________________________________________________ 682.1.3 Clustering _______________________________________________________________ 682.1.4 Modules ________________________________________________________________ 68

2.2 Authentication and authorization ___________________________________________________ 722.2.1 Authentication and authorization _____________________________________________ 732.2.2 Access controls __________________________________________________________ 75

2.3 Backup and restore _____________________________________________________________ 782.3.1 Getting started ___________________________________________________________ 792.3.2 Introducing the RepositoryManager ___________________________________________ 792.3.3 Creating a backup ________________________________________________________ 822.3.4 Restoring a repository _____________________________________________________ 832.3.5 Migrating from ModeShape 2.8 to 3.0 or 3.1 ____________________________________ 832.3.6 What's in the backup? _____________________________________________________ 84

2.4 Binary values __________________________________________________________________ 842.4.1 How it works _____________________________________________________________ 842.4.2 Extended Binary interface __________________________________________________ 872.4.3 Importing and Exporting ____________________________________________________ 892.4.4 Implementation design _____________________________________________________ 892.4.5 Configuring Binary Stores __________________________________________________ 962.4.6 Files and Folders _________________________________________________________ 97

2.5 Clustering ____________________________________________________________________ 972.5.1 Local ___________________________________________________________________ 982.5.2 Replicated ______________________________________________________________ 982.5.3 Invalidation _____________________________________________________________ 1012.5.4 Distributed _____________________________________________________________ 1012.5.5 Remote ________________________________________________________________ 103

2.5.6 How to ________________________________________________________________ 1032.6 Configuration _________________________________________________________________ 103

2.6.1 Infinispan Configuration ___________________________________________________ 1042.7 Content grid __________________________________________________________________ 1062.8 Federation ___________________________________________________________________ 106

2.8.1 Concepts and terminology _________________________________________________ 1062.8.2 How it works ____________________________________________________________ 1102.8.3 Current connectors _______________________________________________________ 113

2.9 Initial Content ________________________________________________________________ 1132.9.1 XML Format ____________________________________________________________ 114

2.9.2 Configuring Initial Content _________________________________________________ 1152.10 Large numbers of child nodes ____________________________________________________ 115


4/423

ModeShape 3


2.10.1 Accessing by path _______________________________________________________ 1172.10.2 Iterating _______________________________________________________________ 1172.10.3 Accessing by identifier ____________________________________________________ 1172.10.4 Additional performance considerations _______________________________________ 117

2.11 MIME types __________________________________________________________________ 1172.12 Monitoring ___________________________________________________________________ 117

2.12.1 Public API ______________________________________________________________ 1182.12.2 Examples ______________________________________________________________ 123

2.13 Public API ___________________________________________________________________ 1262.14 Query and search _____________________________________________________________ 126

2.14.1 Choosing a query language ________________________________________________ 1272.14.2 Creating queries _________________________________________________________ 1282.14.3 Executing queries ________________________________________________________ 1292.14.4 JCR-SQL and JCR-SQL2 extensions ________________________________________ 1302.14.5 Query Object Model extensions _____________________________________________ 1302.14.6 Search and text extraction _________________________________________________ 149

2.15 Registering custom node types ___________________________________________________ 1492.15.1 Registering using the standard API __________________________________________ 1492.15.2 Registering using CND files ________________________________________________ 1492.15.3 Jackrabbit XML format ____________________________________________________ 152

2.16 Sequencing __________________________________________________________________ 1522.16.1 Sequencers ____________________________________________________________ 1542.16.2 Built-in sequencers _______________________________________________________ 1552.16.3 Custom sequencers ______________________________________________________ 1572.16.4 Configuring a automatic sequencer __________________________________________ 1572.16.5 Waiting for automatic sequencing ___________________________________________ 161

3 Using ModeShape _________________________________________________________________ 1643.1 Deploying to web and app servers ________________________________________________ 164

3.1.1 RepositoryFactory and configuration files _____________________________________ 1643.1.2 RepositoryFactory and JNDI _______________________________________________ 1643.1.3 Lookup Repository in JNDI ________________________________________________ 1643.1.4 Lookup Repositories in JNDI _______________________________________________ 166

3.2 ModeShape in Java applications __________________________________________________ 1693.2.1 The ModeShape Engine __________________________________________________ 170

3.2.2 Use RepositoryFactory and the JCR API ______________________________________ 1763.2.3 Configuring repositories ___________________________________________________ 178

3.3 ModeShape and JBoss AS7 and EAP _____________________________________________ 1903.3.1 JBoss AS7 or EAP? ______________________________________________________ 1913.3.2 Getting started __________________________________________________________ 1913.3.3 Installing ModeShape into EAP _____________________________________________ 1913.3.4 Configuring ModeShape in EAP ____________________________________________ 1963.3.5 Using Repositories with JCR API in EAP ______________________________________ 2123.3.6 Using Repositories with REST in EAP ________________________________________ 2213.3.7 Using Repositories with WebDAV in EAP _____________________________________ 223

3.3.8 Using Repositories with JDBC in EAP ________________________________________ 2273.3.9 Administering Repositories in JBoss EAP _____________________________________ 229


5/423

ModeShape 3


3.4 ModeShape in web applications __________________________________________________ 2403.4.1 ModeShape's JCA Adapter ________________________________________________ 240

3.5 ModeShape's REST Service _____________________________________________________ 2433.5.1 REST Service 2.x ________________________________________________________ 2433.5.2 REST Service 3.x ________________________________________________________ 249

4 Query language grammars __________________________________________________________ 2724.1 JCR-SQL2 ___________________________________________________________________ 272

4.1.1 Extensions to JCR-SQL2 __________________________________________________ 2744.1.2 Extended JCR-SQL2 Grammar _____________________________________________ 2754.1.3 Full-text search grammar __________________________________________________ 3004.1.4 Example JCR-SQL2 queries _______________________________________________ 300

4.2 JCR-SQL ____________________________________________________________________ 3064.2.1 Grammar ______________________________________________________________ 308

4.3 XPath _______________________________________________________________________ 3094.3.1 Column Specifiers _______________________________________________________ 3104.3.2 Type Constraints ________________________________________________________ 3114.3.3 Property Constraints _____________________________________________________ 3114.3.4 Path Constraints _________________________________________________________ 3124.3.5 Ordering Specifiers ______________________________________________________ 3154.3.6 Miscellaneous __________________________________________________________ 316

4.4 JCR-JQOM __________________________________________________________________ 3164.5 Full text search _______________________________________________________________ 318

4.5.1 Grammar ______________________________________________________________ 3205 Built-in node types _________________________________________________________________ 321

5.1 Standard node types ___________________________________________________________ 3215.2 ModeShape built-in node types ___________________________________________________ 324

6 Built-in sequencers ________________________________________________________________ 3276.1 Compact Node Type (CND) files __________________________________________________ 3276.2 DDL files ____________________________________________________________________ 3296.3 Image files ___________________________________________________________________ 3336.4 Java source and class files ______________________________________________________ 334

6.4.1 Node Structure __________________________________________________________ 3346.4.2 Java Source File Sequencer _______________________________________________ 3366.4.3 Java Class File Sequencer ________________________________________________ 338

6.5 Microsoft Office files ___________________________________________________________ 3386.6 MP3 files ____________________________________________________________________ 3426.7 Teiid Relational Models _________________________________________________________ 3436.8 Teiid Virtual Database (VDB) files _________________________________________________ 3436.9 Text Files ____________________________________________________________________ 3436.10 Web Service Definition Language (WSDL) files ______________________________________ 3456.11 XML files ____________________________________________________________________ 3556.12 XML Schema Document (XSD) files _______________________________________________ 3586.13 ZIP files _____________________________________________________________________ 369

7 Built-in connectors _________________________________________________________________ 372

7.1 File system connector __________________________________________________________ 3727.2 Git connector _________________________________________________________________ 377


6/423

ModeShape 3


7.3 CMIS connector _______________________________________________________________ 3797.4 JDBC Metadata Connector ______________________________________________________ 383

8 Built-in text extractors ______________________________________________________________ 3878.1 Tika text extractor _____________________________________________________________ 387

9 Extending ModeShape _____________________________________________________________ 3889.1 Custom authentication providers __________________________________________________ 388

9.1.1 The AuthenticationProvider interface _________________________________________ 3889.1.2 The AuthorizationProvider interface __________________________________________ 3919.1.3 The AdvancedAuthorizationProvider interface __________________________________ 3919.1.4 Putting it all together _____________________________________________________ 3949.1.5 Configure a repository to use your provider(s) __________________________________ 395

9.2 Custom sequencers ___________________________________________________________ 3959.2.1 The Sequencer framework _________________________________________________ 3969.2.2 Creating a new sequencer _________________________________________________ 398

9.3 Custom text extractors _________________________________________________________ 3989.3.1 The text extraction framework ______________________________________________ 3999.3.2 Creating a new sequencer _________________________________________________ 401

9.4 Custom connectors ____________________________________________________________ 4019.4.1 The Connector framework _________________________________________________ 4029.4.2 Creating a custom connector _______________________________________________ 414

10 Tools for Eclipse __________________________________________________________________ 41510.1 Installation ___________________________________________________________________ 41510.2 Compact Node Definition (CND) editor _____________________________________________ 415

10.2.1 Header Section _________________________________________________________ 41610.2.2 Namespaces Section ____________________________________________________ 41710.2.3 Node Types Section _____________________________________________________ 41710.2.4 CND Preference Page ___________________________________________________ 421

10.3 ModeShape publishing tool ______________________________________________________ 42110.3.1 Configuration ___________________________________________________________ 42210.3.2 Publishing ______________________________________________________________ 422

10.4 Want to help? ________________________________________________________________ 424


7/423

ModeShape 3


This guide is intended for users of ModeShape. Browse the child pages for more information on each topic.


8/423

ModeShape 3


1 Introduction to JCRThe "Content Repository for Java™ Technology API, Version 2.0" specification (also known as ) JSR-283defines a set of concepts (or abstract model) and a standard Java programming interface (or API) forworking with "content" stored in any compliant implementation. Applications use the API to navigate, change,create, query, version, import, export, lock and observe content.

This document provides an introduction to the JCR API and its core concepts, and can be used byapplication developers who are learning the standard API and who are developing applications that use theJCR API.

For the most part, this document describes how to use the JCR API without using anyimplementation-specific behaviors. This is a testament to the completeness of the JCR API. However, this

document does try to call out where the behaviors of implementations are allowed to vary.

1.1 Why use a repositoryBefore we can explain why you might want to use a repository, we first need to state the obvious:applications have different data requirements, and no one data storage solution will fit all applications. Sowhile most of the applications you've worked on probably used relational databases, the truth is that arelational database is often not the best fit. And once you understand the sweet spot of repositories, you canmake an informed decision about whether repositories make sense for your application.

Lots of choices for storing dataWhat are repositories good at?What are repositories bad at?What kinds of applications use repositories?

http://www.jcp.org/en/jsr/detail?id=283http://www.jcp.org/en/jsr/detail?id=283


9/423

ModeShape 3


1.1.1 Lots of choices for storing dataApplication developers have a lot of options for persisting their application's data. Choices over the years

have included a variety of databases, including relational, network, graph, object, document, XML, andhybrids. While relational databases have certainly been the norm for many years, more recently there hasbeen a lot of interest in alternative databases that have different characteristics and features than traditionalrelational databases. Much of this interest has its origins in several trends, including:

installing databases on larger numbers of smaller hardware (scale out)storing very large amounts of datastoring simple data structures, such as simple JSON documentsusing the (sometimes multiple) natural hierarchies in datalooking up data by keys rather than using queries

searching for data based upon relevance rather than criteriamap-reduce patterns for distributing data operations in parallel across all the dataevolving schemas and/or data structuresservices that access/store only one kind of datacaching data in-memory for performancegiving up consistency guarantees for increased availability

Relational databases are less suited for applications with these needs. For example, large relationaldatabases are usually installed on large, very capable hardware, and are difficult to configure and use withlarge clusters. Also, in many situations described above, relational databases are simply overkill because

few of the features are used, or because they lack features that are required.

And while early adopters of "NoSQL" databases advocated avoiding relational databases, it is now muchmore widely understood that each type of database system has advantages, features, and sweet spots thathave to be understood and matched to the application and operational requirements. Even relationaldatabases have their sweet spot, including:

finding data based on ad hoc queries with various (even user-defined) criteriaaggregate operations (e.g., sum, average, min/max, etc.)transactional guaranteessimplified updates of (normalized) dataconstrained data structure (schema) independent of applicationwell-understood operational behaviorsused by many installed applications

In short, don't pick a database system just because you used it on your last application or because its newand you want to use it on your new application. Figure out what your application needs, and pick the datastorage solution that best satisfies those needs.


10/423

ModeShape 3

JBoss Community Documentation Page of10 424

1.1.2 What are repositories good at?No single data storage technology is good at all the data usage patterns described above. So let's examine

what kind of data and access patterns repositories are very good at handling.

- Some kinds of data are naturally hierarchical, and repositories enable you to useHierarchical datathis hierarchy as an asset. A few examples include: ZIP codes partition the US geographically; the

breaks knowledge into 10 main classes, which are thenDewey Decimal classification schemesubdivided into 10 divisions, which are then divided into 10 sections; merchandise is often classifiedusing various categories or taxonomies; temporal and historical data is often naturally stored in ahierarchy based on time; physical products and assemblies are composed of parts and otherassemblies, forming natural hierarchies; metadata is often structured assemblies of components thatdescribe other components. Other kinds of data are not inherently hierarchical, but have

characteristics that enable you to easily treat them as such. For example, cryptographic hashfunctions like are well distributed even in the first few bits of the hash, so a hierarchy canSHA-1easily be created by segmenting the first few pairs of characters of the hexadecimal form of thehashes. Repositories can very naturally manage this kind of data, whereas other data storagetechnologies require you to jump through complex and non-trivial hoops. There are thatentire booksdescribe the multiple ways (none of which are ideal in all cases) to store trees and hierarchies inrelational databases.

- JCR repositories are very good at storing files right alongside your other data. In fact,File storageyou can store quite a bit of metadata about the files you're storing, and some JCR repositories (likeModeShape) can automatically determine the SHA1 hash and the MIME type for your files.

- Any data stored in a hierarchy can be identified by the path in thatNavigation-based accesshierarchy. Often applications that deal with hierarchical data need to work with subsets of thehierarchy, and thus navigate to a particular location and deal with the subgraph of data below thatnode. This form of navigation-based access is a natural advantage of repositories.

- Above all else, JCR is a programming interface for Java (and other JVMProgrammatic APIlanguages) to interact with content repositories independently from how those repositories areimplemented. Thus, the API defines all the useful components necessary to create, read, update,delete, observer, version, relate, and query the persisted content. And while you can write yourapplication to use this API, under the covers the repository may support various data storage options,clustering and scaling options, federation capabilities, and other features designed to add value toyour application's data management needs.

- Repositories do not require your data structure to be designed a priori.Flexible data structureInstead, you can start storing your data, yet allow additional kinds of information to be stored as theneed arises over time. Plus, not all similar data need be treated identically. Consider how anapplication might use user-defined tags. Tags might apply to many different kinds of data, yet withJCR's you can enable a particular piece of data to become a holder of tags only when usersmixins want to apply tags to it. JCR repositories give tremendous flexibility to your data needs, allowing yourdata to vary while evolving over time as needs change.

http://en.wikipedia.org/wiki/Dewey_Decimal_Classificationhttp://en.wikipedia.org/wiki/SHA-1http://www.amazon.com/Hierarchies-Smarties-Kaufmann-Management-Systems/dp/1558609202http://www.amazon.com/Hierarchies-Smarties-Kaufmann-Management-Systems/dp/1558609202http://en.wikipedia.org/wiki/SHA-1http://en.wikipedia.org/wiki/Dewey_Decimal_Classification


11/423

ModeShape 3


- Flexible data structures are often very useful, but sometimes your applicationsRigid data structureneed more control. JCR repositories let you choose how constrained your data should be. You canensure that only specific properties are used, with values that fit specific constraints. If you want, youcan start out with these restrictions or you can add them over time. With JCR, you're in control.

- JCR supports multiple query languages, ranging from hierarchically orientedSearching for datalanguages like XPath, to highly structured set-oriented languages like JCR-SQL2, to veryunstructured that enable full-text search.

- Receive notifications when content is changed. use filters to simplify identifying theObserving dataparticular cases your interested in.

- Ensure that changes made by a session are either all persisted, or that none of theTransactionschanges are persisted. Plus, integrate with the Java Transaction API (JTA) and J2EE to makechanges to your repositories within container-managed transactions in your applications.

- JCR defines a built-in mechanism for versioning the changes made to single nodes orVersioningentire subgraphs. An application simply marks a node as being versionable, and from that pointforward the repository automatically tracks the changes by recording the snapshots of the versionablesubgraph. The version history of the versionable nodes is easily accessible through the standard API,allowing the application to access this history and roll back the versionable content to a prior state.

- The JCR API defines a mechanism for temporarily locking a single node or an entireLockingsubgraph to prevent others from modifying or removing that content. This of course works across allof the clients using the repository, making it easy for applications to take advantage of this built-incapability.

- JCR references that allow one node to refer to one (or more) other nodes, allowingReferenceseasy navigation from the referring node to the referenced node.

- JCR defines two styles of references: strong references require thatReferential integrity

referenced nodes not be removed, whereas weak references do not prevent removal of thereferenced nodes.


12/423

ModeShape 3


1.1.3 What are repositories bad at?In the previous section we talked about what repositories are good at, and in this section we'll cover some of

the kinds of data and access patterns that JCR repositories are less capable of doing well. If your applicationuses data in these ways, you might consider using something other than a repository.

- Content repositories work very well with hierarchically structured data. AndFlat, unorganized datawhile we think most data have hierarchical nature, not all data does. And content repositoriesdoes are far less capable of handling of data.very large amounts flat, non-hiearchically organized

- Relational databases support inserting, updating and deleting data viaBulk declarative updatedeclarative statements. JCR provides no such facility, and all inserts and updates must be done viaimport or direct manipulation of nodes via stateful sessions. However, removing a node removedoes all descendants.

- As mentioned above, JCR repositories very good at storing files,Massively large file storage are and can even store massively large files (e.g., many GB or more). However, you may have verycritical performance requirements or highly-optimized infrastructure for delivering such gigantic files toclients, and perhaps the Java streaming mechanism used by the JCR API may not be ideal. In thatcase, you may want to consider storing such massive files outside of the repository while storinginside the repository the metadata and location for that file. So in short, JCR repositories may work forlarge files, but be sure to test and evaluate a content repository before committing to it.

- The JCR API is a standard Java programming interface, so byAccess by non-JVM languagesdefinition it can only be used by languages running on the JVM. However, many content repositories(including ModeShape) do offer non-Java APIs, such as REST, WebDAV and/or CMIS.

- Although JCR can version content, the structure of the versionComplex merging of versionshistory is relatively limited, and the built-in functionality for merging is not terribly sophisticated. Youmay find it more effective to create your own versioning mechanism on top of JCR. Or, if you havevery complex versioning requirements and are dealing with mostly files, then perhaps other fileversioning systems (e.g., Git) may be a better fit.


13/423

ModeShape 3


1.1.4 What kinds of applications use repositories?Below are some categories of applications for which content repositories are a good fit.

- Content management systems (CMS) and web contentContent management systemsmanagement systems (WCM) allow users to easily create and change the information used on websites and other information systems. So storing information in a hierarchical manner that mirrors thestructured web site and the XHTML files allows such systems to easily manage and serve theinformation.

- Storing and versioning documents and associated metadata is somethingDocument repositoriesrepositories do very well, and so they're often used within document management systems.

- Systems that store artifacts (files that are the output of some process andArtifact repositoriesused by other systems) often use repositories. For example, several Maven repository systems use

JCR for storage of the artifacts and metadata, and rely upon not only the direct navigational accessbut also query and search.

- Repositories are a great fit for applications or systems that govern theGovernance systemslifecycle of artifacts, services, and files. Such applications typically need to store a wide variety ofmetadata with each governed artifact, and often this metadata changes as the lifecycle process ischanged.

- Configuration information usually consists of structured files (e.g.,Configuration managementXML, YAML, JSON, etc.). A JCR repository can provide a more formal way to manage and versionmultiple configurations. Plus, JCR's event system allows easy notification of configuration changes,while versioning can help guarantee the ability to revert back to a previous (valid) configuration.

- Repositories provide an excellent way to store the varied and changingKnowledge systemsinformation managed by knowledge management systems. Such systems also require search,references, referential integrity, and versioning capabilities.

1.2 ConceptsIt's important to understand the central concepts used within the JCR API. This section presents an overviewof these concepts, but for a more thorough description see the .JCR 2.0 specification

RepositoryWorkspace and SessionsNode, children, names, and paths

Properties and valuesNode types and mixinsEventsQueries



14/423

ModeShape 3


1.2.1 RepositoryA is a single, self-contained persistent store of information plus the software that is used to accessrepository

and update that information. Each repository contains an area for system-wide information and versionstorage, and separate areas for its workspaces.

A repository is represented in software with the interface, which defines:javax.jcr.Repository

methods to authenticate and obtain a session (or connection) to the repositorymethods to obtain the set of features supported by the repositoryconstants used to identify the various repository features

There are multiple ways that your application can obtain a instance. The easiest is to simplyRepository

look it up in JNDI, although this obviously only works if your application is running in an environment that hasJNDI support. But another technique is to use Java's to look up theServiceLoader

implementations, and use them to ask for a repository given a set ofjavax.jcr.RepositoryFactory

parameters; the first factory to understand the parameters will return a instance:Repository

Map parameters = ...

Repository repository = null;

for (RepositoryFactory factory : ServiceLoader.load(RepositoryFactory.class)) {

repository = factory.getRepository(parameters);

if (repository != null) break;

}

The parameters are unique to the JCR implementation, but you can keep them outside of your codebase bysimply reading them in from a properties file. For more details and other options, see the Repository and

page.Session

1.2.2 Workspace and SessionsEach repository is divided into separate named , and it is within these workspaces that allworkspaces content is stored as a tree-structure of nodes. The top of that tree structure is the root node (named "/"), and

all nodes in the tree are accessible via navigation, lookup by unique identifier, or via query result.

Accessing and updating the content within a workspace requires establishing a obtained bysession authenticating with the repository. Generally speaking, sessions are intended to be short-lived, meaning thatclients will create a session, use the session to read or update content, save the session's transientchanges, and then close the session. However, the only way to access or update any repository content isthrough an authenticated session.

When using a session to read content, all of the nodes reflect the persisted state of the workspace. So asthe persisted state changes, all sessions immediately see the updated content. This means that as a client

uses a session, the content accessible by that session may be changing if other sessions are makingchanges to the content.


15/423

ModeShape 3


Sessions are also used to update content. Each session maintains the transient set of changes overlaid ontop of the persisted state, and these transient changes are persisted only when the session is saved. (When

, the session must still be saved, but the changes are persisted only when the transactionusing transactionsis committed.)

The JCR API defines the interface to represent a session, and it's created to accessjavax.jcr.Sessionand change the content of a single persistent workspace. The interface tojavax.jcr.Workspace

represent a persistent workspace, and contains methods that modify or copy content (including from otherworkspaces). Each object has its own distinct instance, since ensure that theSession Workspace

session's authorizations are respected. (This is why objects are not shared.)Workspace

Let's look at a very simple example that shows the basics for obtaining a and :Session Workspace

Repository repository = ...

// Create a session by logging in. There are multiple forms of 'login(...)',// but we'll use the one that just specifies the workspace name ...

Session session = repository.login(workspaceName);

// Obtain the session's workspace ...

Workspace workspace = session.getWorkspace();

// Note how the workspace is owned by the session ...

assert session == workspace.getSession();

// And we can always get back to the repository, too ...

assert repository == session.getRepository();

// Work with your content ...

// Eventually log out ...

session.logout();

1.2.3 Node, children, names, and pathsThe content of each workspace is organized as a tree of : at the top of the tree is a single root node,nodes and every node can contain multiple child nodes. Every node has a and a unique identifier, and canname also be identified by a containing the names of all ancestors, from the parent to the node itself. Namespath are comprised of a namespace and local part, and there is a namespace registry to centralize short prefixesfor each namespace.

Generally, all of the children of a single node are uniquely named, and this is considered a best-practice.However, this is not required, and it is possible (and desirable in some use cases) for a single parent node tohave multiple child nodes with the same name. In these cases, the (SNS) aresame-name siblings distinguished by including a 1-based in the path. The index simply identifies the order of theSNS index SNSs, so inserting, reordering, or removing children may alter the SNS index of a particular node, effectivelychanging the node's path.


16/423

ModeShape 3


Let's consider a sample repository that stores information about various assets of a fictional company. Thisis of course just one possible repository design to showcase the capabilities and features of JCRrepositories:

We've kept it simple: none of these nodes uses SNS indexes, since there are no two children with the samenames. But even with this simple example you can see how a hierarchical structure naturally organizes thedata in such a way that makes navigating to relevant data very straightforward. For example, our assetrepository breaks down the assets into " ", " " and " ", and each of those isvehicles equipment facilities

further segmented into smaller divisions. The " " assets are divided into " ", " ",vehicles cargo passenger

and " " vehicles, and under each of those are all of the vehicle nodes named with their Vehicletransit

Identification Number (VIN).

(We could have alternatively designed the repository without the " cargo ", " passenger ", and " transit "

layer, and tracked that information as properties on the nodes. But since any given vehicle is only one of these types, including the layer has advantages.)

The " " area stores information about computer assets, office equipment, etc., while the "equipment

" area stores information about the buildings used or owned by our company.facilities

So with this cursory overview of our sample repository, let's look at some code that shows just a few of theways to navigate our repository structure:


17/423

ModeShape 3


Repository repository = ...

Session session = repository.login("assets");

Node root = session.getRootNode();

// Find a node by absolute path ...Node nyc = session.getNode("/facilities/NYC");

// Or find a nodes by relative path ...

Node cargo = root.getNode("vehicles/cargo");

Node veh1 = cargo.getNode("JF2SH636X9G700001");

Node transit = veh1.getNode("../../transit");

// Iterate over all children ...

NodeIterator iter = cargo.getNodes(); // implements Iterator

while ( iter.hasNext() ) {

Node child = iter.nextNode();

}

// Or iterate over some children, using name patterns ...

iter = cargo.getNodes("JF*");

while ( iter.hasNext() ) {

Node child = iter.nextNode();

}

// If we know a node's identifier ...

String nodeId = veh1.getIdentifier();

// We can find it by simply looking it up ...

Node byId = session.getNodeByIdentifier(nodeId);

// And we can always get back to the session we used to get a node ...

Session sessionForNode = byId.getSession();

assert sessionForNode == session;

There are a couple of interesting things in this example:


18/423

ModeShape 3


1.

2.

3.

4.

5.

6.

7.

You can only obtain the root node from the session (line 3). The object for the root should neverNode

change during the lifetime of the session, even when the properties and children of the objectNode

change.You can get a node by directly from the Session (line 5).absolute path You can find nodes relative to other nodes (including the root node) using (lines 9-11).relative paths Relative paths may contain " " and " " segments to signify the parent or self, respectively. Thus,.. .

JCR paths are very similar to paths on a file system path.You can iterate over all the children of a node (lines 14-17) that this session has authorization to see.Any child for which you don't have authorization just doesn't even appear to exist. Note that JSR-283was designed for JRE 1.4 (pre-generics), so it defines a interface that extendsNodeIterator

adds type-specific methods and size information. ( is updating thisjava.util.Iterator JSR-333

so that extends , though it will retain the ability to return the sizeNodeIterator Iterator

for backward compatibility.)You can iterate over of the children that have names matching one or several glob patterns (linesome 20). In this example, the names of the nodes are VIN numbers, and we can use this knowledge andthe structure of VINs to iterate over all of the passenger vehicles that were made in Japan by FujiHeavy Industries (for Subaru). We could just as easily issued a query instead, and would likely wantto if the criteria were any more complicated.Every node in the workspace has a unique but opaque identifier (line 26) assigned by theimplementation, and you can easily look up any node in the workspace using this ID (line 29). (Notethat two different workspaces in the same repository can have nodes with the same ID. These arereferred to as , and this characteristic is an important factor in deciding whethercorresponding nodes to design your repository to have one or several workspaces.)

Every node is valid only in the context of its session, and you can always get a 's Node Sessionobject (line 32). This means that your code can pass around a object (assuming theNode Session

remains open while doing so), but don't have to also pass around the .Session

One more thing about node identifiers. While all node identifiers are unique within a workspace, it is possiblefor multiple workspaces in the same repository to each have a node with a given identifier. Such nodes arecalled , and this can be a primary factor in deciding whether to design your repositorycorresponding nodes with a single workspace or several. For example, it's possible to clone a subgraph of nodes in oneworkspace into another workspace, and all these nodes will retain the same identifiers.



19/423

ModeShape 3


Properties and valuesSo far we've seen how the content in a repository workspace can be organized into a tree structure ofnodes, but we haven't yet seen how to store any data (other than node names and parent-child

relationships). In JCR, all data is stored on nodes in . Each property has a name and is eitherproperties (meaning it always has 1 value) or (meaning it has 0 or more values). Eachsingle-valued multi-valued value

is immutable and can be any of the following types:

Property Type Java type

STRING java.lang.String

NAME java.lang.String

PATH java.lang.String

BOOLEAN java.lang.Boolean

LONG java.lang.Long

DOUBLE java.lang.Double

DATE java.util.Calendar

BINARY javax.jcr.Binary

REFERENCE javax.jcr.Node

WEAKREFERENCE javax.jcr.Node

DECIMAL java.math.BigDecimal

URI java.lang.String

One really nice thing about values is that they have methods that will convert the value to a desired type.This means your applications don't have to keep track of the actual type of a value, but instead can simplyask for the value in the type your application wants. JCR defines conversions between most types (e.g.,every value can be converted to a STRING or a BINARY representation), but some conversions don't makesense (e.g., converting a path to a date) and result in an exception.

Before we look at an example, let's talk about node types and mixin types.


20/423

ModeShape 3


1.2.4 Node types and mixinsThe repository enforces the structure of the content by defining , which specify the patterns ofnode types

acceptable properties and children. Some node types can allow any combination of properties and/orchildren, while other node types can be extremely restrictive on the names and values of properties andnames and types of children. Each repository comes with a large set of predefined standard node types, butapplications can define and start using custom node types at any time. The interface exposes aWorkspace

that can be used to discover the existing node types and (with proper privileges) makeNodeTypeRegistry

changes to the set of registered node types. (Note that it may not be possible to change or remove nodetypes if they are in use by the content.)

Every node declares one and zero or more . Primary node types areprimary node type mixin node types typically used to declare the core characteristics of a node, while mixin node types are used to add (i.e., "mix

in") additional characteristics. A primary type must be assigned when the node is created, but may bechanged at a later time. Mixin types can be added to and removed from a node at any time.

Node types can use inheritance, but it is much more common to define a few concrete node types (thatmight use inheritance) and many more mixins that do no use inheritance but that can be mixed and matchedon nodes as needed.

The next table describes a few of the more commonly-used standard node types that are defined by theJSR-283 specification and available in all implementations:

Name Kind Description

nt:base primarytype

The implicit abstract base type for all node types.

nt:unstructured primarytype

A concrete node type that allows any single- or multi-valued propertiesand any children with or without same-name-siblings. This node type isfrequently used as the primary node type for nodes, coupled with mixinsto more accurately describe the sets of properties that are used on thatnode.

nt:file primary

type

A concrete node that that represents a file uploaded to the repository,

with properties describing the file's metadata and a child node used tostore the of the file.content

nt:folder primarytype

A concrete node that is often used as a container for andnt:file

nodes.nt:folder

nt:query primarytype

A concrete node type used to store a JCR query expression.


21/423

ModeShape 3


nt:address primarytype

A concrete node type that represents the location of a JCR node orproperty not just within the current repository but within the set of alladdressable repositories. It defines properties for the URL to therepository, the workspace, the path within the workspace, and the

identifier of the node within the workspace.mix:referenceable mixin

typeUsed on nodes that can be referenced directly by andREFERENCE

properties.WEAKREFERENCE

mix:created mixintype

Used on a node when the repository should add properties automaticallycapture when the node was created and by whom.

mix:lastModified mixintype

Used on a node when the repository should add properties thatautomatically capture when the node was last modified and by whom.

mix:etag mixin

type

Added to a node when the repository should created and automatically

maintain a " " property containing a value that is semanticallyjcr:etagcomparable to the HTTP/1.1 strong entity tag, and that changes onlywhen a property is added, removed or changed on the node.BINARY

The " " value can then be used by applications to quicklyjcr:etag

determine if the node has changed relative to a previously-known state.

mix:versionable mixintype

Added to a node to make it versionable using the JCR versioning API.

mix:lockable mixintype

Added to a node to make it lockable using the JCR locking API.

mix:shareable mixintype

Added to a node to make it able to be (i.e., linked) into multipleshared locations within the same workspace or into different workspaces.

mix:title mixintype

Added to a node when it should have a " " property.jcr:title

mix:mimeType mixintype

Added to a node to add properties useful for tracking the MIME typeand/or encoding.

Now that we have a cursory understanding of nodes, properties, node types, and mixins, let's continuelooking at our asset repository example. The higher-level nodes aren't terribly interesting, as they are largely

just containers with few properties on their own. So let's look at how vehicle information might be stored.Again, this is just an example of one possible repository design to showcase the capabilities and features ofrepositories.


22/423

ModeShape 3


This rendering shows several of the nodes in the " " branch and the properties on/vehicles/passenger

them. As we just learned, every node has a " " property that contains the name of thatjcr:primaryType

node's primary type. For example, the primary type of the " " is " ", whichpassenger nt:unstructured

means that it can contain any property and any child nodes (in other words, the node is not constrained by aschema). However, the " " node also has three mixins: " " is a (notional) custompassenger dot:defined

node type (for our example) that represents a particular defined DOT class, a " " (notional)acme:category

custom node type that is a marker (with no defined properties) signifying a category within our assetrepository, and the standard " " node type that enables automatic tracking of when themix:lastModified

nod was last changed and by whom.


23/423

ModeShape 3


The " " node represents a vehicle with a particular VIN, and contains a "JF2SH636X9G700001

" of " " and two mixins: the " " mixin is a (notional)jcr:primaryType nt:unstructured veh:vehicle

custom node type that signifies a vehicle with several vehicle-related properties, and the " asset:acquired

" mixin is a (notional) custom node type that signifies several properties related to when and how the assetwas acquired. The remaining properties of the " " node contain the information related to thesepassenger

characteristics.

The " " node is intended to be a container for various nodes that describe important events in theHistory

ownership history of a vehicle, including the acquisition information, maintenance activities, accidents/issues,etc.

The " " node is a container for documents, images, photos, and other files that are relevant to theDocuments

vehicle. This particular vehicle has two such documents: a JPEG photo with EXIF metadata, and a PDFdocument of the vehicles title.

1.2.5 EventsAn application can be notified of each change to the repository by registering listeners with a session. Notethat each listener will only receive events until the session with which it's registered is closed. There aresome common for properly using listeners in long-running applications.patterns

When registering a listener, the caller has the ability to specify the kinds of events that its interested in.Examples of filters include the types of events (e.g., created, modified, deleted), the location of nodes (e.g.,by path), the identities of nodes, and even the types of nodes.

1.2.6 QueriesJCR defines a powerful feature that applications can use to search the repository using a variety ofquery expression languages and even a that can be used to programmatically build a query.query object model The most powerful expression language is , which is a SQL-like language for queryingJCR-SQL2 relational-like views defined by the properties of each node type. JCR-SQL2 has support for a variety of richcriteria (including full-text matching) and multiple kinds of joins. See the for moreQuery languagesinformation about these languages, and for the detailed grammars of theQuery language grammarslanguages supported by ModeShape.

Let's continue with our example and see how we can use the query system and the JCR-SQL2 language tofind content satisfying some fairly complex criteria. First, let's imagine want to issue a simple criteria to finalall Chevrolet, Toyota and Ford vehicles. We can do this with a query that selects nodes in the "

" table (or node type), and apply the criteria against the columns (or properties) defined by theveh:vehicle

" " node type:veh:vehicle

SELECT * FROM [veh:vehicle] AS vehicle

WHERE vehicle.[veh:make] = 'Chevrolet' OR vehicle.[veh:make] = 'Toyota' OR vehicle.[veh:make] =

'Ford'


24/423

ModeShape 3


This looks very much like the SQL-99 you're probably familiar with. ModeShape even extends theJCR-SQL2 grammar to add support for " " clauses, so this is not standard JCR-SQL2 but works inIN

ModeShape:


WHERE vehicle.[veh:make] IN ('Chevrolet', 'Toyota', 'Ford')

Using the JCR API, we can walk through the results and get the tuple results (like regular SQL) or get theobject that each row represents.Node

Let's look at a more complicated example. Imagine that we want to find "large" images (greater than 100pixels wide) of all Ford vehicles acquired in 2011 or later. The images will exist as files under the "

" child of a particular vehicle, and the vehicle has the make and acquisition information. ThisDocuments

seems pretty straightforward, except that the criteria involves multiple nodes within a structural pattern.

One approach is to first issue a simple query to find all the FORD vehicles that match acquired in or after2011:


JOIN [asset:acquired] AS asset ON ISSAMENODE(vehicle,asset)

WHERE vehicle.[veh:make] = 'Ford'

AND asset.[asset :acquisitionId] > CAST('2011-01-01T00:00:00' AS DATE)

but then we have to get each node in the results and for each navigate to its " " folder and lookDocuments

for images that meet our size criteria.

Alternatively, we could issue a single (more complex) query that finds the images that satisfy all of thecriteria, and with this approach we have very little programming to do. This query will need to join three"tables":

the " " table represents all nodes that are of this particular node type, and it containsveh:vehicle

columns for the " ", " ", " ", and " " properties defined byveh:year veh:make veh:model veh:color

the " " mixin. We'll apply a constraint on the " " column with the value "Ford".veh:vehicle veh:make

the " " table represents all nodes that are of this particular node type, and itasset:acquired

contains columns for the " " and " " properties definedasset:acquiredOn asset:acquisitionId

by the " " mixin. We'll apply a constraint on the " " to find allasset:acquired asset:acquiredOn

nodes acquired later than January 1, 2011 at midnight.the " " table represents all of the nodes of this particular node type. We're largely interestednt:file

in the path of this node.

We'll also need some join criteria:

that ensures that the nodes in the " " table are also in the " " table;veh:vehicle asset:acquired

andthat the " " nodes (in the 3rd table) are below (a descendant of) the nodes in the "nt:file

" tableveh:vehicle


25/423

ModeShape 3


Our query then becomes:

SELECT images.[jcr:path]

FROM [veh:vehicle] AS vehicle

JOIN [asset:acquired] AS asset ON ISSAMENODE(vehicle,asset)

JOIN [nt:file] AS images ON ISDESCENDANTNODE(images,vehicle) WHERE vehicle.[veh:make] = 'Ford'

AND asset.[asset:acquisitionId] > CAST('2011-01-01T00:00:00' AS DATE)

AND images.[jcr:mimeType] IN ('application/jpeg','application/png')

Note that this really isn't that much more complicated than our single-query, and results include a columnwith the path of each of our images that satisfies our constraints (or we can just look up the objects).Node

These are just some of the possibilities that the query API makes possible.

1.3 FeaturesThe organizes the various features of the specification into several categories. The firstJCR 2.0 specificationare the features:mandatory

- Obtaining a instance andRepository acquisition, authentication and authorization Repository

connecting to the repository to obtain multiple objects.Session

- Navigating and finding nodes by path and by identifier, andReading and browsing contentreading properties of nodes.

- Using the two query languages defined by JCR 2.0, including the SQL-likeQuerying contentJCR-SQL2 and the programmatic JCR-JQOM languages.

- Exporting all or part of a workspace to one of two XML formats: the systemExporting contentdocument format results in " ", " ", and " " XML elements, and asv:node sv:property sv:value

document view format that results in XML elements that correspond to nodes and XML attributes thatcorrespond to properties.

- Using the built-in and related JCR interfaces to findDiscovering node types NodeTypeManager

and list all the node types, property type definitions, and child node definitions that are registered withthe repository.

- Checking whether any session has the ability to read, setChecking permissions and capabilitiesproperties, add nodes, or remove nodes at particular locations within the workspace. This alsoincludes allowing any session to determine a priori whether certain operations cannot be performed,although this basically is a best-effort mechanism.

The specification then outlines some of the features:optional



26/423

ModeShape 3


- Creating, modifying, or removing content using the -relatedWriting to the repository Session

methods. - Importing the information in an XML file (in either the system document format orImporting content

the document view format) into the repository, prescribing the behavior when there are clashes in

identities. - Allowing users to register listeners with various criteria that will be notifiedObserving changes

when changes are made in the repository content that satisfy the listener's criteria. - Programmatically creating new workspaces and deleting existingManaging workspaces

workspaces. - A feature that allows certain nodes to be "shared" at multiple locations within theShareable nodes

same or different workspaces. - A mechanism that allows the user to mark content as versionable (by adding aVersioning

"mix:versionable" mixin), and then use methods to signal to the repository that the current state of thatcontent be captured in the repository's version history. Users can also navigate the version history,and merge or restore the content from older versions.

- A simple mechanism by which a user can lock (for a short period of time) contentLocking contentto prevent other users from modifying or removing that same content.

- Allowing users to register new node types, re-register node types withManaging node typesalternative definitions, and unregister node types that are no longer used.

- Defines how repositories and sessions behave when used within a JTA environment.Transactions - Defines the semantics and behaviors for allowing children of a single node toSame name siblings

have the same name yet be individually addressable. - Defines how nodes (and in particular node types) can specify that the ordering ofOrdering children

their children is to be maintained or changed. - An advanced mechanism for allowing users to discover and manageManaging access controls

fine-grained access control privileges. Much of this feature relies upon implementation-specific policydefinitions.

- Allow content to be associated with various lifecycles, and allowManaging content lifecyclesusers to transition the state of content through the appropriate lifecycle. The names and semantics ofthe lifecycle states and transitions are implementation-specific.

- Allows a repository to integrate with an external facility toRetention and hold retention and hold place a hold on certain content, effectively making that content appear as if it were read-only, whiletracking information about the hold and the hold policy that applies to various content.

ModeShape 3.x supports all of these JCR features the last three: access controls, contentexcept lifecycles, and retention and hold.


27/423

ModeShape 3


1.3.1 Discovering supportThe JCR API also provides a way for a user to dynamically discover which of these features a repository

supports. Each instance exposes for each of these behavioral features. TheRepository descriptors descriptor keys for a repository instance are accessible as are the individual values for each descriptor.Standard descriptor keys are defined by constants on the interface.javax.jcr.Repository

Here's a small sample of code that gets the various descriptors for a repository:

javax.jcr.Repository repository = ...

String[] keys = repository.getDescriptorKeys();

for ( String key : keys ) {

boolean std = repository.isStandardDescriptor(key);

boolean singleValued = repository.isSingleValueDescriptor(key);

if ( singleValued ) {

Value value = repository.getDescriptorValue(key);

} else {

Value[] values = repository.getDescriptorValues(key);

}

}

Note that the object is the same as what's used for property values, and the class hasValue Value

methods to obtain the value in the form of a , , , , ,String boolean long double java.util.Calendar

, , and objects.java.match.BigDecimal java.io.InputStream javax.jcr.Binary

Here's another example that shows how to determine the languages that are supported by a repository:

javax.jcr.Repository repository = ...

Value[] languages = repository.getDescriptorValues(Repository.QUERY_LANGUAGES);

1.4 Repository and Session

Before your application can do anything with a JCR repository, it first has to find theinstance and use it to establish a . This page shows thejavax.jcr.Repository javax.jcr.Session

ways of using the JCR API to do exactly this.


28/423

ModeShape 3


Getting a RepositoryUsing JNDIUsing RepositoryFactory

Getting a Session

CredentialsThread-safetyLong-running Sessions

Making and persisting changesVisibility of changesTransactions

Logging out

1.4.1 Getting a RepositoryThe defines two primary ways to obtain a instance, and neither requireJCR 2.0 specification Repository

your application to use any implementation-specific code.

Using JNDIOne of the more popular ways to find a instance is to use JNDI, though this only works inRepository

environments like web servers or application servers that contain a JNDI implementation. It also assumesthat a instance has already been registered in JNDI; how this is done is specific to theRepository

environment.

For example, consider that our environment has registered our in JNDI with the name " ".Repository jcr

We can then simply use JNDI to obtain the instance using the JNDI API (in the " " package):javax.naming

InitialContext initCtx = new InitialContext();

Context envCtx = (Context) initCtx.lookup("java:comp/env");

javax.jcr.Repository repository = (javax.jcr.Repository) envCtx.lookup("jcr");

Different environments require different techniques to obtain the object.javax.naming.Context

The above example is what's used in the Tomcat web server. Some app servers allow you todirectly look up components in JNDI using the .InitialContext



29/423

ModeShape 3


Using RepositoryFactoryThe JCR 2.0 specification defined a new mechanism to find instances without relying uponRepository

JNDI, and this works in any Java application.

Implementations that support this mechanism implement the interface,javax.jcr.RepositoryFactory

and define a resource in their JARs that registers their implementation with the Java SE Service Loaderfacility.

The only thing a JCR client application needs to do is use the facility to loop over all theServiceLoader

implementations and ask each one to create (or obtain) a repository given a set ofRepositoryFactory

supplied parameters:

Map parameters = ...

Repository repository = null;for (RepositoryFactory factory : ServiceLoader.load(RepositoryFactory.class)) {

repository = factory.getRepository(parameters);

if (repository != null) break;

}

The parameters are implementation-specific, but you can keep your application independent of theJCR implementation by simply loading the properties from a resource file.

1.4.2 Getting a SessionOnce you've gotten hold of your instance, your application can connect to it by passing a setRepository

of credentials identifying the user and the name of the workspace that the user wishes to use. The repositorywill return a instance that has the privileges awarded to that user per the credentials.javax.jcr.Session

The can be used to read, query, observe, or change repository content.Session

The interface defines a method that takes the usersRepository login javax.jcr.Credentials

object and the name of the workspace. The signature of this method is as follows:

public interface Repository {

...

public Session login(Credentials credentials, String workspaceName)

throws LoginException, NoSuchWorkspaceException, RepositoryException;

...

}

The application can supply null values for either or both of the " " and " ".credentials workspaceName

When no credentials is provided, the repository can use an external mechanism to identify and authenticatethe user. When no workspace name is provided, the repository chooses a .default workspace

http://java.sun.com/javase/6/docs/api/java/util/ServiceLoader.htmlhttp://java.sun.com/javase/6/docs/api/java/util/ServiceLoader.html


30/423

ModeShape 3


For convenience, the interface defines three other forms of that take differentRepository login

combinations of the credentials and/or workspace name, but all are simple wrappers around the primarymethod.login(Credentials,String)

CredentialsThe JCR API defines a marker interface that is intended to encapsulate thejavax.jcr.Credentials

information necessary to identify, authenticate, and authorize a particular user. JCR implementations candefine their own implementations, or they can reuse the two concrete implementationCredentials

classes:

- A that identifies a user with a username andjavax.jcr.SimpleCredentials Credentials

password. - A that can be used to obtain an anonymousjavax.jcr.GuestCredentials Credentials

session.

Credentials don't need to be supplied, either. In such cases, the repository can use an external mechanismto authenticate and authorize the current user. Many implementations support JAAS, allowing the logincontext currently associated with the thread to perform the authentication.

Thread-safetyJCR sessions are intended to be lightweight, so creating them should be very fast. But they are not threadsafe, so they shouldn't be used concurrently by multiple threads. Therefore, most applications shouldprobably create a session to read, query or change repository content, and then quickly close that session.

Web applications, for example, often will obtain a for each incoming request, use that session toSessionprocess the request, and then will close the session.

Although not required by the specification, ModeShape 3 sessions are thread-safe and can beused by multiple threads. Care still needs to be used, however, as any transient state of a sessionused by multiple threads will be visible to all components using that session.


31/423

ModeShape 3


Long-running SessionsOne exception to the short-lived session pattern is that an application can only register listeners to therepository through a . When a session is closed, all listeners registered with that session areSession

unbound. So if an application requires listeners to exist for long periods of time, the application will have touse a long-lived session.

Applications should use these long-lived sessions only to register listeners, and should never use thesession to process any of the events. This is because the session is not thread-safe, and the listeners willoften be notified on separate threads. Instead, listener implementations should enqueue any work to bedone and return without using the listener's session. Then, have separate threads that take items from thequeue, obtain a new , perform the work, and close the session.Session

Getting off the listener thread is generally a good practice for asynchronous listeners, even if the Session

implementations are thread-safe. This is because implementations may serialize delivery of the events to alllisteners, so one listener that takes a long time to process each event might cause a delay for the otherlisteners.

Some JCR implementations can operate in a mode where the repository remains open only as longas there is at least one session. As such, your application might need to use a long-runningsession just to keep the repository running.


32/423

ModeShape 3


1.4.3 Making and persisting changesThe can be used to make changes to the persistent workspace content. However, all changes areSession

and visible only to that until the method is called on the . At that point,transient Session save() Sessionthe transient changes are persisted to the workspace, and generally become immediately visible to all othersessions.

Visibility of changesThe specification gives a fair amount of freedom to implementations in how and when a sees theSession

changes persisted by other Session}}s. Some implementations use a copy-on-read

obtains a snapshot of each node it accesses, and any changes tobehavior, where the {{Session

those nodes will only be seen by the session if/when it refreshes it's cached information or if/when it savesits state. Other implementations use a different behavior, where the only content a session iscopy-on-write sure to see unchanged are the transient changes it has made, and will immediately see all other changespersisted by other sessions.

Be sure to know how the implementation you're using works.

ModeShape 3.x uses the behavior. Note that this is different than ModeShape 2.x,copy-on-write which used .copy-on-read

TransactionsWhen using transactions, the changes made by a are not persisted on " ", but as expectedSession save()

are persisted when the transaction commits. Note that only those saved changes will be committed as partof the transaction, so be sure to call " " prior to committing the transaction.save()

1.4.4 Logging outAn application is expected to close each session after it is no longer needed, and this is done using the

method. This will immediately discard any transient (but unsaved) changes made with thatlogout()

session, and will immediately unregister all listeners that were registered using the session.

1.5 Reading content

1.6 Writing content

1.7 Workspace operations


33/423

ModeShape 3


1.8 Defining custom node typesOne of the important features of JCR is that it allows your applications to define and use custom node types,which can be used for either primary types or mixin types. This section talks about how to define and use thenode types, property definitions, and child node definitions.

Compact Node Definition (CND)Declaring namespacesDeclaring node types

Property definitionsChild node definitions

CND exampleBuilt-in node typesRegistering custom node types

1.8.1 Compact Node Definition (CND)The JCR 2.0 specification defines a file format called "Compact Node Definition", or CND. True to itsnamesake, the format does indeed make it possible to define node types in a very compact form. It supportsJava-style comments, uses JCR-style namespace prefixes, and does not require whitespace or newlinesaround key characters (e.g., ' ', ' ', ' ', ' ', ' ', ' ', ' ', and ' ').[ ] > , ( ) = <

This documentation is a summary of the CND format. For the true specification of the format, seeSection 25.2 in the .JCR 2.0 specification

Here is a small CND file that defines just a few of the 33 built-in node types, and hopefully gives you anexample of what CND files look like:



34/423

ModeShape 3


/* Every node type directly or indirectly extends from 'nt:base' */[nt:base] abstract

- jcr:primaryType (name) mandatory autocreated protected compute

- jcr:mixinTypes (name) protected multiple compute

[nt:unstructured] orderable

- * (undefined) multiple

- * (undefined)

+ * (nt:base) = nt:unstructured sns version

[mix:created] mixin

- jcr:created (date) protected

- jcr:createdBy (string) protected

[nt:hierarchyNode] > mix:created abstract

// The 'nt:file' and 'nt:folder' node types allows applications to store

// files and directories as content inside a repository

[nt:file] > nt:hierarchyNode

+ jcr:content (nt:base) primary mandatory

[nt:folder] > nt:hierarchyNode

+ * (nt:hierarchyNode) version

[mix:referenceable] mixin

- jcr:uuid (string) mandatory autocreated protected initialize

[mix:mimeType] mixin

- jcr:mimeType (string)

- jcr:encoding (string)

[mix:lastModified] mixin

- jcr:lastModified (date)

- jcr:lastModifiedBy (string)

[nt:resource] > mix:mimeType, mix:lastModified

- jcr:data (binary) primary mandatory

Let's break apart the format into the different parts.

Declaring namespacesA namespace is declared using the form:

< prefix = uri >

where is the quoted or unquoted string literal used in the rest of the file as the prefix for theprefix

namespace, and is the quoted URI for the namespace. For readability, most people place eachurinamespace declaration on a separate line near the top of the file, but that's not required.


35/423

ModeShape 3


Declaring node typesEach node type declaration is made up of several parts. The first is the specification of the node type's nameand attributes, and is of the form:

[ prefixedName ] > supertypes attributes

where is the name of the node type in prefixed notation (e.g., " ", "prefixedName nt:base

", " ", etc), is the optional comma-separated list of thent:unstructured mix:lastModified supertypes

prefixed names of the node type's supertypes, and is the optional list of node type attributes:attributes

AttributeKeywords

Description

orderable

ordo

The node type supports orderable children. If absent, then orderable children are not

supported.

mixin

mix

m

The node type is a mixin. If absent, the node type can be used as a primary type.

abstract

abs

a

The node type is abstract and cannot be directly used as nodes' primary type or mixintype. If absent, the node type is concrete.

noquerynq

query

q

Specifies whether the node type can be queried. If ' ' or ' ' are used, then thenoquery nqnode type cannot be queried; if ' ' or ' ' are used, then the node type can bequery q

queried. If neither are specified, ModeShape assumes that the node type can be queried.If multiple are specified, the last one is used.

primaryitem

!

The string following this keyword specifies the prefixed name of the property or child(including same-name-sibling index if required) that will be considered the ,primary item which is the child that can be navigated using a special method and allows a client tomore easily navigate an unknown structure. If absent, the node type does not have aprimary item.

After the attributes are listed the property definitions and child node definitions.

Property definitionsEach property definition begins with a ' ' character and follows the form:-

- prefixedName ( type ) = defaultValues attributes

where


36/423

ModeShape 3


is the name of the property definition in prefix formprefixedName

is the case-insensitive name of the JCR property type, and is one of: , , ,type STRING BINARY LONG

, , , , , , , , andDOUBLE DATE BOOLEAN NAME PATH REFERENCE WEAKREFERENCE URI DECIMAL

is an optional comma-separated list of quoted string literals containing the stringdefaultValues

representation of the default values; multiple are allowed for multi-valued properties is the optional list of property definition attributes:attributes

AttributeKeywords

Description

mandatory

man

m

The parent node must have at least least one property to which this property definitionapplies.

autocreatedaut

a

The property is automatically created when the node is created with the node type asprimary type, or when the node type is added as a mixin to a node. If absent, theproperty is not auto-created.

protected

pro

p

The property to which this definition applies is protected, meaning it can be read but notmodified by client applications. When absent, the property can be set by clientapplications.

multiple

mul

*

The property is multi-valued. If absent, the property is single-valued.

COPY

VERSION

INITIALIZE

COMPUTE

IGNORE

ABORT

The specification for how the property is to be handled when the node is versioned.When absent, the default versioning is .COPY

< constraints The quoted string literals containing regular expressions or exact matches for the values.When constraints are provided, every value must satisfy at least one constraint on the

property definition. If absent, there are no constraints on the values.

queryops

qop

This keyword is followed by a quoted string literal containing the comma-separatedoperators that can be used in property comparison constraints against this property. Ifabsent, all possible operators are used, and this is equivalent to specifying ' =, ,


37/423

ModeShape 3


Child node definitionsEach child node definition begins with a '{+}' character and follows the form:

{+}prefixedName ( requiredTypes ) = defaultType attributes

where

is the name of the property definition in prefix formprefixedName

is optional comma-separated names of the required node types for the child node.requiredTypes

Any child adhering to this child node definition must be instances of at least the required types listedhere. If absent, the required type is assumed to be ' ' (of which all nodes are instances).nt:base

is an optional name of the node type that should be used by default when creating thedefaultType

child node. If absent, the default type is assumed to be ' '. The default type cannt:unstructured

always be overridden by clients using the method.Node.addNode(String,String)

is the optional list of child node definition attributes:attributes


38/423

ModeShape 3


AttributeKeywords

Description

mandatory

man

m

The parent node must have at least least one child to which this child node definitionapplies.

autocreated

aut

a

The child node is automatically created when the node is created with the node type asprimary type, or when the node type is added as a mixin to a node. If absent, the childnode is not auto-created.

protected

pro

p

The child to which this node definition type applies is protected, meaning it can be readbut not modified by client applications. When absent, the property can be set by clientapplications. If absent, the child nodes can be read and removed from the parent node.

sns

*

There may be multiple child nodes with the same name to which this definition applies.Such child nodes will be distinguished with a same-name-sibling index. If absent,same-name-siblings are not allowed.

COPY

VERSION

INITIALIZE

COMPUTE

IGNORE

ABORT

The specification for how the child nodes to which this definition applies are to behandled when the parent node is versioned. When absent, the default versioning is

.COPY

< constraints The quoted string literals containing regular expressions or exact matches for the values.When constraints are provided, every value must satisfy at least one constraint on theproperty definition. If absent, there are no constraints on the values.

queryops

qop

This keyword is followed by a quoted string literal containing the comma-separatedoperators that can be used in property comparison constraints against this property. Ifabsent, all possible operators are used, and this is equivalent to specifying ' =, ,


39/423

ModeSh