JSR 170 Summary Notes

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

JSR-170Back to JSR-170

Table of Contents

• 1 Purpose Of These Notes


• 2 Objectives of JSR-170


• 3 The Repository Model


• 4 Compliance Levels


• 5 API Basics


• 6 Workspaces in Detail


• 7 Nodes in Detail


• 8 Properties In Detail


• 9 Querying Using XPath

Purpose Of These Notes

To give a high level introduction to the JSR-170 spec, summarising the specific functional areas that of interest to us.  For details please read the spec.

Currently these notes are specifically targeted at Level 1 compliance.  Details about Level 2 compliance and Optional features may be left out.

These notes are based on JSR-170 0.16.2.

Objectives of JSR-170

A standard content repository API facilitating vendor neutrality and interoperability.

The Repository Model

• A JCR repository consists of one or more workspaces, each of which contains a tree of items.
  
• An item is either a node or a property.
  
• Each node may have zero or more child nodes and zero or more child properties.
  
• There is a single root node, which has no parent.
  
• All other nodes have one parent.
  
• Properties have one parent (a node) and cannot have children; they are the leaves of the tree.
  
• A property is the smallest unit of content, being a name-value pair.
  
• All of the actual content in the repository is stored within the values of the properties.
  

Compliance Levels

There are two compliance levels to the specification and a number of optional features.  At present we primarily concerned with Level 1 compliance.

Level 1

• Retrieval and traversal of node and properties.
  
• Reading the values of properties.
  
• Transient namespace remapping.
  
• Export to XML/SAX.
  
• Query facility with XPath.
  
• Discovery of available node types.
  

Level 2

• Adding and removing nodes and properties.
  
• Writing the values of properties.
  
• Persistent namespace changes.
  
• Import from XML/SAX.
  
• Assigning node types to nodes.
  
• Discovery of access control permissions.
  

Optional

• Transactions.
  
• Versioning.
  
• Observation. (Events)
  
• Access Control.
  
• Locking.
  
• SQL syntax for query.
  

API Basics

An instance of a Respository object represents the repository as a whole.

The method login is called with Credentials to connect to the repository.  A Session object is returned.  The Session object is tied to a single workspace in the repository.

The aquisition of the Repository and Credential objects are not covered in the spec.  We would probably use Spring.

The API provides methods for the traversal of the tree structure item by item and also support for direct access to items using XPath's or UUID's.

Level 2 compliance includes an API to write to the repository by adding or removing nodes and properties or changing the values of properties.

All changes made to the workspace are kept in transient storage untill they are committed.  This is performed by Session.save.  Pending changes are only visible within the Session, becoming visible throughout once save is called.  Validation is performed during the save process.

If the Session is within a transaction, save will not make pending changes visible to other sessions.  This will only happen when the transaction is also committed.  Transaction support is optional.

Workspaces in Detail

A repository can be made up of a single workspace or many, each has a single rooted tree.

Nodes in Detail

Node Types

Every node must have a primary node type.  This defines the names, types and other characteristics of the properties and child nodes that the node is allowed.  The property jcrrimaryType records the node type.

Additional node type can be mixed in.  The property jcr:MixinTypes records nay mixin types.

Level 1 compliance provides methods for discovering the node type of existing nodes and for discovering and reading the definitions of node types available in the repository.

Referencable Nodes

A repository may support referencable nodes using mix:referencable. (does may mean that it is not required for Level 1 compliance?)  This enforces the property jsr:uuid to be populated.  Within a workspace there is never more than one node with the UUID property value.

A nodes with identical UUID values can be present in different workspaces.  These node are said to be corresponding, but need not share any other common attributes.

Primary Node

Any one of a nodes children can be specified a the primary child node.  This can be of use when there are system nodes in the  hierarchy.

Properties In Detail

Every property value is of a simple type.  Available types are string, binary, date, long, double, boolean, name, path and reference.  Methods are provided in Level 1 to read the property values into the corresponding Java native types.  Level 2 provides the corresponding write methods.

Multi-valued properties are supported.

Properties do not support null values.  Setting a property to a null value is equivalent to removing it.

Reference Type

A property that has a value of type reference, contains the UUID of a referenceable node within the same workspace.  This allows nodes to reference one another via their property values.

Querying Using XPath

Level 1 compliance states that a workspace must be queryable using a XPath like syntax.  The syntax specified in the spec is a cut down version of standard XPath.  I won't give specific details of the scope of the syntax here, but I have provided a number of examples.

Example XPath Queries

• / - path to the root node
  
• /a/b - path to the node named b under the root node a
  
• /a/b/@x - path to the value of the property named x of the node named b below the root node a
  
• /a/b[2]/c[3] - path to the third child node of c of the second child node of b below the root node a
  
• //b - all the nodes in the workspace with the name b (is this supported?)
  
• b/.. - all the parent nodes of node named b in the workspace relative to the current context
  
• /as:a/as:b - second example using namespace syntax
  

An absolute path is a path from the root of the tree to a specified location.  Absolute paths always begin with a /.  Relative paths are also supported, they do not begin with a / and give a location relative to a given context. ( a node or collection of nodes)

Namespaces

Nodes and Properties can have namespaces.  These are the same as standard XML namespaces, an alias and a unique URI.  To support this all Level 1 & 2 implementations must has a namespace registry.

In Level 1 there is no provision for adding new namespaces to the registry (or deleting) this is part of Level 2.  Level 1 may, however, provide a number of built in namespaces in addition to the five reserved namespaces listed below.

Level 1 compliance also states that the prefix assigned to an exiting registered namespace (URI) may be temporarily over-ridden by another prefix within the scope of an particular session.

There are a number of reserved namespace prefixes:

• jcr - reserved for items with built-in types.
  
• nt - reserved for the names of built-in primary node types.
  
• mix - reserved for the names of built-in mixin node types.
  
• sv - XML serialisation.
  
• '' - the default namespace.
  

Same Name Siblings and Ordered Nodes

Same name sibilings support is optional.  If it is supported then the XPath index syntax, shown above, is used to distinguish between child nodes.  Propeties cannot have same name siblings.

Ordered child node support is optional.  The order is controled by the parent node and if not implemented, cannot be guarenteed.