svn commit: r1229679 [11/12] - /jackrabbit/site/trunk/content/

[ju...@apache.org]

Added: jackrabbit/site/trunk/content/node-types.cwiki
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/node-types.cwiki?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/node-types.cwiki (added)
+++ jackrabbit/site/trunk/content/node-types.cwiki Tue Jan 10 18:50:59 2012
@@ -0,0 +1,95 @@
+Each node in a Jackrabbit workspace tree has a node type that defines the child nodes and properties it may (or must) have. Developers can use node types to define a custom content model for their application domain and have Jackrabbit enforce the constraints of that model at the repository level.
+
+h2. Primary vs Mixin
+
+There are two categories of node types, *primary* and *mixin*. Every node has a primary node type assigned to it upon creation (see {{Node.addNode}} in the JCR API). In addition, a mixin node type may be added to a node later in its lifecycle (see {{Node.addMixin}}).
+
+The primary node type of a node usually defines node structure (i.e., allowed and required child nodes and properties) related to the problem domain being modeled. For example, a node used in storing content about business contacts might have the primary type {{myapp:Contact}} which defines properties such as {{myapp:givenName}}, {{myapp:familyName}} and so forth.
+
+Mixin node types usually specify additional properties or child nodes related to a capability being added to the node. These capabilities may include generic repository-level functions as in the case of the built-in mixins {{mix:versionable}} and {{mix:lockable}}, for example, or domain-level capabilities such as a (hypothetical) {{myapp:Emailable}} mixin type that adds the property {{myapp:emailAddress}} to a node.
+
+h2. Inheritance
+
+Primary node types are arranged in an inheritance hierarchy. Every primary node type must be the subtype of at least one existing node type. The built-in node type {{nt:base}} serves as the root of this hierarchy. Jackrabbit supports multiple inheritance of node types so node types can have more than one supertype.
+
+Mixin node types do not have to have supertypes.
+
+The JSR 170 specification and the current public review draft of the JSR 283 specification (section 4.7.7) leave it up to the implementation whether e.g. the orderable child nodes setting is inherited from supertypes. Inheritance semantics, especially with multiple inheritance, are non-trivial at best and up to a certain degree arbitrary. Jackrabbit therefore, in compliance with the spec, doesn't support inheritance of node type attributes such as orderable.
+
+h2. Node Type Definition
+
+A node type definition has the following attributes:
+
+* *Name* Every node type registered with the repository has a unique name. The naming conventions for node                     types are the same as for items (i.e., they may have a colon delimited prefix).
+* *Supertypes* A primary node type (with the exception of {{nt:base}}) must extend another node type (and may extend more than one node type). A mixin node type may extend another node type.
+* *Mixin Status* A node type may be either primary or mixin.
+* *Orderable Child Nodes Status* A primary node type may specify that child nodes are client-orderable. If this status is set to true, then {{Node.orderBefore}} can be used to set the order of child nodes. Only primary node types control a node's status in this regard. This setting on a mixin node type will not have                     any effect on the node.
+* *Property Definitions* A node type contains a set of definitions specifying the properties that nodes of this node type are allowed (or required) to have and the characteristics of those properties (see below).
+* *Child Node Definitions* A node type contains a set of definitions specifying the child nodes that nodes of this node type are allowed (or required) to have and the characteristics of those child nodes (including, in turn, their node types, see below).
+* *Primary Item Name* A node type may specify one child item (property or node) by name as the primary item. This indicator is used by the method {{Node.getPrimaryItem()}}.
+
+h2. Property Definition
+
+A property definition (within a node type definition) contains the the following information:
+
+* *Name* The name of the property to which this definition applies, or "{{*}}" if this definition is                         a "residual definition', meaning that it applies to any additional properties with any names apart from those otherwise defined in this node type.
+* *Required Type* The required type of the property. One of
+** {{STRING}}
+** {{BINARY}}
+** {{LONG}}
+** {{DOUBLE}}
+** {{BOOLEAN}}
+** {{DATE}}
+** {{PATH}}
+** {{NAME}}
+** {{REFERENCE}}
+** {{UNDEFINED}} (the property can be of any type)
+* *Value Constraints* The value constraints on the property define the range of values that may be assigned                         to this property.
+* *Default Value* The value that the property will have if it is auto-created.
+* *Auto-create Status* Whether this property will be auto-created when its parent node is created. Only properties with a default value can be auto-created.
+* *Mandatory Status* A mandatory property is one that must exist. If a node of a type that specifies a                         mandatory property is created then any attempt to save that node without adding the mandatory property will fail. Since single-value properties either have a value or do not exist (there being no concept of the null value) this implies that a mandatory single-value property must have a value. A mandatory multi-value property on the other hand may have zero or more values.
+* *On-Parent-Version Status* The {{onParentVersion}} status of specifies what happens to this property if a                         new version of its parent node is created (i.e. a checked-in is done on it).
+* *Protected Status* A protected property is one which cannot be modified (i.e. have child nodes or properties added or removed) or removed from its parent through the JCR API.
+* *Multiple Values Status* Whether this property can have multiple values, meaning that it stores an array of values, not just one. Note that this "multiple values" flag is special in that a given node type may have two property definitions that are identical in every respect except for the their "multiple values" status. For example, a node type can specify two string properties both called X, one of which is multi-valued and the other that is not. An example of such a node type is {{nt:unstructured}}.
+
+h2. Child Node Definition
+
+A child node definition (within a node type definition) contains the the following information:
+
+* *Name* The name of the child node to which this definition applies or "{{*}}" if this definition is                         a "residual definition', meaning that it applies to any additional child nodes with any                         names apart from those otherwise defined in this node type.
+* *Required Primary Types* If it specifies only a single node type N then the primary node type of this child node must be N or a subtype of N. If this attribute specifies multiple node types N1, N2,..., Nm then the primary node type of this child node must be a subtype of all the types N1, N2, ... Nm. Note that this                         is possible because Jackrabbit supports multiple inheritance among node types and that each node still has one and only one primary node type.
+* *Default Primary Type* This is the primary node type automatically assigned if no node type information is specified when the node is created.
+* *Auto-create Status* Governs whether this child node will be auto-created when its parent node is created.
+* *Mandatory Status* Governs whether the child node is mandatory. A mandatory child node is one that must exist. If a mandatory child node is missing from a parent node then save on the parent node will fail.
+* *On-Parent-Version Status* This specifies what to do with the child node if its parent node is versioned.
+* *Protected Status* This governs whether the child node is protected. A protected node is one which cannot be modified (have child node or properties added to it or removed from it) or be removed from its                         parent through the JCR API.
+* *Same-Name Siblings Status* This governs whether this child node can have same-name siblings, meaning that the parent node can have more than one child node of this name.
+
+h2. Registering Node Types
+
+Each Jackrabbit instance has a {{NodeTypeRegistry}} which is created on start-up and populated with the set of built-in node types (these include both those required by the JCR specification and others required by the Jackrabbit implementation).
+
+First you define your node types in a text file using the "Compact Namespace and Node Type Definition" (CND) notation, then register them using the  [{{JackrabbitNodeTypeManager}}|http://jackrabbit.apache.org/api/1.5/org/apache/jackrabbit/api/JackrabbitNodeTypeManager.html]. The following code gives an example:
+
+{code}
+import javax.jcr.Session;
+import org.apache.jackrabbit.api.JackrabbitNodeTypeManager;
+import java.io.FileInputStream;
+
+public class CustomNodeTypeExample {
+    public static void RegisterCustomNodeTypes(Session session, String cndFileName)
+        throws Exception {
+
+        // Get the JackrabbitNodeTypeManager from the Workspace.
+        // Note that it must be cast from the generic JCR NodeTypeManager to the
+        // Jackrabbit-specific implementation.
+        JackrabbitNodeTypeManager manager = (JackrabbitNodeTypeManager)
+               session.getWorkspace().getNodeTypeManager();
+        // Register the custom node types defined in the CND file
+        manager.registerNodeTypes(new FileInputStream(cndFileName),
+               JackrabbitNodeTypeManager.TEXT_X_JCR_CND);
+    }
+}
+{code}
+
+Continue to [Node Type Notation] or [Node Type Visualization]
\ No newline at end of file

Propchange: jackrabbit/site/trunk/content/node-types.cwiki
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jackrabbit/site/trunk/content/node-types.mdtext
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/node-types.mdtext?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/node-types.mdtext (added)
+++ jackrabbit/site/trunk/content/node-types.mdtext Tue Jan 10 18:50:59 2012
@@ -0,0 +1,199 @@
+Title: Node Types
+Each node in a Jackrabbit workspace tree has a node type that defines the
+child nodes and properties it may (or must) have. Developers can use node
+types to define a custom content model for their application domain and
+have Jackrabbit enforce the constraints of that model at the repository
+level.
+
+<a name="NodeTypes-PrimaryvsMixin"></a>
+## Primary vs Mixin
+
+There are two categories of node types, *primary* and *mixin*. Every node
+has a primary node type assigned to it upon creation (see *Node.addNode*
+in the JCR API). In addition, a mixin node type may be added to a node
+later in its lifecycle (see *Node.addMixin*).
+
+The primary node type of a node usually defines node structure (i.e.,
+allowed and required child nodes and properties) related to the problem
+domain being modeled. For example, a node used in storing content about
+business contacts might have the primary type *myapp:Contact* which
+defines properties such as *myapp:givenName*, *myapp:familyName* and so
+forth.
+
+Mixin node types usually specify additional properties or child nodes
+related to a capability being added to the node. These capabilities may
+include generic repository-level functions as in the case of the built-in
+mixins *mix:versionable* and *mix:lockable*, for example, or
+domain-level capabilities such as a (hypothetical) *myapp:Emailable*
+mixin type that adds the property *myapp:emailAddress* to a node.
+
+<a name="NodeTypes-Inheritance"></a>
+## Inheritance
+
+Primary node types are arranged in an inheritance hierarchy. Every primary
+node type must be the subtype of at least one existing node type. The
+built-in node type *nt:base* serves as the root of this hierarchy.
+Jackrabbit supports multiple inheritance of node types so node types can
+have more than one supertype.
+
+Mixin node types do not have to have supertypes.
+
+The JSR 170 specification and the current public review draft of the JSR
+283 specification (section 4.7.7) leave it up to the implementation whether
+e.g. the orderable child nodes setting is inherited from supertypes.
+Inheritance semantics, especially with multiple inheritance, are
+non-trivial at best and up to a certain degree arbitrary. Jackrabbit
+therefore, in compliance with the spec, doesn't support inheritance of node
+type attributes such as orderable.
+
+<a name="NodeTypes-NodeTypeDefinition"></a>
+## Node Type Definition
+
+A node type definition has the following attributes:
+
+* *Name* Every node type registered with the repository has a unique name.
+The naming conventions for node 		    types are the same as
+for items (i.e., they may have a colon delimited prefix).
+* *Supertypes* A primary node type (with the exception of *nt:base*) must
+extend another node type (and may extend more than one node type). A mixin
+node type may extend another node type.
+* *Mixin Status* A node type may be either primary or mixin.
+* *Orderable Child Nodes Status* A primary node type may specify that child
+nodes are client-orderable. If this status is set to true, then
+*Node.orderBefore* can be used to set the order of child nodes. Only
+primary node types control a node's status in this regard. This setting on
+a mixin node type will not have 		    any effect on the node.
+* *Property Definitions* A node type contains a set of definitions
+specifying the properties that nodes of this node type are allowed (or
+required) to have and the characteristics of those properties (see below).
+* *Child Node Definitions* A node type contains a set of definitions
+specifying the child nodes that nodes of this node type are allowed (or
+required) to have and the characteristics of those child nodes (including,
+in turn, their node types, see below).
+* *Primary Item Name* A node type may specify one child item (property or
+node) by name as the primary item. This indicator is used by the method
+*Node.getPrimaryItem()*.
+
+<a name="NodeTypes-PropertyDefinition"></a>
+## Property Definition
+
+A property definition (within a node type definition) contains the the
+following information:
+
+* *Name* The name of the property to which this definition applies, or
+"***" if this definition is			      a "residual
+definition', meaning that it applies to any additional properties with any
+names apart from those otherwise defined in this node type.
+* *Required Type* The required type of the property. One of
+** *STRING*
+** *BINARY*
+** *LONG*
+** *DOUBLE*
+** *BOOLEAN*
+** *DATE*
+** *PATH*
+** *NAME*
+** *REFERENCE*
+** *UNDEFINED* (the property can be of any type)
+* *Value Constraints* The value constraints on the property define the
+range of values that may be assigned			     to this
+property.
+* *Default Value* The value that the property will have if it is
+auto-created.
+* *Auto-create Status* Whether this property will be auto-created when its
+parent node is created. Only properties with a default value can be
+auto-created.
+* *Mandatory Status* A mandatory property is one that must exist. If a node
+of a type that specifies a			   mandatory property is
+created then any attempt to save that node without adding the mandatory
+property will fail. Since single-value properties either have a value or do
+not exist (there being no concept of the null value) this implies that a
+mandatory single-value property must have a value. A mandatory multi-value
+property on the other hand may have zero or more values.
+* *On-Parent-Version Status* The *onParentVersion* status of specifies
+what happens to this property if a			   new version of
+its parent node is created (i.e. a checked-in is done on it).
+* *Protected Status* A protected property is one which cannot be modified
+(i.e. have child nodes or properties added or removed) or removed from its
+parent through the JCR API.
+* *Multiple Values Status* Whether this property can have multiple values,
+meaning that it stores an array of values, not just one. Note that this
+"multiple values" flag is special in that a given node type may have two
+property definitions that are identical in every respect except for the
+their "multiple values" status. For example, a node type can specify two
+string properties both called X, one of which is multi-valued and the other
+that is not. An example of such a node type is *nt:unstructured*.
+
+<a name="NodeTypes-ChildNodeDefinition"></a>
+## Child Node Definition
+
+A child node definition (within a node type definition) contains the the
+following information:
+
+* *Name* The name of the child node to which this definition applies or
+"***" if this definition is			      a "residual
+definition', meaning that it applies to any additional child nodes with any
+			names apart from those otherwise defined in this
+node type.
+* *Required Primary Types* If it specifies only a single node type N then
+the primary node type of this child node must be N or a subtype of N. If
+this attribute specifies multiple node types N1, N2,..., Nm then the
+primary node type of this child node must be a subtype of all the types N1,
+N2, ... Nm. Note that this			   is possible because
+Jackrabbit supports multiple inheritance among node types and that each
+node still has one and only one primary node type.
+* *Default Primary Type* This is the primary node type automatically
+assigned if no node type information is specified when the node is created.
+* *Auto-create Status* Governs whether this child node will be auto-created
+when its parent node is created.
+* *Mandatory Status* Governs whether the child node is mandatory. A
+mandatory child node is one that must exist. If a mandatory child node is
+missing from a parent node then save on the parent node will fail.
+* *On-Parent-Version Status* This specifies what to do with the child node
+if its parent node is versioned.
+* *Protected Status* This governs whether the child node is protected. A
+protected node is one which cannot be modified (have child node or
+properties added to it or removed from it) or be removed from its	   
+	      parent through the JCR API.
+* *Same-Name Siblings Status* This governs whether this child node can have
+same-name siblings, meaning that the parent node can have more than one
+child node of this name.
+
+<a name="NodeTypes-RegisteringNodeTypes"></a>
+## Registering Node Types
+
+Each Jackrabbit instance has a *NodeTypeRegistry* which is created on
+start-up and populated with the set of built-in node types (these include
+both those required by the JCR specification and others required by the
+Jackrabbit implementation).
+
+First you define your node types in a text file using the "Compact
+Namespace and Node Type Definition" (CND) notation, then register them
+using the  [*JackrabbitNodeTypeManager*](http://jackrabbit.apache.org/api/1.5/org/apache/jackrabbit/api/JackrabbitNodeTypeManager.html)
+. The following code gives an example:
+
+
+    import javax.jcr.Session;
+    import org.apache.jackrabbit.api.JackrabbitNodeTypeManager;
+    import java.io.FileInputStream;
+    
+    public class CustomNodeTypeExample {
+        public static void RegisterCustomNodeTypes(Session session, String
+cndFileName)
+    	throws Exception {
+    
+    	// Get the JackrabbitNodeTypeManager from the Workspace.
+    	// Note that it must be cast from the generic JCR NodeTypeManager
+to the
+    	// Jackrabbit-specific implementation.
+    	JackrabbitNodeTypeManager manager = (JackrabbitNodeTypeManager)
+    	       session.getWorkspace().getNodeTypeManager();
+    	// Register the custom node types defined in the CND file
+    	manager.registerNodeTypes(new FileInputStream(cndFileName),
+    	       JackrabbitNodeTypeManager.TEXT_X_JCR_CND);
+        }
+    }
+
+
+Continue to [Node Type Notation](node-type-notation.html)
+ or [Node Type Visualization]

Propchange: jackrabbit/site/trunk/content/node-types.mdtext
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jackrabbit/site/trunk/content/object-content-manager.cwiki
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/object-content-manager.cwiki?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/object-content-manager.cwiki (added)
+++ jackrabbit/site/trunk/content/object-content-manager.cwiki Tue Jan 10 18:50:59 2012
@@ -0,0 +1,103 @@
+The main component in the OCM framework is the ObjectContentManager. It converts an object graph into JCR nodes and properties and vice versa. The ObjectContentManager is always associated with a JCR Session. It is used to retrieve, create, update and delete objects from a JCR content repository. Usually there is one ObjectContentManager per user session.
+
+This page describes how an ObjectContentManager is working and how it can be initialised in your applications. 
+
+h2. How does the Object Content Manager work ?
+
+Thanks to a Mapping Descriptor, the ObjectContentManager is able to use the appropriate mapping strategy for each persistent object (pojo). The Mapping Descriptor contains one Class Descriptor per persistent class. Each Class Descriptor contains mapping information for the corresponding class attributes.
+
+In the point of view implementation, the Mappring Descriptor is a java object injected into the ObjectContentManager (see the interface org.apache.jackrabbit.ocm.mapper.Mapper). Right now, there are 2 different Mapping Descriptor implementations:
+
+    * Annotation : each persistent object is annoted in order to provide to the ObjectContentManager all the required information on its mapping strategy (see the class org.apache.jackrabbit.ocm.mapper.impl.annotation.AnnotationMapperImpl).
+    * XML configuration file : the class descriptors are defined in one or more XML config files used by the ObjectContentManager when it is instantiated (see the class org.apache.jackrabbit.ocm.mapper.impl.digester.DigesterMapperImpl). 
+
+For a business developer, it is not necessary to know how the ObjectContentManager is using the Class Descriptors. He has to make only a choice between annoted classes or XML files. Below, you can see how to setup correctly an ObjectContentManager. 
+
+h2. How does an object is persisted into a JCR repository ?
+
+In all cases, a persistent object (a pojo) is mapped into a JCR node and its fields are mapped into subnodes or properties depending on their types.
+
+There are 3 "field types":
+
+* Atomic fields
+    Primitive data types and simple objects (String, Long, Double, ...) . Those fields are mapped into JCR properties. 
+
+* Bean fields
+    One class can contain an 1..1 association to another bean. In this case, the field is a custom object. Those fields are mapped into JCR subnodes or a referenced node. 
+
+* Collection fields
+    One class can contain an 1..n association to a collection of beans (or Map). Those fields are mapped into a collection of JCR subnodes or a collection of referenced nodes. It is also possible to map a java collection into a multivalue property. 
+
+The Mapping descriptor contains also information on inheritances, interface mapping strategy, lazy loading, custom converter, cache strategy, etc. 
+h2. Basic setup (with annoted persistent classes)
+
+When you start your application, you need the following code to initialize correctly the Object Content Manager.
+
+{code}
+import javax.jcr.Session;
+import javax.jcr.Repository;
+		      
+import org.apache.jackrabbit.ocm.manager.impl.ObjectContentManagerImpl;
+import org.apache.jackrabbit.ocm.mapper.Mapper;
+import org.apache.jackrabbit.ocm.mapper.impl.annotation.AnnotationMapperImpl;
+
+		      
+// 1. Instantiate a JCR session
+Repository repository = ...;
+Session session = repository.login(...);
+		      
+// 2. Register the different persistent classes
+List classes = new ArrayList();
+classes.add(MyContent.class); // Call this method for each persistent class
+
+				      
+// 3. Instantiate the object content manager
+Mapper mapper = new AnnotationMapperImpl(classes);
+ObjectContentManager ocm = new ObjectContentManagerImpl(session, mapper);
+{code}
+
+h2. Basic setup (with one or more XML Mapping Descriptor files)
+
+When you start your application, you need the following code to initialize correctly the Object Content Manager.
+{code}
+import javax.jcr.Session;
+import javax.jcr.Repository;
+
+import org.apache.jackrabbit.ocm.mapper.Mapper;
+import org.apache.jackrabbit.ocm.mapper.impl.digester.DigesterMapperImpl;
+import org.apache.jackrabbit.ocm.manager.ObjectContentManager;
+import org.apache.jackrabbit.ocm.manager.impl.ObjectContentManagerImpl;
+import org.apache.jackrabbit.ocm.manager.atomictypeconverter.AtomicTypeConverterProvider;
+import org.apache.jackrabbit.ocm.manager.atomictypeconverter.impl.DefaultAtomicTypeConverterProvider;
+import org.apache.jackrabbit.ocm.manager.objectconverter.ObjectConverter;
+import org.apache.jackrabbit.ocm.manager.objectconverter.impl.ObjectConverterImpl;
+import org.apache.jackrabbit.ocm.query.QueryManager;
+import org.apache.jackrabbit.ocm.query.impl.QueryManagerImpl;
+
+// 1. Instantiate a JCR session
+Repository repository = ...;
+Session session = repository.login(...);
+
+// 2. Specify the different mapping files
+String[] files = {
+      "./src/test-config/jcrmapping.xml",
+      "./src/test-config/jcrmapping-atomic.xml",
+      "./src/test-config/jcrmapping-beandescriptor.xml"
+  };
+
+// 3. Instantiate the object content manager
+ObjectContentManager ocm = new ObjectContentManagerImpl(session, files);
+
+{code}
+
+
+h2. API Overview
+
+With the current Object Manager API, it is possible to:
+
+* Manage the object life cycle (insert, update, delete, retrieve). See [Basic OCM operations].
+* Search single object or collections with criteria. See [OCM Search].
+* Lock objects. See [OCM Locking].
+* Manage versions (check int, check out, create a new version, show history). See [OCM Version Management].
+
+We plan to add other features in a future release. 
\ No newline at end of file

Propchange: jackrabbit/site/trunk/content/object-content-manager.cwiki
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jackrabbit/site/trunk/content/object-content-manager.mdtext
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/object-content-manager.mdtext?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/object-content-manager.mdtext (added)
+++ jackrabbit/site/trunk/content/object-content-manager.mdtext Tue Jan 10 18:50:59 2012
@@ -0,0 +1,150 @@
+Title: Object Content Manager
+The main component in the OCM framework is the ObjectContentManager. It
+converts an object graph into JCR nodes and properties and vice versa. The
+ObjectContentManager is always associated with a JCR Session. It is used to
+retrieve, create, update and delete objects from a JCR content repository.
+Usually there is one ObjectContentManager per user session.
+
+This page describes how an ObjectContentManager is working and how it can
+be initialised in your applications. 
+
+<a name="ObjectContentManager-HowdoestheObjectContentManagerwork?"></a>
+## How does the Object Content Manager work ?
+
+Thanks to a Mapping Descriptor, the ObjectContentManager is able to use the
+appropriate mapping strategy for each persistent object (pojo). The Mapping
+Descriptor contains one Class Descriptor per persistent class. Each Class
+Descriptor contains mapping information for the corresponding class
+attributes.
+
+In the point of view implementation, the Mappring Descriptor is a java
+object injected into the ObjectContentManager (see the interface
+org.apache.jackrabbit.ocm.mapper.Mapper). Right now, there are 2 different
+Mapping Descriptor implementations:
+
+    * Annotation : each persistent object is annoted in order to provide to
+the ObjectContentManager all the required information on its mapping
+strategy (see the class
+org.apache.jackrabbit.ocm.mapper.impl.annotation.AnnotationMapperImpl).
+    * XML configuration file : the class descriptors are defined in one or
+more XML config files used by the ObjectContentManager when it is
+instantiated (see the class
+org.apache.jackrabbit.ocm.mapper.impl.digester.DigesterMapperImpl). 
+
+For a business developer, it is not necessary to know how the
+ObjectContentManager is using the Class Descriptors. He has to make only a
+choice between annoted classes or XML files. Below, you can see how to
+setup correctly an ObjectContentManager. 
+
+<a name="ObjectContentManager-HowdoesanobjectispersistedintoaJCRrepository?"></a>
+## How does an object is persisted into a JCR repository ?
+
+In all cases, a persistent object (a pojo) is mapped into a JCR node and
+its fields are mapped into subnodes or properties depending on their types.
+
+There are 3 "field types":
+
+* Atomic fields
+    Primitive data types and simple objects (String, Long, Double, ...) .
+Those fields are mapped into JCR properties. 
+
+* Bean fields
+    One class can contain an 1..1 association to another bean. In this
+case, the field is a custom object. Those fields are mapped into JCR
+subnodes or a referenced node. 
+
+* Collection fields
+    One class can contain an 1..n association to a collection of beans (or
+Map). Those fields are mapped into a collection of JCR subnodes or a
+collection of referenced nodes. It is also possible to map a java
+collection into a multivalue property. 
+
+The Mapping descriptor contains also information on inheritances, interface
+mapping strategy, lazy loading, custom converter, cache strategy, etc. 
+<a name="ObjectContentManager-Basicsetup(withannotedpersistentclasses)"></a>
+## Basic setup (with annoted persistent classes)
+
+When you start your application, you need the following code to initialize
+correctly the Object Content Manager.
+
+
+    import javax.jcr.Session;
+    import javax.jcr.Repository;
+    		      
+    import org.apache.jackrabbit.ocm.manager.impl.ObjectContentManagerImpl;
+    import org.apache.jackrabbit.ocm.mapper.Mapper;
+    import
+org.apache.jackrabbit.ocm.mapper.impl.annotation.AnnotationMapperImpl;
+    
+    		      
+    // 1. Instantiate a JCR session
+    Repository repository = ...;
+    Session session = repository.login(...);
+    		      
+    // 2. Register the different persistent classes
+    List classes = new ArrayList();
+    classes.add(MyContent.class); // Call this method for each persistent class
+    
+    				      
+    // 3. Instantiate the object content manager
+    Mapper mapper = new AnnotationMapperImpl(classes);
+    ObjectContentManager ocm = new ObjectContentManagerImpl(session, mapper);
+
+
+<a name="ObjectContentManager-Basicsetup(withoneormoreXMLMappingDescriptorfiles)"></a>
+## Basic setup (with one or more XML Mapping Descriptor files)
+
+When you start your application, you need the following code to initialize
+correctly the Object Content Manager.
+
+    import javax.jcr.Session;
+    import javax.jcr.Repository;
+    
+    import org.apache.jackrabbit.ocm.mapper.Mapper;
+    import org.apache.jackrabbit.ocm.mapper.impl.digester.DigesterMapperImpl;
+    import org.apache.jackrabbit.ocm.manager.ObjectContentManager;
+    import org.apache.jackrabbit.ocm.manager.impl.ObjectContentManagerImpl;
+    import
+org.apache.jackrabbit.ocm.manager.atomictypeconverter.AtomicTypeConverterProvider;
+    import
+org.apache.jackrabbit.ocm.manager.atomictypeconverter.impl.DefaultAtomicTypeConverterProvider;
+    import org.apache.jackrabbit.ocm.manager.objectconverter.ObjectConverter;
+    import
+org.apache.jackrabbit.ocm.manager.objectconverter.impl.ObjectConverterImpl;
+    import org.apache.jackrabbit.ocm.query.QueryManager;
+    import org.apache.jackrabbit.ocm.query.impl.QueryManagerImpl;
+    
+    // 1. Instantiate a JCR session
+    Repository repository = ...;
+    Session session = repository.login(...);
+    
+    // 2. Specify the different mapping files
+    String[]
+ files = {
+          "./src/test-config/jcrmapping.xml",
+          "./src/test-config/jcrmapping-atomic.xml",
+          "./src/test-config/jcrmapping-beandescriptor.xml"
+      };
+    
+    // 3. Instantiate the object content manager
+    ObjectContentManager ocm = new ObjectContentManagerImpl(session, files);
+    
+
+
+
+<a name="ObjectContentManager-APIOverview"></a>
+## API Overview
+
+With the current Object Manager API, it is possible to:
+
+* Manage the object life cycle (insert, update, delete, retrieve). See [Basic OCM operations](basic-ocm-operations.html)
+.
+* Search single object or collections with criteria. See [OCM Search](ocm-search.html)
+.
+* Lock objects. See [OCM Locking](ocm-locking.html)
+.
+* Manage versions (check int, check out, create a new version, show
+history). See [OCM Version Management](ocm-version-management.html)
+.
+
+We plan to add other features in a future release. 

Propchange: jackrabbit/site/trunk/content/object-content-manager.mdtext
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jackrabbit/site/trunk/content/object-content-mapping.cwiki
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/object-content-mapping.cwiki?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/object-content-mapping.cwiki (added)
+++ jackrabbit/site/trunk/content/object-content-mapping.cwiki Tue Jan 10 18:50:59 2012
@@ -0,0 +1,34 @@
+{warning:title=Warning}
+The Jackrabbit OCM documentation is still in progress. We advise you also to review  [the unit tests|http://svn.apache.org/viewvc/jackrabbit/trunk/jackrabbit-ocm/src/test/]to get an overview on current OCM features.
+{warning}
+
+* [Object Content Manager]
+** [Basic OCM operations]
+** [OCM Search]
+** [OCM Version Management]
+** [OCM Locking]
+* Tutorials
+** [5' with Jackrabbit OCM]
+** [A simple OCM project with Maven & Eclipse]
+** [How to map associations between objects]
+* [Mapping Stategies] (obsolete doc)
+** [Mapping Atomic Fields] (obsolete doc)
+** [Mapping Bean Fields] (obsolete doc)
+** [Mapping Collection Fields] (obsolete doc)
+** [Advanced Mapping Strategies] (obsolete doc)
+
+Jackrabbit OCM is a framework used to persist java objects (pojos) in a JCR repository including association, inheritance, polymorphism, composition, and the Java collections framework. It offers also features like version support, object locking and express queries with Java-based criteria, as well as with JCR query languages.
+
+In order to easily support the JCR specification, any content application managing an high level object model can use this framework. For example, a classic Forum application contains objects like "Forum", "Topic" and "Post". Now, the data objects (pojo) can be managed by our JCR mapping tools in order to persist them into a JCR compliant repository.
+
+h2. Why an ocm?
+
+The object content mapping framework was created for the following different reasons:
+
+* Sometimes it is very convenient to be able to just access the JCR nodes and properties directly from your presentation-layer for very simple things (mostly generic display). When a lot of "business logic" are involved, the JCR API can be too low level and real business objects (pojo) are more appreciate in such cases.
+* The OCM framework provides more abstraction on the technologies used to persist your content. The different application layers are less dependent on the JCR API.
+* ORM tools like OJB or Hibernate are not appropriate for content oriented application.
+
+h2. Prerequisite
+
+Before using this OCM framework, you should review the JCR specification and implementations like Apache Jackrabbit.
\ No newline at end of file

Propchange: jackrabbit/site/trunk/content/object-content-mapping.cwiki
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jackrabbit/site/trunk/content/object-content-mapping.mdtext
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/object-content-mapping.mdtext?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/object-content-mapping.mdtext (added)
+++ jackrabbit/site/trunk/content/object-content-mapping.mdtext Tue Jan 10 18:50:59 2012
@@ -0,0 +1,61 @@
+Title: Object Content Mapping
+{warning:title=Warning}
+The Jackrabbit OCM documentation is still in progress. We advise you also
+to review  [the unit tests](http://svn.apache.org/viewvc/jackrabbit/trunk/jackrabbit-ocm/src/test/)
+to get an overview on current OCM features.
+{warning}
+
+* [Object Content Manager](object-content-manager.html)
+** [Basic OCM operations](basic-ocm-operations.html)
+** [OCM Search](ocm-search.html)
+** [OCM Version Management](ocm-version-management.html)
+** [OCM Locking](ocm-locking.html)
+* Tutorials
+** [5' with Jackrabbit OCM](5'-with-jackrabbit-ocm.html)
+** [A simple OCM project with Maven & Eclipse](a-simple-ocm-project-with-maven-&-eclipse.html)
+** [How to map associations between objects](how-to-map-associations-between-objects.html)
+* [Mapping Stategies](mapping-stategies.html)
+ (obsolete doc)
+** [Mapping Atomic Fields](mapping-atomic-fields.html)
+ (obsolete doc)
+** [Mapping Bean Fields](mapping-bean-fields.html)
+ (obsolete doc)
+** [Mapping Collection Fields](mapping-collection-fields.html)
+ (obsolete doc)
+** [Advanced Mapping Strategies](advanced-mapping-strategies.html)
+ (obsolete doc)
+
+Jackrabbit OCM is a framework used to persist java objects (pojos) in a JCR
+repository including association, inheritance, polymorphism, composition,
+and the Java collections framework. It offers also features like version
+support, object locking and express queries with Java-based criteria, as
+well as with JCR query languages.
+
+In order to easily support the JCR specification, any content application
+managing an high level object model can use this framework. For example, a
+classic Forum application contains objects like "Forum", "Topic" and
+"Post". Now, the data objects (pojo) can be managed by our JCR mapping
+tools in order to persist them into a JCR compliant repository.
+
+<a name="ObjectContentMapping-Whyanocm?"></a>
+## Why an ocm?
+
+The object content mapping framework was created for the following
+different reasons:
+
+* Sometimes it is very convenient to be able to just access the JCR nodes
+and properties directly from your presentation-layer for very simple things
+(mostly generic display). When a lot of "business logic" are involved, the
+JCR API can be too low level and real business objects (pojo) are more
+appreciate in such cases.
+* The OCM framework provides more abstraction on the technologies used to
+persist your content. The different application layers are less dependent
+on the JCR API.
+* ORM tools like OJB or Hibernate are not appropriate for content oriented
+application.
+
+<a name="ObjectContentMapping-Prerequisite"></a>
+## Prerequisite
+
+Before using this OCM framework, you should review the JCR specification
+and implementations like Apache Jackrabbit.

Propchange: jackrabbit/site/trunk/content/object-content-mapping.mdtext
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jackrabbit/site/trunk/content/ocm-locking.cwiki
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/ocm-locking.cwiki?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/ocm-locking.cwiki (added)
+++ jackrabbit/site/trunk/content/ocm-locking.cwiki Tue Jan 10 18:50:59 2012
@@ -0,0 +1,65 @@
+Following the Jcr specification, it is possible to lock nodes and their children (see section 8.4). You can see on this page the OCM API used to lock on the object level. In order to lock an object, its matching node has to implement the jcr mixin type "mix:lockable". It is possible to specify this node type in the class descriptor:
+
+h2. A basic example
+
+{code}
+// --------------------------------------------------------------------------------
+// Create and store an object graph in the repository
+// --------------------------------------------------------------------------------
+A a = new A();
+a.setPath("/test");
+a.setA1("a1");
+a.setA2("a2");
+B b = new B();
+b.setB1("b1");
+b.setB2("b2");
+a.setB(b);
+
+C c1 = new C();
+c1.setId("first");
+c1.setName("First Element");
+C c2 = new C();
+c2.setId("second");
+c2.setName("Second Element");
+
+C c3 = new C();
+c3.setId("third");
+c3.setName("Third Element");
+
+Collection collection = new ArrayList();
+collection.add(c1);
+collection.add(c2);
+collection.add(c3);
+
+a.setCollection(collection);
+
+ocm.insert(a);
+ocm.save();
+
+
+// --------------------------------------------------------------------------------
+// Check if the object is not locked
+// --------------------------------------------------------------------------------
+if (ocm.isLocked("/test"))
+{
+   System.out.println("Error : The object is locked- humm ??");
+}
+
+// --------------------------------------------------------------------------------
+// Lock the object
+// --------------------------------------------------------------------------------
+String lockToken = ocm.lock("/test", true, false);
+
+// --------------------------------------------------------------------------------
+// Check if the object is not locked
+// --------------------------------------------------------------------------------
+if (! ocm.isLocked("/test"))
+{
+   System.out.println("Error : The object is not locked- humm ??");
+}
+
+// --------------------------------------------------------------------------------
+// Unlock the object
+// --------------------------------------------------------------------------------
+ocm.unlock("/test", lockToken);
+{code}

Propchange: jackrabbit/site/trunk/content/ocm-locking.cwiki
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jackrabbit/site/trunk/content/ocm-locking.mdtext
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/ocm-locking.mdtext?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/ocm-locking.mdtext (added)
+++ jackrabbit/site/trunk/content/ocm-locking.mdtext Tue Jan 10 18:50:59 2012
@@ -0,0 +1,81 @@
+Title: OCM Locking
+Following the Jcr specification, it is possible to lock nodes and their
+children (see section 8.4). You can see on this page the OCM API used to
+lock on the object level. In order to lock an object, its matching node has
+to implement the jcr mixin type "mix:lockable". It is possible to specify
+this node type in the class descriptor:
+
+<a name="OCMLocking-Abasicexample"></a>
+## A basic example
+
+
+    //
+--------------------------------------------------------------------------------
+    // Create and store an object graph in the repository
+    //
+--------------------------------------------------------------------------------
+    A a = new A();
+    a.setPath("/test");
+    a.setA1("a1");
+    a.setA2("a2");
+    B b = new B();
+    b.setB1("b1");
+    b.setB2("b2");
+    a.setB(b);
+    
+    C c1 = new C();
+    c1.setId("first");
+    c1.setName("First Element");
+    C c2 = new C();
+    c2.setId("second");
+    c2.setName("Second Element");
+    
+    C c3 = new C();
+    c3.setId("third");
+    c3.setName("Third Element");
+    
+    Collection collection = new ArrayList();
+    collection.add(c1);
+    collection.add(c2);
+    collection.add(c3);
+    
+    a.setCollection(collection);
+    
+    ocm.insert(a);
+    ocm.save();
+    
+    
+    //
+--------------------------------------------------------------------------------
+    // Check if the object is not locked
+    //
+--------------------------------------------------------------------------------
+    if (ocm.isLocked("/test"))
+    {
+       System.out.println("Error : The object is locked- humm ??");
+    }
+    
+    //
+--------------------------------------------------------------------------------
+    // Lock the object
+    //
+--------------------------------------------------------------------------------
+    String lockToken = ocm.lock("/test", true, false);
+    
+    //
+--------------------------------------------------------------------------------
+    // Check if the object is not locked
+    //
+--------------------------------------------------------------------------------
+    if (! ocm.isLocked("/test"))
+    {
+       System.out.println("Error : The object is not locked- humm ??");
+    }
+    
+    //
+--------------------------------------------------------------------------------
+    // Unlock the object
+    //
+--------------------------------------------------------------------------------
+    ocm.unlock("/test", lockToken);
+

Propchange: jackrabbit/site/trunk/content/ocm-locking.mdtext
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jackrabbit/site/trunk/content/ocm-search.cwiki
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/ocm-search.cwiki?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/ocm-search.cwiki (added)
+++ jackrabbit/site/trunk/content/ocm-search.cwiki Tue Jan 10 18:50:59 2012
@@ -0,0 +1,44 @@
+
+h2. Searching a single object
+
+{code}
+QueryManager queryManager = ocm.getQueryManager();
+
+// Build the search filter
+Filter filter = queryManager.createFilter(Paragraph.class);
+filter.addEqualTo("text", "Para 1");   // Text is an attribute in the class Paragraph
+
+// Build the query
+Query query = queryManager.createQuery(filter);
+Paragraph paragraph = (Paragraph) ocm.getObject(query);
+{code}
+
+h2. Searching a collection
+
+{code}
+QueryManager queryManager = ocm.getQueryManager();
+Filter filter = queryManager.createFilter(Paragraph.class);
+filter.setScope("/test/node1//");
+Query query = queryManager.createQuery(filter);
+Collection result = ocm.getObjects(query);
+{code}
+
+h2. Searching with an iterator
+
+{code}
+QueryManager queryManager = ocm.getQueryManager();
+Filter filter = queryManager.createFilter(Paragraph.class);
+filter.setScope("/test/node1//");
+Query query = queryManager.createQuery(filter);
+Iterator iterator = ocm.getObjectIterator(query);
+{code}
+
+h2. Remove objects based on a query
+
+{code}
+QueryManager queryManager = ocm.getQueryManager();
+Filter filter = queryManager.createFilter(Paragraph.class);
+filter.setScope("/test/node1//");
+Query query = queryManager.createQuery(filter);
+ocm.remove(query);
+{code}

Propchange: jackrabbit/site/trunk/content/ocm-search.cwiki
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jackrabbit/site/trunk/content/ocm-search.mdtext
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/ocm-search.mdtext?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/ocm-search.mdtext (added)
+++ jackrabbit/site/trunk/content/ocm-search.mdtext Tue Jan 10 18:50:59 2012
@@ -0,0 +1,50 @@
+Title: OCM Search
+
+<a name="OCMSearch-Searchingasingleobject"></a>
+## Searching a single object
+
+
+    QueryManager queryManager = ocm.getQueryManager();
+    
+    // Build the search filter
+    Filter filter = queryManager.createFilter(Paragraph.class);
+    filter.addEqualTo("text", "Para 1");   // Text is an attribute in the class
+Paragraph
+    
+    // Build the query
+    Query query = queryManager.createQuery(filter);
+    Paragraph paragraph = (Paragraph) ocm.getObject(query);
+
+
+<a name="OCMSearch-Searchingacollection"></a>
+## Searching a collection
+
+
+    QueryManager queryManager = ocm.getQueryManager();
+    Filter filter = queryManager.createFilter(Paragraph.class);
+    filter.setScope("/test/node1//");
+    Query query = queryManager.createQuery(filter);
+    Collection result = ocm.getObjects(query);
+
+
+<a name="OCMSearch-Searchingwithaniterator"></a>
+## Searching with an iterator
+
+
+    QueryManager queryManager = ocm.getQueryManager();
+    Filter filter = queryManager.createFilter(Paragraph.class);
+    filter.setScope("/test/node1//");
+    Query query = queryManager.createQuery(filter);
+    Iterator iterator = ocm.getObjectIterator(query);
+
+
+<a name="OCMSearch-Removeobjectsbasedonaquery"></a>
+## Remove objects based on a query
+
+
+    QueryManager queryManager = ocm.getQueryManager();
+    Filter filter = queryManager.createFilter(Paragraph.class);
+    filter.setScope("/test/node1//");
+    Query query = queryManager.createQuery(filter);
+    ocm.remove(query);
+

Propchange: jackrabbit/site/trunk/content/ocm-search.mdtext
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jackrabbit/site/trunk/content/ocm-version-management.cwiki
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/ocm-version-management.cwiki?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/ocm-version-management.cwiki (added)
+++ jackrabbit/site/trunk/content/ocm-version-management.cwiki Tue Jan 10 18:50:59 2012
@@ -0,0 +1,101 @@
+Right now, the OCM tools provides basic versioning features:
+
+* Check in, check out.
+* Retrieve version history (first version, last version, the complete history, ...).
+* Apply labels.
+
+Later, we would like to add more advanced versioning support like version compare, replace, revert, ... Each versioned object has to be mapped to a mix:versionable JCR node. It is possible to specify this node type in the xml class descriptor or with an annotation :
+
+h2. Check in - Check out
+
+{code}
+// Create a new page - first version
+Page page = new Page();
+page.setPath("/page");
+page.setTitle("Page Title");
+page.addParagraph(new Paragraph("para1"));
+page.addParagraph(new Paragraph("para2"));
+ocm.insert(page);
+ocm.save();
+
+// Update the page object and create a new version
+page.addParagraph(new Paragraph("para3"));
+ocm.checkout("/page");
+ocm.update(page);
+ocm.save();
+ocm.checkin("/page");
+
+// Update the page object and create a new version
+page.addParagraph(new Paragraph("para4"));
+ocm.checkout("/page");
+ocm.update(page);
+ocm.save();
+ocm.checkin("/page");
+{code}
+
+h2. Retrieve the version history
+
+{code}
+VersionIterator versionIterator = ocm.getAllVersions("/page");
+while (versionIterator.hasNext())
+{
+    Version version = (Version) versionIterator.next();
+    System.out.println("version found : "+ version.getName() + " - " +
+                          version.getPath() + " - " +  version.getCreated().getTime());
+}
+{code}
+
+h2. Retrieve version description
+
+{code}
+// Retrieve the first version description
+Version baseVersion = ocm.getBaseVersion("/page");
+System.out.println("Base version : " + baseVersion.getName());
+
+// Retrieve the latest version description
+Version rootVersion = ocm.getRootVersion("/page");
+System.out.println("Root version : " + rootVersion.getName());
+{code}
+
+h2. Retrieve the object state matching to a specific version
+
+{code}
+//Get the object matching to the first version
+Page  page = (Page) ocm.getObject( "/page", "1.0");
+{code}
+
+h2. Using version labels
+
+{code}
+Page page = new Page();
+page.setPath("/page");
+page.setTitle("Page Title");
+page.addParagraph(new Paragraph("para1"));
+page.addParagraph(new Paragraph("para2"));
+ocm.insert(page);
+ocm.save();
+
+// Checkin with some labels
+page.addParagraph(new Paragraph("para3"));
+ocm.checkout("/page");
+ocm.update(page);
+ocm.save();
+ocm.checkin("/page", new String[] {"A", "B"});
+
+// Checkin with some labels
+page.addParagraph(new Paragraph("para4"));
+ocm.checkout("/page");
+ocm.update(page);
+ocm.save();
+ocm.checkin("/page", new String[] {"C", "D"});
+
+// Retrieve all labels
+String[] allLabels = ocm.getAllVersionLabels("/page");
+assertTrue("Incorrect number of labels", allLabels.length == 4);
+
+// Retrieve labels assigned to the version 1.1
+String[] versionLabels = ocm.getVersionLabels("/page", "1.1");
+assertTrue("Incorrect number of labels", versionLabels.length == 2);
+assertTrue("Incorrect label", versionLabels[0].equals("C") || versionLabels[0].equals("D"));
+assertTrue("Incorrect label", versionLabels[1].equals("C") || versionLabels[0].equals("D"));
+{code}

Propchange: jackrabbit/site/trunk/content/ocm-version-management.cwiki
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jackrabbit/site/trunk/content/ocm-version-management.mdtext
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/ocm-version-management.mdtext?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/ocm-version-management.mdtext (added)
+++ jackrabbit/site/trunk/content/ocm-version-management.mdtext Tue Jan 10 18:50:59 2012
@@ -0,0 +1,118 @@
+Title: OCM Version Management
+Right now, the OCM tools provides basic versioning features:
+
+* Check in, check out.
+* Retrieve version history (first version, last version, the complete
+history, ...).
+* Apply labels.
+
+Later, we would like to add more advanced versioning support like version
+compare, replace, revert, ... Each versioned object has to be mapped to a
+mix:versionable JCR node. It is possible to specify this node type in the
+xml class descriptor or with an annotation :
+
+<a name="OCMVersionManagement-Checkin-Checkout"></a>
+## Check in - Check out
+
+
+    // Create a new page - first version
+    Page page = new Page();
+    page.setPath("/page");
+    page.setTitle("Page Title");
+    page.addParagraph(new Paragraph("para1"));
+    page.addParagraph(new Paragraph("para2"));
+    ocm.insert(page);
+    ocm.save();
+    
+    // Update the page object and create a new version
+    page.addParagraph(new Paragraph("para3"));
+    ocm.checkout("/page");
+    ocm.update(page);
+    ocm.save();
+    ocm.checkin("/page");
+    
+    // Update the page object and create a new version
+    page.addParagraph(new Paragraph("para4"));
+    ocm.checkout("/page");
+    ocm.update(page);
+    ocm.save();
+    ocm.checkin("/page");
+
+
+<a name="OCMVersionManagement-Retrievetheversionhistory"></a>
+## Retrieve the version history
+
+
+    VersionIterator versionIterator = ocm.getAllVersions("/page");
+    while (versionIterator.hasNext())
+    {
+        Version version = (Version) versionIterator.next();
+        System.out.println("version found : "+ version.getName() + " - " +
+    			  version.getPath() + " - " + 
+version.getCreated().getTime());
+    }
+
+
+<a name="OCMVersionManagement-Retrieveversiondescription"></a>
+## Retrieve version description
+
+
+    // Retrieve the first version description
+    Version baseVersion = ocm.getBaseVersion("/page");
+    System.out.println("Base version : " + baseVersion.getName());
+    
+    // Retrieve the latest version description
+    Version rootVersion = ocm.getRootVersion("/page");
+    System.out.println("Root version : " + rootVersion.getName());
+
+
+<a name="OCMVersionManagement-Retrievetheobjectstatematchingtoaspecificversion"></a>
+## Retrieve the object state matching to a specific version
+
+
+    //Get the object matching to the first version
+    Page  page = (Page) ocm.getObject( "/page", "1.0");
+
+
+<a name="OCMVersionManagement-Usingversionlabels"></a>
+## Using version labels
+
+
+    Page page = new Page();
+    page.setPath("/page");
+    page.setTitle("Page Title");
+    page.addParagraph(new Paragraph("para1"));
+    page.addParagraph(new Paragraph("para2"));
+    ocm.insert(page);
+    ocm.save();
+    
+    // Checkin with some labels
+    page.addParagraph(new Paragraph("para3"));
+    ocm.checkout("/page");
+    ocm.update(page);
+    ocm.save();
+    ocm.checkin("/page", new String[]
+ {"A", "B"});
+    
+    // Checkin with some labels
+    page.addParagraph(new Paragraph("para4"));
+    ocm.checkout("/page");
+    ocm.update(page);
+    ocm.save();
+    ocm.checkin("/page", new String[]
+ {"C", "D"});
+    
+    // Retrieve all labels
+    String[]
+ allLabels = ocm.getAllVersionLabels("/page");
+    assertTrue("Incorrect number of labels", allLabels.length == 4);
+    
+    // Retrieve labels assigned to the version 1.1
+    String[]
+ versionLabels = ocm.getVersionLabels("/page", "1.1");
+    assertTrue("Incorrect number of labels", versionLabels.length == 2);
+    assertTrue("Incorrect label", versionLabels[0]
+.equals("C") || versionLabels[0].equals("D"));
+    assertTrue("Incorrect label", versionLabels[1]
+.equals("C") || versionLabels[0].equals("D"));
+

Propchange: jackrabbit/site/trunk/content/ocm-version-management.mdtext
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jackrabbit/site/trunk/content/privacy-policy.cwiki
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/privacy-policy.cwiki?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/privacy-policy.cwiki (added)
+++ jackrabbit/site/trunk/content/privacy-policy.cwiki Tue Jan 10 18:50:59 2012
@@ -0,0 +1,13 @@
+Information about your use of this website is collected using server access logs and a tracking cookie. The collected information consists of the following:
+
+  # The IP address from which you access the website;
+  # The type of browser and operating system you use to access our site;
+  # The date and time you access our site;
+  # The pages you visit; and
+  # The addresses of pages from where you followed a link to our site.
+
+Part of this information is gathered using a tracking cookie set by the [Google Analytics|http://www.google.com/analytics/] service and handled by Google as described in their [privacy policy|http://www.google.com/privacy.html]. See your browser documentation for instructions on how to disable the cookie if you prefer not to share this data with Google.
+
+We use the gathered information to help us make our site more useful to visitors and to better understand how and when our site is used. We do not track or collect personally identifiable information or associate gathered data with any personally identifying information from other sources.
+
+By using this website, you consent to the collection of this data in the manner and for the purpose described above.
\ No newline at end of file

Propchange: jackrabbit/site/trunk/content/privacy-policy.cwiki
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jackrabbit/site/trunk/content/privacy-policy.mdtext
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/privacy-policy.mdtext?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/privacy-policy.mdtext (added)
+++ jackrabbit/site/trunk/content/privacy-policy.mdtext Tue Jan 10 18:50:59 2012
@@ -0,0 +1,23 @@
+Title: Privacy Policy
+Information about your use of this website is collected using server access
+logs and a tracking cookie. The collected information consists of the
+following:
+
+1. The IP address from which you access the website;
+1. The type of browser and operating system you use to access our site;
+1. The date and time you access our site;
+1. The pages you visit; and
+1. The addresses of pages from where you followed a link to our site.
+
+Part of this information is gathered using a tracking cookie set by the [Google Analytics](http://www.google.com/analytics/)
+ service and handled by Google as described in their [privacy policy|http://www.google.com/privacy.html]
+. See your browser documentation for instructions on how to disable the
+cookie if you prefer not to share this data with Google.
+
+We use the gathered information to help us make our site more useful to
+visitors and to better understand how and when our site is used. We do not
+track or collect personally identifiable information or associate gathered
+data with any personally identifying information from other sources.
+
+By using this website, you consent to the collection of this data in the
+manner and for the purpose described above.

Propchange: jackrabbit/site/trunk/content/privacy-policy.mdtext
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jackrabbit/site/trunk/content/repository-lifecycle.cwiki
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/repository-lifecycle.cwiki?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/repository-lifecycle.cwiki (added)
+++ jackrabbit/site/trunk/content/repository-lifecycle.cwiki Tue Jan 10 18:50:59 2012
@@ -0,0 +1,27 @@
+The lifecycle of any Jackrabbit Content Repository starts with a call to one of the RepositoryFactory.create() methods passing optionally the source of a repository configuration file (which by convention is called config.xml) and the RepositoryFactoryHome, which points to a directory from which the Repository will continue reading further information for start-up and in many cases will store the actual data that is persisted in the repository and its workspaces.
+
+Not supplying the RepositoryFactoryHome will default to the users home dir from the System property user.dir.
+
+Not supplying the configuration file parameter will default to the value of Repository.factory.config System Property and if that is not set it will default to the config.xml in the RepositoryFactoryHome.
+
+Calling the create() method will instantiate the RepositoryFactory singleton that will then, through the getRepository(String name) method, serve as the factory for Repository instances.
+
+As per the config.xml a repository are started up with the respectively configured RepositoryStore, the RepositoryStore defines where the repository stores information that is visible for the entire Repository which includes things like the uuid of the root node, repository properties, the namespace registry, node type definitions or the version backing store in a file structure as follows.
+
+{code}
+./meta:
+rep.properties
+rootUUID
+
+./namespaces:
+ns_reg.properties
+
+./nodetypes:
+custom_nodetypes.xml
+
+./versions:
+{code}
+
+The RepositoryStore normally points to a regular (i.e. local) file system but is abstracted through an abstract FileSystem that can be configured to point to a different FileSystem implementation, in case the above information should be stored in a different data container.
+
+... to be continued ... 
\ No newline at end of file

Propchange: jackrabbit/site/trunk/content/repository-lifecycle.cwiki
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jackrabbit/site/trunk/content/repository-lifecycle.mdtext
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/repository-lifecycle.mdtext?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/repository-lifecycle.mdtext (added)
+++ jackrabbit/site/trunk/content/repository-lifecycle.mdtext Tue Jan 10 18:50:59 2012
@@ -0,0 +1,47 @@
+Title: Repository lifecycle
+The lifecycle of any Jackrabbit Content Repository starts with a call to
+one of the RepositoryFactory.create() methods passing optionally the source
+of a repository configuration file (which by convention is called
+config.xml) and the RepositoryFactoryHome, which points to a directory from
+which the Repository will continue reading further information for start-up
+and in many cases will store the actual data that is persisted in the
+repository and its workspaces.
+
+Not supplying the RepositoryFactoryHome will default to the users home dir
+from the System property user.dir.
+
+Not supplying the configuration file parameter will default to the value of
+Repository.factory.config System Property and if that is not set it will
+default to the config.xml in the RepositoryFactoryHome.
+
+Calling the create() method will instantiate the RepositoryFactory
+singleton that will then, through the getRepository(String name) method,
+serve as the factory for Repository instances.
+
+As per the config.xml a repository are started up with the respectively
+configured RepositoryStore, the RepositoryStore defines where the
+repository stores information that is visible for the entire Repository
+which includes things like the uuid of the root node, repository
+properties, the namespace registry, node type definitions or the version
+backing store in a file structure as follows.
+
+
+    ./meta:
+    rep.properties
+    rootUUID
+    
+    ./namespaces:
+    ns_reg.properties
+    
+    ./nodetypes:
+    custom_nodetypes.xml
+    
+    ./versions:
+
+
+The RepositoryStore normally points to a regular (i.e. local) file system
+but is abstracted through an abstract FileSystem that can be configured to
+point to a different FileSystem implementation, in case the above
+information should be stored in a different data container.
+
+... to be continued ... 

Propchange: jackrabbit/site/trunk/content/repository-lifecycle.mdtext
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jackrabbit/site/trunk/content/repository-server-howto.cwiki
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/repository-server-howto.cwiki?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/repository-server-howto.cwiki (added)
+++ jackrabbit/site/trunk/content/repository-server-howto.cwiki Tue Jan 10 18:50:59 2012
@@ -0,0 +1,49 @@
+This document describes how to use a Jackrabbit content repository in the deployment model 3: The Repository Server. In this deployment model, a separate repository server is running outside the virtual machine the client application is running in. A repository server can serve multiple applications running on separate JVMs on separate network hosts. See the [JCR client application HOWTO] for instructions on how to use the configured content repository server.
+
+Note that JCR specification defines no standard communication protocol for inter-JVM repository access, and that Jackrabbit supports no such protocol by default. However, Jackrabbit contains tools for using JCR content repositories over the RMI and WebDAV protocols (see the jcr-rmi and the jcr-server, webapp packages).
+
+This how-to contains instructions for accessing a JCR-RMI server in Tomcat versions 4.x and 5.x. It should be easy to modify the instructions for other container environments and communication protocols.
+
+In addition to the following the instructions in this document, you also need to have an already running JCR-RMI server. See the JCR-RMI javadocs for instructions on how to setup such a server.
+
+Warning: The current JCR-RMI library is designed for simplicity, not performance. You will probably experience major performance issues if you try running any non-trivial applications on top of JCR-RMI.
+
+h2. Tomcat instructions
+
+Follow the steps below to setup a model 3 JCR-RMI client deployment for your web application in Tomcat 4.x or 5.x. Example code for both versions of Tomcat is included after this overview.
+
+Note that these instructions closely follow the Model 1 HOWTO instructions. By making similar changes (change the factory class and parameters of the repository) to the Model 2 HOWTO instructions, you can setup a shared JCR-RMI client deployment for all applications in the container.
+
+# Place the JCR-RMI jar file and its dependencies (including the JCR API jar) under _Tomcat folder_/webapps/_your app_/WEB-INF/lib.
+# Register the JCR-RMI client repository factory in the context scope.
+
+h3. Step 2 - Context configuration
+
+In Tomcat 4.x and 5.0, add the following snippet in server.xml under the Context element of your web application.
+
+{code}
+<Resource name="jcr/repository"
+          auth="Container"
+          type="javax.jcr.Repository"/>
+
+<ResourceParams name="jcr/repository">
+  <parameter>
+    <name>factory</name>
+    <value>org.apache.jackrabbit.rmi.client.ClientRepositoryFactory</value>
+  </parameter>
+  <parameter>
+    <name>url</name>
+    <value>[The RMI URL of the repository]</value>
+  </parameter>
+</ResourceParams>
+{code}
+
+In Tomcat 5.5, add the following snippet in your application's context.xml file (or in the server.xml file if you prefer central configuration).
+
+{code}
+<Resource name="jcr/repository"
+          auth="Container"
+          type="javax.jcr.Repository"
+          factory="org.apache.jackrabbit.rmi.client.ClientRepositoryFactory"
+          url="[The RMI URL of the repository]"/>
+{code}

Propchange: jackrabbit/site/trunk/content/repository-server-howto.cwiki
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jackrabbit/site/trunk/content/repository-server-howto.mdtext
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/repository-server-howto.mdtext?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/repository-server-howto.mdtext (added)
+++ jackrabbit/site/trunk/content/repository-server-howto.mdtext Tue Jan 10 18:50:59 2012
@@ -0,0 +1,78 @@
+Title: Repository Server HOWTO
+This document describes how to use a Jackrabbit content repository in the
+deployment model 3: The Repository Server. In this deployment model, a
+separate repository server is running outside the virtual machine the
+client application is running in. A repository server can serve multiple
+applications running on separate JVMs on separate network hosts. See the [JCR client application HOWTO](jcr-client-application-howto.html)
+ for instructions on how to use the configured content repository server.
+
+Note that JCR specification defines no standard communication protocol for
+inter-JVM repository access, and that Jackrabbit supports no such protocol
+by default. However, Jackrabbit contains tools for using JCR content
+repositories over the RMI and WebDAV protocols (see the jcr-rmi and the
+jcr-server, webapp packages).
+
+This how-to contains instructions for accessing a JCR-RMI server in Tomcat
+versions 4.x and 5.x. It should be easy to modify the instructions for
+other container environments and communication protocols.
+
+In addition to the following the instructions in this document, you also
+need to have an already running JCR-RMI server. See the JCR-RMI javadocs
+for instructions on how to setup such a server.
+
+Warning: The current JCR-RMI library is designed for simplicity, not
+performance. You will probably experience major performance issues if you
+try running any non-trivial applications on top of JCR-RMI.
+
+<a name="RepositoryServerHOWTO-Tomcatinstructions"></a>
+## Tomcat instructions
+
+Follow the steps below to setup a model 3 JCR-RMI client deployment for
+your web application in Tomcat 4.x or 5.x. Example code for both versions
+of Tomcat is included after this overview.
+
+Note that these instructions closely follow the Model 1 HOWTO instructions.
+By making similar changes (change the factory class and parameters of the
+repository) to the Model 2 HOWTO instructions, you can setup a shared
+JCR-RMI client deployment for all applications in the container.
+
+1. Place the JCR-RMI jar file and its dependencies (including the JCR API
+jar) under _Tomcat folder_/webapps/_your app_/WEB-INF/lib.
+1. Register the JCR-RMI client repository factory in the context scope.
+
+<a name="RepositoryServerHOWTO-Step2-Contextconfiguration"></a>
+### Step 2 - Context configuration
+
+In Tomcat 4.x and 5.0, add the following snippet in server.xml under the
+Context element of your web application.
+
+
+    <Resource name="jcr/repository"
+    	  auth="Container"
+    	  type="javax.jcr.Repository"/>
+    
+    <ResourceParams name="jcr/repository">
+      <parameter>
+        <name>factory</name>
+        <value>org.apache.jackrabbit.rmi.client.ClientRepositoryFactory</value>
+      </parameter>
+      <parameter>
+        <name>url</name>
+        <value>[The RMI URL of the repository]
+</value>
+      </parameter>
+    </ResourceParams>
+
+
+In Tomcat 5.5, add the following snippet in your application's context.xml
+file (or in the server.xml file if you prefer central configuration).
+
+
+    <Resource name="jcr/repository"
+    	  auth="Container"
+    	  type="javax.jcr.Repository"
+    	 
+factory="org.apache.jackrabbit.rmi.client.ClientRepositoryFactory"
+              url="[The RMI URL of the repository]
+"/>
+

Propchange: jackrabbit/site/trunk/content/repository-server-howto.mdtext
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jackrabbit/site/trunk/content/search-implementation.cwiki
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/search-implementation.cwiki?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/search-implementation.cwiki (added)
+++ jackrabbit/site/trunk/content/search-implementation.cwiki Tue Jan 10 18:50:59 2012
@@ -0,0 +1,35 @@
+Jackrabbit implements both the mandatory XPath and optional SQL query syntax. Its design follows the goal of the JSR-170 specification that all the mandatory query features can be expressed either in XPath or in SQL. Thus, the actual implementation of the query engine is independent of the query syntax used, though Jackrabbit's query internals are closer to XPath than SQL, because of the hierarchical structure of a JCR.
+
+The major parts of the query implementation are:
+
+* XPath Parser
+* SQL Parser
+* Abstract Query Tree
+* Query engine
+* Utilities
+
+h2. XPath Parser
+
+The XPath query parser is based on the W3C XQuery grammar definition which is not yet final but can be downloaded as draft here. The reason why Jackrabbit uses the XQuery grammar, rather than the XPath grammar, is, that JSR-170 specifies an 'order by' clause for the XPath query syntax. This 'order by' clause is borrowed from the XQuery FLWOR expression syntax. Before parsing the XPath query in Jackrabbit, the statement is surrounded with dummy code, to form a valid XQuery FLWOR expression and is then passed to the XQuery parser. The actual parser is a class generated by JavaCC, which uses the grammar that can be found in src/grammar/xpath. The parsed XPath statement is then translated into an Abstract Query Tree. See class: org.apache.jackrabbit.core.query.xpath.XPathQueryBuilder
+
+h2. SQL Parser
+
+The SQL query parser is generated from a grammar definition located in src/grammar/sql. After parsing, the Abstract Syntax Tree is translated into the Jackrabbit internal Abstract Query Tree. See class: org.apache.jackrabbit.core.query.sql.JCRSQLQueryBuilder
+
+h2. Abstract Query Tree
+
+The Abstract Query Tree (AQT) is the common query description format that allows Jackrabbit to implement a query engine which is (to a certain extent) independent of the query syntax used (XPath or SQL). The AQT consists of the classes that are derived from: org.apache.jackrabbit.core.query.QueryNode
+
+Please note that the AQT is Jackrabbit internal and not exposed to a client using the JCR API!
+
+h2. Query Engine
+
+Now this is where the meat is. The actual implementation of the query engine is configurable. One needs to implement the interface: org.apache.jackrabbit.core.query.QueryHandler. Jackrabbit comes with an implementation that uses a Lucene index: org.apache.jackrabbit.core.query.lucene.SearchIndex This index is independent of the persistence manager in use. However it is also possible to write a QueryHandler implementation which is aware of the underlying storage (e.g. a database) and executes the query on the 'native' storage.
+
+The class org.apache.core.query.lucene.LuceneQueryBuilder translates the Abstract Query Tree into a query that can be executed against the Lucene index. Jackrabbit implements a couple of extensions to the standard Lucene classes, primarily to improve performance in an environment with incremental indexing like Jackrabbit. Instead of a single index, Jackrabbit uses generations of indexes to circumvent costly IndexReader / IndexWriter creation. See: org.apache.jackrabbit.core.query.lucene.MultiIndex. The most recent generation of the search index is held completely in memory. See: org.apache.jackrabbit.core.query.lucene.VolatileIndex. It is comparable with the garbage collection in Java, where generations are used to move living objects from the young into the old generation over time. Queries are then executed on a MultiReader that spans all the indexes. Every now and then (depending on the configuration parameters in workspace.xml) indexes are merged and nodes marked as dele
 ted in the index are removed. This happens similar to how Lucene merges its internal segments.
+
+h2. Utilities
+
+The class org.apache.jackrabbit.core.query.QueryParser allows you to translate a query statement into an Abstract Query Tree and vice versa. It's a nice tool to see how a query in XPath looks like in SQL or the other way round.
+
+The class org.apache.jackrabbit.core.query.PropertyTypeRegistry provides fast access to the type information based on property names. The Jackrabbit QueryHandler implementation uses this class to coerce value literals into other value types.

Propchange: jackrabbit/site/trunk/content/search-implementation.cwiki
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jackrabbit/site/trunk/content/search-implementation.mdtext
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/search-implementation.mdtext?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/search-implementation.mdtext (added)
+++ jackrabbit/site/trunk/content/search-implementation.mdtext Tue Jan 10 18:50:59 2012
@@ -0,0 +1,91 @@
+Title: Search implementation
+Jackrabbit implements both the mandatory XPath and optional SQL query
+syntax. Its design follows the goal of the JSR-170 specification that all
+the mandatory query features can be expressed either in XPath or in SQL.
+Thus, the actual implementation of the query engine is independent of the
+query syntax used, though Jackrabbit's query internals are closer to XPath
+than SQL, because of the hierarchical structure of a JCR.
+
+The major parts of the query implementation are:
+
+* XPath Parser
+* SQL Parser
+* Abstract Query Tree
+* Query engine
+* Utilities
+
+<a name="Searchimplementation-XPathParser"></a>
+## XPath Parser
+
+The XPath query parser is based on the W3C XQuery grammar definition which
+is not yet final but can be downloaded as draft here. The reason why
+Jackrabbit uses the XQuery grammar, rather than the XPath grammar, is, that
+JSR-170 specifies an 'order by' clause for the XPath query syntax. This
+'order by' clause is borrowed from the XQuery FLWOR expression syntax.
+Before parsing the XPath query in Jackrabbit, the statement is surrounded
+with dummy code, to form a valid XQuery FLWOR expression and is then passed
+to the XQuery parser. The actual parser is a class generated by JavaCC,
+which uses the grammar that can be found in src/grammar/xpath. The parsed
+XPath statement is then translated into an Abstract Query Tree. See class:
+org.apache.jackrabbit.core.query.xpath.XPathQueryBuilder
+
+<a name="Searchimplementation-SQLParser"></a>
+## SQL Parser
+
+The SQL query parser is generated from a grammar definition located in
+src/grammar/sql. After parsing, the Abstract Syntax Tree is translated into
+the Jackrabbit internal Abstract Query Tree. See class:
+org.apache.jackrabbit.core.query.sql.JCRSQLQueryBuilder
+
+<a name="Searchimplementation-AbstractQueryTree"></a>
+## Abstract Query Tree
+
+The Abstract Query Tree (AQT) is the common query description format that
+allows Jackrabbit to implement a query engine which is (to a certain
+extent) independent of the query syntax used (XPath or SQL). The AQT
+consists of the classes that are derived from:
+org.apache.jackrabbit.core.query.QueryNode
+
+Please note that the AQT is Jackrabbit internal and not exposed to a client
+using the JCR API!
+
+<a name="Searchimplementation-QueryEngine"></a>
+## Query Engine
+
+Now this is where the meat is. The actual implementation of the query
+engine is configurable. One needs to implement the interface:
+org.apache.jackrabbit.core.query.QueryHandler. Jackrabbit comes with an
+implementation that uses a Lucene index:
+org.apache.jackrabbit.core.query.lucene.SearchIndex This index is
+independent of the persistence manager in use. However it is also possible
+to write a QueryHandler implementation which is aware of the underlying
+storage (e.g. a database) and executes the query on the 'native' storage.
+
+The class org.apache.core.query.lucene.LuceneQueryBuilder translates the
+Abstract Query Tree into a query that can be executed against the Lucene
+index. Jackrabbit implements a couple of extensions to the standard Lucene
+classes, primarily to improve performance in an environment with
+incremental indexing like Jackrabbit. Instead of a single index, Jackrabbit
+uses generations of indexes to circumvent costly IndexReader / IndexWriter
+creation. See: org.apache.jackrabbit.core.query.lucene.MultiIndex. The most
+recent generation of the search index is held completely in memory. See:
+org.apache.jackrabbit.core.query.lucene.VolatileIndex. It is comparable
+with the garbage collection in Java, where generations are used to move
+living objects from the young into the old generation over time. Queries
+are then executed on a MultiReader that spans all the indexes. Every now
+and then (depending on the configuration parameters in workspace.xml)
+indexes are merged and nodes marked as deleted in the index are removed.
+This happens similar to how Lucene merges its internal segments.
+
+<a name="Searchimplementation-Utilities"></a>
+## Utilities
+
+The class org.apache.jackrabbit.core.query.QueryParser allows you to
+translate a query statement into an Abstract Query Tree and vice versa.
+It's a nice tool to see how a query in XPath looks like in SQL or the other
+way round.
+
+The class org.apache.jackrabbit.core.query.PropertyTypeRegistry provides
+fast access to the type information based on property names. The Jackrabbit
+QueryHandler implementation uses this class to coerce value literals into
+other value types.

Propchange: jackrabbit/site/trunk/content/search-implementation.mdtext
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jackrabbit/site/trunk/content/shared-j2ee-resource-howto.cwiki
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/shared-j2ee-resource-howto.cwiki?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/shared-j2ee-resource-howto.cwiki (added)
+++ jackrabbit/site/trunk/content/shared-j2ee-resource-howto.cwiki Tue Jan 10 18:50:59 2012
@@ -0,0 +1,57 @@
+This document describes how to use a Jackrabbit content repository in the deployment model 2: Shared J2EE Resource. In this deployment model, a central content repository resource managed by an application server is used by multiple different applications. See the [JCR client application HOWTO] for instructions on how to use the configured content repository.
+
+This how-to contains instructions for Tomcat versions 4.x and 5.x. It should be easy to modify the instructions for other container environments.
+
+h2. Tomcat instructions
+
+Follow the steps below to setup a model 2 Jackrabbit deployment for your Tomcat 4.x or 5.x installation. Example code for both versions of Tomcat is included after this overview.
+
+# Place the Jackrabbit jar file and all the dependencies (including the JCR API jar file) under _Tomcat folder_/common/lib.
+# Register the bindable repository factory as a global resource.
+# Link the global resource to a context scoped JNDI address.
+
+h3. Step 2 - Resource configuration
+
+Note: This step is essentially the same as step 2 in the Model 1 HOWTO. The only differences are in the (arbitrary) naming of the resource and placing of the configuration elements. The difference in the end result is that the configured repository is bound to the global JNDI context instead of a local one. In Tomcat 4.x and 5.0, add the following snippet in server.xml under the GlobalNamingResources element.
+
+{code}
+<Resource name="jcr/globalRepository"
+          auth="Container"
+          type="javax.jcr.Repository"/>
+
+<ResourceParams name="jcr/globalRepository">
+  <parameter>
+    <name>factory</name>
+    <value>org.apache.jackrabbit.core.jndi.BindableRepositoryFactory</value>
+  </parameter>
+  <parameter>
+    <name>configFilePath</name>
+    <value>[full path to repository.xml]</value>
+  </parameter>
+  <parameter>
+    <name>repHomeDir</name>
+    <value>[full path to the repository home folder]</value>
+  </parameter>
+</ResourceParams>
+{code}
+
+In Tomcat 5.5, add the following snippet in server.xml under the GlobalNamingResources element.
+
+{code}
+<Resource name="jcr/globalRepository"
+          auth="Container"
+          type="javax.jcr.Repository"
+          factory="org.apache.jackrabbit.core.jndi.BindableRepositoryFactory"
+          configFilePath="[full path to repository.xml"
+          repHomeDir="[full path to the repository home folder]"/>
+{code}
+
+h3. Step 3 - Resource link
+
+In Tomcat versions 4.x and 5.0, add the following snippet in server.xml under the Context element of your web application. In Tomcat version 5.5, add the snippet in your application's context.xml or $CATALINA_HOME/conf/_enginename_/_hostname_/_webappname_.xml. If you prefer central configuration, you can add the configuration to $CATALINA_HOME/conf/context.xml.
+
+{code}
+<ResourceLink name="jcr/repository"
+              global="jcr/globalRepository"
+              type="javax.jcr.Repository"/>
+{code}

Propchange: jackrabbit/site/trunk/content/shared-j2ee-resource-howto.cwiki
------------------------------------------------------------------------------
    svn:eol-style = native