You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jackrabbit.apache.org by ju...@apache.org on 2012/01/10 19:51:06 UTC
svn commit: r1229679 [5/12] - /jackrabbit/site/trunk/content/
Propchange: jackrabbit/site/trunk/content/getting-started-with-apache-jackrabbit.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: jackrabbit/site/trunk/content/how-jackrabbit-works.cwiki
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/how-jackrabbit-works.cwiki?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/how-jackrabbit-works.cwiki (added)
+++ jackrabbit/site/trunk/content/how-jackrabbit-works.cwiki Tue Jan 10 18:50:59 2012
@@ -0,0 +1,12 @@
+The diagram on the left explains which components of the Jackrabbit are used when a user of the JCR API modified content in the content repository. This is a simple and very common operation, that touches a large portion of the components in the Jackrabbit implementation. Please keep in mind that this implementation architecture is not mandated by JCR, but has been designed from scratch based on JCR.
+
+{center}!jackrabbit-ism_small.jpg!{center}
+
+The used components and their respective functions in the order of their appearance in the use case of writing or modifying content in the content repository:
+
+* *Transient Item State Manager* Once content items are read by a session they are cached in the Transient Item State Manager. When those items are modified the modification is only visible to that same session, in the so-called "transient" space.
+* *Transactional Item State Manager* When the Application persists the modified items using the JCR Item.save() or Session.save() the transient Items are promoted into the Transactional ISM. The modifications are still only visible within the scope of this transaction, meaning that other sessions will not see the modification until they are committed. The commit is implicit if the Content Repository is not running in an XA environment.
+* *Shared Item State Manager* Once a transaction is committed the Shared Item State Manager receives the changelog and publishes the changes to all the sessions logged into the same workspace. This means that all the Item States that are cached and referenced by other sessions are notified and possibly updated or invalidated. The Shared Item State Manager also triggers the observation and hands the changelog over to the persistence manager that is configured for this workspace.
+* *Persistence Manager* The Persistence Manager persists all the Item States in the changelog passed by the Shared ISM. The persistence manager is a very simple, fast and transactional interface that is very low-level and does not need to understand the complexities of the repository operations, but basically just needs to be able persist and retrieve a given item based on its item id.
+* *Observation* When a transaction is committed the Shared Item State Manager triggers the Observation mechanism. This allows applications to asynchronously subscribe changes in the workspace. Jackrabbit also non-standard offers a synchronous observation.
+* *Query Manager / Index* Through a synchronous observation event the Query Manager is instructed to index the new or modified items. A content repository index is much more complex than a classical RDB index since it deals with content repository features like the item hierarchy, nodetype inheritance or fulltext searches.
Propchange: jackrabbit/site/trunk/content/how-jackrabbit-works.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: jackrabbit/site/trunk/content/how-jackrabbit-works.mdtext
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/how-jackrabbit-works.mdtext?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/how-jackrabbit-works.mdtext (added)
+++ jackrabbit/site/trunk/content/how-jackrabbit-works.mdtext Tue Jan 10 18:50:59 2012
@@ -0,0 +1,46 @@
+Title: How Jackrabbit works
+The diagram on the left explains which components of the Jackrabbit are
+used when a user of the JCR API modified content in the content repository.
+This is a simple and very common operation, that touches a large portion of
+the components in the Jackrabbit implementation. Please keep in mind that
+this implementation architecture is not mandated by JCR, but has been
+designed from scratch based on JCR.
+
+{center}!jackrabbit-ism_small.jpg!{center}
+
+The used components and their respective functions in the order of their
+appearance in the use case of writing or modifying content in the content
+repository:
+
+* *Transient Item State Manager* Once content items are read by a session
+they are cached in the Transient Item State Manager. When those items are
+modified the modification is only visible to that same session, in the
+so-called "transient" space.
+* *Transactional Item State Manager* When the Application persists the
+modified items using the JCR Item.save() or Session.save() the transient
+Items are promoted into the Transactional ISM. The modifications are still
+only visible within the scope of this transaction, meaning that other
+sessions will not see the modification until they are committed. The commit
+is implicit if the Content Repository is not running in an XA environment.
+* *Shared Item State Manager* Once a transaction is committed the Shared
+Item State Manager receives the changelog and publishes the changes to all
+the sessions logged into the same workspace. This means that all the Item
+States that are cached and referenced by other sessions are notified and
+possibly updated or invalidated. The Shared Item State Manager also
+triggers the observation and hands the changelog over to the persistence
+manager that is configured for this workspace.
+* *Persistence Manager* The Persistence Manager persists all the Item
+States in the changelog passed by the Shared ISM. The persistence manager
+is a very simple, fast and transactional interface that is very low-level
+and does not need to understand the complexities of the repository
+operations, but basically just needs to be able persist and retrieve a
+given item based on its item id.
+* *Observation* When a transaction is committed the Shared Item State
+Manager triggers the Observation mechanism. This allows applications to
+asynchronously subscribe changes in the workspace. Jackrabbit also
+non-standard offers a synchronous observation.
+* *Query Manager / Index* Through a synchronous observation event the Query
+Manager is instructed to index the new or modified items. A content
+repository index is much more complex than a classical RDB index since it
+deals with content repository features like the item hierarchy, nodetype
+inheritance or fulltext searches.
Propchange: jackrabbit/site/trunk/content/how-jackrabbit-works.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: jackrabbit/site/trunk/content/how-to-map-associations-between-objects.cwiki
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/how-to-map-associations-between-objects.cwiki?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/how-to-map-associations-between-objects.cwiki (added)
+++ jackrabbit/site/trunk/content/how-to-map-associations-between-objects.cwiki Tue Jan 10 18:50:59 2012
@@ -0,0 +1,106 @@
+h2. Overview
+
+This tutorial explains how to map associations between objects (1:1 and 1:n). You can find the tutorial code sample from [here|^Beans_and_collections.zip]. It is based on Maven and ready to be used inside Eclipse. If you have some configuration issues, please review the tutorial "[A simple OCM project with Maven & Eclipse]".
+
+h2. The Content Model
+
+We will extend the content model created in the previous tutorial [5' with Jackrabbit OCM]. Each PressRelease is made by an Author and it is possible to add some references (URL).
+
+So, we have to add 2 new associations in our model :
+- An 1:1 association between a PressRelease and an Author.
+- An 1:n association between PresseRelease and Url.
+
+
+Here is the main java class, the PressRelease :
+
+{code}
+@Node
+public class PressRelease
+{
+ @Field(path=true) private String path;
+ @Field private String title;
+ @Field private Date pubDate;
+ @Field private String content;
+ @Bean private Author author;
+ @Collection List<Url> urls;
+
+ //if you want a map instead of a list, use the following declaration
+ @Collection Map<String,Url> map;
+
+ [... Add here getters & setters ...]
+
+}
+{code}
+
+Since the tutorial [5' with Jackrabbit OCM], we can understand the goal of the annotations @Node and @Field.
+An association 1:1 can be specified with the annotation @Bean like
+{code}
+@Bean private Author author;
+{code}
+
+It is possible to set extra settings with this annotation but it is out of the scope of this tutorial.You can review the code of the Author class which is very simple. As you will see, it is not mandatory to add annotation @Field(path=true) in the Author class because it is an aggregation of a PressRelease.
+
+An 1:n association can be specified with the annotation @Collection like
+{code}
+@Collection List<Url> urls;
+{code}
+
+For this kind of association, you can also use a Map instead of a Collection
+{code}
+@Collection Map<String,Url> map;
+{code}
+
+
+Right now, the support of Map is limited to the usage of String for the key because the map key will be used as the Node name.
+
+
+h2.How are those objects stored in the repository ?
+
+
+For this tutorial each java class is mapped into the "nt:unstructured" node type. Making this kind of mapping is quite flexible because it does not imply specific repository configuration. There is no constraints in the JCR repository. All constrains are defined in the java code.
+
+{info}
+Note : It is possible to associate a specific node type to each java class but this imply more repository configurations.
+ It is also possible to change the corresponding JCR node structure by using specific Bean or Collection converters.
+ Later, we will add more tutorials on OCM converters.
+{info}
+
+Following our example, the Author and Urls nodes will be created as subnodes of a press release.
+Here is an example of the correspoding JCR structure :
+
+{code}
+- PressRelease_1
+ * path : "/mypath/myrelease"
+ * title : "..."
+ * pubDate : 10/06/08
+ * content : "...."
+ - Author
+ * firstName : "..."
+ * lastName : "..."
+ - urls
+ * url1
+ * url : "http://...."
+ * caption : "..."
+ * description : "..."
+ * url2
+ * url : "http://...."
+ * caption : "..."
+ * description : "..."
+ ...
+ - map
+ * Apache
+ * url : "http://www.apache.org"
+ * caption : "..."
+ * description : "..."
+
+ * Jackrabbit
+ * url : "http://jackrabbit.apache.org"
+ * caption : "..."
+ * description : "..."
+
+{code}
+
+h2.Download the tutorial code
+
+You can download the OCM project from [here|^Beans_and_collections.zip]
+
Propchange: jackrabbit/site/trunk/content/how-to-map-associations-between-objects.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: jackrabbit/site/trunk/content/how-to-map-associations-between-objects.mdtext
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/how-to-map-associations-between-objects.mdtext?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/how-to-map-associations-between-objects.mdtext (added)
+++ jackrabbit/site/trunk/content/how-to-map-associations-between-objects.mdtext Tue Jan 10 18:50:59 2012
@@ -0,0 +1,130 @@
+Title: How to map associations between objects
+<a name="Howtomapassociationsbetweenobjects-Overview"></a>
+## Overview
+
+This tutorial explains how to map associations between objects (1:1 and
+1:n). You can find the tutorial code sample from [here](^beans_and_collections.zip.html)
+. It is based on Maven and ready to be used inside Eclipse. If you have
+some configuration issues, please review the tutorial "[A simple OCM
+project with Maven & Eclipse]".
+
+<a name="Howtomapassociationsbetweenobjects-TheContentModel"></a>
+## The Content Model
+
+We will extend the content model created in the previous tutorial [5' with Jackrabbit OCM](5'-with-jackrabbit-ocm.html)
+. Each PressRelease is made by an Author and it is possible to add some
+references (URL).
+
+So, we have to add 2 new associations in our model :
+- An 1:1 association between a PressRelease and an Author.
+- An 1:n association between PresseRelease and Url.
+
+
+Here is the main java class, the PressRelease :
+
+
+ @Node
+ public class PressRelease
+ {
+ @Field(path=true) private String path;
+ @Field private String title;
+ @Field private Date pubDate;
+ @Field private String content;
+ @Bean private Author author;
+ @Collection List<Url> urls;
+
+ //if you want a map instead of a list, use the following declaration
+ @Collection Map<String,Url> map;
+
+ [... Add here getters & setters ...]
+
+ }
+
+
+Since the tutorial [5' with Jackrabbit OCM](5'-with-jackrabbit-ocm.html)
+, we can understand the goal of the annotations @Node and @Field.
+An association 1:1 can be specified with the annotation @Bean like
+
+ @Bean private Author author;
+
+
+It is possible to set extra settings with this annotation but it is out of
+the scope of this tutorial.You can review the code of the Author class
+which is very simple. As you will see, it is not mandatory to add
+annotation @Field(path=true) in the Author class because it is an
+aggregation of a PressRelease.
+
+An 1:n association can be specified with the annotation @Collection like
+
+ @Collection List<Url> urls;
+
+
+For this kind of association, you can also use a Map instead of a
+Collection
+
+ @Collection Map<String,Url> map;
+
+
+
+Right now, the support of Map is limited to the usage of String for the key
+because the map key will be used as the Node name.
+
+
+<a name="Howtomapassociationsbetweenobjects-Howarethoseobjectsstoredintherepository?"></a>
+## How are those objects stored in the repository ?
+
+
+For this tutorial each java class is mapped into the "nt:unstructured" node
+type. Making this kind of mapping is quite flexible because it does not
+imply specific repository configuration. There is no constraints in the JCR
+repository. All constrains are defined in the java code.
+
+{info}
+Note : It is possible to associate a specific node type to each java class
+but this imply more repository configurations.
+ It is also possible to change the corresponding JCR node structure
+by using specific Bean or Collection converters.
+ Later, we will add more tutorials on OCM converters.
+{info}
+
+Following our example, the Author and Urls nodes will be created as
+subnodes of a press release.
+Here is an example of the correspoding JCR structure :
+
+
+ - PressRelease_1
+ * path : "/mypath/myrelease"
+ * title : "..."
+ * pubDate : 10/06/08
+ * content : "...."
+ - Author
+ * firstName : "..."
+ * lastName : "..."
+ - urls
+ * url1
+ * url : "http://...."
+ * caption : "..."
+ * description : "..."
+ * url2
+ * url : "http://...."
+ * caption : "..."
+ * description : "..."
+ ...
+ - map
+ * Apache
+ * url : "http://www.apache.org"
+ * caption : "..."
+ * description : "..."
+
+ * Jackrabbit
+ * url : "http://jackrabbit.apache.org"
+ * caption : "..."
+ * description : "..."
+
+
+
+<a name="Howtomapassociationsbetweenobjects-Downloadthetutorialcode"></a>
+## Download the tutorial code
+
+You can download the OCM project from [here](^beans_and_collections.zip.html)
+
Propchange: jackrabbit/site/trunk/content/how-to-map-associations-between-objects.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: jackrabbit/site/trunk/content/index-readers.cwiki
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/index-readers.cwiki?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/index-readers.cwiki (added)
+++ jackrabbit/site/trunk/content/index-readers.cwiki Tue Jan 10 18:50:59 2012
@@ -0,0 +1,37 @@
+Jackrabbit uses Lucene as the underlying index implementation and provides several extensions and customizations that help improve performance in an environment where changes to the index are frequent. The extensions also cover features that are not supported by Lucene, like hierarchical queries.
+
+{center}!index-readers-per-segment.jpg!{center}
+
+h2. CachingIndexReader
+
+The CachingIndexReader is at the very bottom of the index reader stack in Jackrabbit. It's main purpose is to cache the parent relationship of a node. Each node is represented with a document in the index and one of the fields is _:PARENT. The value of this field is the string representation of the parent nodes UUID. In case of the root node the the parent field contains an empty string as its value. Several queries in Jackrabbit are hierarchical and check whether a node is a descendant of another node. For the very simple case, where one needs to know if a node is the child of another node, we can just look up both nodes (lucene documents) in the index and compare the parent field on one node with the _:UUID field of the other. If they match the one is the child of the other node. When it comes to evaluating a descendant axis, this becomes much more expensive and will cause lots of document lookups in lucene. By caching the parent child relationship of documents, hierarchic
al operations can be executed much faster.
+
+The cache consists of an array of DocId instances. The length of this array corresponds to the number of documents accessible through the index reader. That is every document in the index has a corresponding cache entry in the array. Initially the cache is empty and is filled as it is accessed. There are two kinds of DocIds: PlainDocId and UUIDDocId. When the parent of a node resides in the same index segment a PlainDocId is created, which simply contains the document number of the parent. If the parent resides in a different index segment a UUIDDocId is created, which contains the UUID of the parent node. When a UUIDDocId is resolved it is passed an index reader, which allows it to get the document number for the UUID and cache it for later reuse.
+
+h2. Overwriting DocId
+
+It may happen that a PlainDocId is present in the cache of a CachingIndexReader but must be considered invalid in the context of a call. CachingIndexReader.getParent() may be called from a ReadOnlyIndexReader instance which has the target of the PlainDocId in the set of deleted document. This indicates that the nodes has been deleted or modified. Thus it has traveled to another index segment. In this case the PlainDocId is overwritten with a UUIDDocId. The opposite never happens. A UUIDDocId is never overwritten with a PlainDocId because when a document is added to an index a new CachingIndexReader is created.
+
+h2. SharedIndexReader
+
+The SharedIndexReader wraps a CachingIndexReader and adds a reference count facility. A SharedIndexReader is kept open for the entire lifetime of a PersistentIndex. Even if documents are marked deleted in the underlying index (by another thread through CommittableIndexReader), the SharedIndexReader will still be kept open and considers the documents as valid. The reference counting is needed because it may happen that a client of the SharedIndexReader is still in use while the underlying PersistentIndex is closed. This may happen when the index merger replaces indexes while a query still operates on the indexes to be deleted. Using reference counts, closing the SharedIndexReader is delayed until all clients are finished with the SharedIndexReader.
+
+h2. ReadOnlyIndexReader
+
+The inconsistency introduced by the SharedIndexReader (considers deleted documents as still valid) is corrected by the ReadOnlyIndexReader. Whenever a new instance of this reader is created it copies the currently marked deleted documents from the CommittableIndexReader. At the same time all methods that attempt delete documents will throw a UnsupportedOperationException.
+
+h2. CommittableIndexReader
+
+This is the index reader where documents are marked deleted in a PersistentIndex. As with the SharedIndexReader the CommittableIndexReader is kept open for the entire lifetime of the PersistentIndex. To achieve this the CommittableIndexReader exposes a method commitDeleted, which forces the underlying native lucene index reader to commit changes. Only committing changes whithout closing the index reader is otherwise not possible using the plain lucene index reader.
+
+h2. Combining the index segments
+
+{center}!index-readers-per-query-handler.jpg!{center}
+
+h2. CachingMultiIndexReader
+
+The index for the content of a workspace consists of multiple segments, that is multiple ReadOnlyIndexReaders. They are combined in a MultiIndex using a CachingMultiIndexReader. In order to speed up lookups by UUID the CachingMultiIndexReader also has a DocNumberCache. This cache uses a LRU algorithm to keep a limitted amount of UUID to document number mappings.
+
+h2. CombinedIndexReader
+
+This index reader is similar to the CachingMultiIndexReader, in fact both implement MultiIndexReader and HierarchyResolver. A CombinedIndexReader is created when a query needs an index reader that spans both the workspace index as well as the jcr:system index, where the version store resides.
Propchange: jackrabbit/site/trunk/content/index-readers.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: jackrabbit/site/trunk/content/index-readers.mdtext
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/index-readers.mdtext?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/index-readers.mdtext (added)
+++ jackrabbit/site/trunk/content/index-readers.mdtext Tue Jan 10 18:50:59 2012
@@ -0,0 +1,109 @@
+Title: Index readers
+Jackrabbit uses Lucene as the underlying index implementation and provides
+several extensions and customizations that help improve performance in an
+environment where changes to the index are frequent. The extensions also
+cover features that are not supported by Lucene, like hierarchical queries.
+
+{center}!index-readers-per-segment.jpg!{center}
+
+<a name="Indexreaders-CachingIndexReader"></a>
+## CachingIndexReader
+
+The CachingIndexReader is at the very bottom of the index reader stack in
+Jackrabbit. It's main purpose is to cache the parent relationship of a
+node. Each node is represented with a document in the index and one of the
+fields is _:PARENT. The value of this field is the string representation of
+the parent nodes UUID. In case of the root node the the parent field
+contains an empty string as its value. Several queries in Jackrabbit are
+hierarchical and check whether a node is a descendant of another node. For
+the very simple case, where one needs to know if a node is the child of
+another node, we can just look up both nodes (lucene documents) in the
+index and compare the parent field on one node with the _:UUID field of the
+other. If they match the one is the child of the other node. When it comes
+to evaluating a descendant axis, this becomes much more expensive and will
+cause lots of document lookups in lucene. By caching the parent child
+relationship of documents, hierarchical operations can be executed much
+faster.
+
+The cache consists of an array of DocId instances. The length of this array
+corresponds to the number of documents accessible through the index reader.
+That is every document in the index has a corresponding cache entry in the
+array. Initially the cache is empty and is filled as it is accessed. There
+are two kinds of DocIds: PlainDocId and UUIDDocId. When the parent of a
+node resides in the same index segment a PlainDocId is created, which
+simply contains the document number of the parent. If the parent resides in
+a different index segment a UUIDDocId is created, which contains the UUID
+of the parent node. When a UUIDDocId is resolved it is passed an index
+reader, which allows it to get the document number for the UUID and cache
+it for later reuse.
+
+<a name="Indexreaders-OverwritingDocId"></a>
+## Overwriting DocId
+
+It may happen that a PlainDocId is present in the cache of a
+CachingIndexReader but must be considered invalid in the context of a call.
+CachingIndexReader.getParent() may be called from a ReadOnlyIndexReader
+instance which has the target of the PlainDocId in the set of deleted
+document. This indicates that the nodes has been deleted or modified. Thus
+it has traveled to another index segment. In this case the PlainDocId is
+overwritten with a UUIDDocId. The opposite never happens. A UUIDDocId is
+never overwritten with a PlainDocId because when a document is added to an
+index a new CachingIndexReader is created.
+
+<a name="Indexreaders-SharedIndexReader"></a>
+## SharedIndexReader
+
+The SharedIndexReader wraps a CachingIndexReader and adds a reference count
+facility. A SharedIndexReader is kept open for the entire lifetime of a
+PersistentIndex. Even if documents are marked deleted in the underlying
+index (by another thread through CommittableIndexReader), the
+SharedIndexReader will still be kept open and considers the documents as
+valid. The reference counting is needed because it may happen that a client
+of the SharedIndexReader is still in use while the underlying
+PersistentIndex is closed. This may happen when the index merger replaces
+indexes while a query still operates on the indexes to be deleted. Using
+reference counts, closing the SharedIndexReader is delayed until all
+clients are finished with the SharedIndexReader.
+
+<a name="Indexreaders-ReadOnlyIndexReader"></a>
+## ReadOnlyIndexReader
+
+The inconsistency introduced by the SharedIndexReader (considers deleted
+documents as still valid) is corrected by the ReadOnlyIndexReader. Whenever
+a new instance of this reader is created it copies the currently marked
+deleted documents from the CommittableIndexReader. At the same time all
+methods that attempt delete documents will throw a
+UnsupportedOperationException.
+
+<a name="Indexreaders-CommittableIndexReader"></a>
+## CommittableIndexReader
+
+This is the index reader where documents are marked deleted in a
+PersistentIndex. As with the SharedIndexReader the CommittableIndexReader
+is kept open for the entire lifetime of the PersistentIndex. To achieve
+this the CommittableIndexReader exposes a method commitDeleted, which
+forces the underlying native lucene index reader to commit changes. Only
+committing changes whithout closing the index reader is otherwise not
+possible using the plain lucene index reader.
+
+<a name="Indexreaders-Combiningtheindexsegments"></a>
+## Combining the index segments
+
+{center}!index-readers-per-query-handler.jpg!{center}
+
+<a name="Indexreaders-CachingMultiIndexReader"></a>
+## CachingMultiIndexReader
+
+The index for the content of a workspace consists of multiple segments,
+that is multiple ReadOnlyIndexReaders. They are combined in a MultiIndex
+using a CachingMultiIndexReader. In order to speed up lookups by UUID the
+CachingMultiIndexReader also has a DocNumberCache. This cache uses a LRU
+algorithm to keep a limitted amount of UUID to document number mappings.
+
+<a name="Indexreaders-CombinedIndexReader"></a>
+## CombinedIndexReader
+
+This index reader is similar to the CachingMultiIndexReader, in fact both
+implement MultiIndexReader and HierarchyResolver. A CombinedIndexReader is
+created when a query needs an index reader that spans both the workspace
+index as well as the jcr:system index, where the version store resides.
Propchange: jackrabbit/site/trunk/content/index-readers.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: jackrabbit/site/trunk/content/issue-tracker.cwiki
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/issue-tracker.cwiki?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/issue-tracker.cwiki (added)
+++ jackrabbit/site/trunk/content/issue-tracker.cwiki Tue Jan 10 18:50:59 2012
@@ -0,0 +1,43 @@
+Apache Jackrabbit uses Jira for tracking bug reports and requests for improvements, new features, and other changes.
+
+The issue tracker is available at https://issues.apache.org/jira/browse/JCR and is readable by everyone. A Jira account is needed to create new issues and to comment on existing issues. Use the [registration form|https://issues.apache.org/jira/secure/Signup!default.jspa] to request an account if you do not already have one.
+
+h2. Issue workflow
+
+When an issue is created, it's in the *Open* state. This is the time for describing the issue and discussing possible ways of solving it. If a proposed patch is attached, then the issue can optionally be moved to the *Patch available* state to give it more visibility. If the patch is cancelled because more work is needed, the issue moves back to the *Open* state.
+
+Once the issue is solved, the committer who committed the changes marks the issue as *Resolved* with resolution type _Fixed_. Other resolution types like _Duplicate_, _Invalid_ or _Won't Fix_ are used when resolving issues that for one reason or another require no changes in the codebase. An issue can be *Reopened* if the committed fix is found to be not good enough.
+
+When an issue is resolved as fixed, the committer should set the "Fix Version(s)" field to the next trunk version to mark that the change will be included in that release. If the fix is also backported to one or more of the maintenance branches (for backporting, use "svn merge -c _revision_ ^/jackrabbit/trunk" in the root of the branch) the version numbers of the relevant next maintenance releases should also be included in the "Fix Version(s)" field.
+
+Finally, once a release containing the change has been made, the release manager will mark the issue *Closed*, after which the issue can no longer be reopened (since the release can obviously no longer be changed). Potential regressions or other related problems should be tracked in separate followup issues.
+
+h2. Issue contents
+
+See below for guidelines on how to use the various fields in an issue.
+
+h3. Issue type
+
+When creating a new issue, select the issue type based as follows:
+
+|| Issue type || Description ||
+| *Bug* | Bug reports are used for cases where Jackrabbit fails not function as it should (as defined by the JCR specification or some other documentation). If you are not certain whether the issue you've found is actually a bug, please ask the Jackrabbit [mailing lists] first for help. |
+| *New Feature* | Use a feature request when Jackrabbit does not have some functionality you need. |
+| *Improvement* | Use an improvement request to suggest improvements to existing features. Typical improvement requests are about updating documentation, increasing stability and performance, simplifying the implementation, or other such changes that make Jackrabbit better without introducing new features or fixing existing bugs. |
+| *Test* | Use this type when contributing test cases for existing features. Normally test cases should be contributed as a part of the original feature request or as regression tests associated with bug reports, but sometimes you just want to extend test coverage by introducing new test cases. This issue type is for such cases. |
+| *Task* | Used only for issues related to project infrastructure. |
+
+h3. Issue summary, environment and description
+
+The issue summary should be a short and clear statement that indicates the scope of the issue. You are probably being too verbose if you exceed the length of the text field. Use the Environment and Description fields to provide more detailed information.
+
+h3. Issue priority
+
+Issue priority should be set according to the following:
+
+|| Issue priority || Description |
+| *Blocker* | Legal or other fundamental issue that makes it impossible to release Jackrabbit code |
+| *Critical* | Major loss of functionality that affects many Jackrabbit users |
+| *Major* | Important issue that should be resolved soon |
+| *Minor* | Nice to have issues |
+| *Trivial* | Trivial changes that can be applied whenever someone has extra time |
Propchange: jackrabbit/site/trunk/content/issue-tracker.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: jackrabbit/site/trunk/content/issue-tracker.mdtext
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/issue-tracker.mdtext?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/issue-tracker.mdtext (added)
+++ jackrabbit/site/trunk/content/issue-tracker.mdtext Tue Jan 10 18:50:59 2012
@@ -0,0 +1,95 @@
+Title: Issue Tracker
+Apache Jackrabbit uses Jira for tracking bug reports and requests for
+improvements, new features, and other changes.
+
+The issue tracker is available at https://issues.apache.org/jira/browse/JCR
+and is readable by everyone. A Jira account is needed to create new issues
+and to comment on existing issues. Use the [registration form](https://issues.apache.org/jira/secure/Signup!default.jspa)
+ to request an account if you do not already have one.
+
+<a name="IssueTracker-Issueworkflow"></a>
+## Issue workflow
+
+When an issue is created, it's in the *Open* state. This is the time for
+describing the issue and discussing possible ways of solving it. If a
+proposed patch is attached, then the issue can optionally be moved to the
+*Patch available* state to give it more visibility. If the patch is
+cancelled because more work is needed, the issue moves back to the *Open*
+state.
+
+Once the issue is solved, the committer who committed the changes marks the
+issue as *Resolved* with resolution type _Fixed_. Other resolution types
+like _Duplicate_, _Invalid_ or _Won't Fix_ are used when resolving issues
+that for one reason or another require no changes in the codebase. An issue
+can be *Reopened* if the committed fix is found to be not good enough.
+
+When an issue is resolved as fixed, the committer should set the "Fix
+Version(s)" field to the next trunk version to mark that the change will be
+included in that release. If the fix is also backported to one or more of
+the maintenance branches (for backporting, use "svn merge -c _revision_
+^/jackrabbit/trunk" in the root of the branch) the version numbers of the
+relevant next maintenance releases should also be included in the "Fix
+Version(s)" field.
+
+Finally, once a release containing the change has been made, the release
+manager will mark the issue *Closed*, after which the issue can no longer
+be reopened (since the release can obviously no longer be changed).
+Potential regressions or other related problems should be tracked in
+separate followup issues.
+
+<a name="IssueTracker-Issuecontents"></a>
+## Issue contents
+
+See below for guidelines on how to use the various fields in an issue.
+
+<a name="IssueTracker-Issuetype"></a>
+### Issue type
+
+When creating a new issue, select the issue type based as follows:
+
+<table>
+<tr><th> Issue type </th><th> Description </th></tr>
+<tr><td> *Bug* </td><td> Bug reports are used for cases where Jackrabbit fails
+not function as it should (as defined by the JCR specification or some
+other documentation). If you are not certain whether the issue you've found
+is actually a bug, please ask the Jackrabbit [mailing lists](mailing-lists.html)
+ first for help. </td></tr>
+<tr><td> *New Feature* </td><td> Use a feature request when Jackrabbit does not have
+some functionality you need. </td></tr>
+<tr><td> *Improvement* </td><td> Use an improvement request to suggest improvements to
+existing features. Typical improvement requests are about updating
+documentation, increasing stability and performance, simplifying the
+implementation, or other such changes that make Jackrabbit better without
+introducing new features or fixing existing bugs. </td></tr>
+<tr><td> *Test* </td><td> Use this type when contributing test cases for
+existing features. Normally test cases should be contributed as a part of
+the original feature request or as regression tests associated with bug
+reports, but sometimes you just want to extend test coverage by introducing
+new test cases. This issue type is for such cases. </td></tr>
+<tr><td> *Task* </td><td> Used only for issues related to project
+infrastructure. </td></tr>
+</table>
+
+<a name="IssueTracker-Issuesummary,environmentanddescription"></a>
+### Issue summary, environment and description
+
+The issue summary should be a short and clear statement that indicates the
+scope of the issue. You are probably being too verbose if you exceed the
+length of the text field. Use the Environment and Description fields to
+provide more detailed information.
+
+<a name="IssueTracker-Issuepriority"></a>
+### Issue priority
+
+Issue priority should be set according to the following:
+
+<table>
+<tr><th> Issue priority </th><th> Description </td></tr>
+<tr><td> *Blocker* </td><td> Legal or other fundamental issue that makes it
+impossible to release Jackrabbit code </td></tr>
+<tr><td> *Critical* </td><td> Major loss of functionality that affects many
+Jackrabbit users </td></tr>
+<tr><td> *Major* </td><td> Important issue that should be resolved soon </td></tr>
+<tr><td> *Minor* </td><td> Nice to have issues </td></tr>
+<tr><td> *Trivial* </td><td> Trivial changes that can be applied whenever someone
+has extra time </td></tr>
Propchange: jackrabbit/site/trunk/content/issue-tracker.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: jackrabbit/site/trunk/content/jackrabbit-api.cwiki
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/jackrabbit-api.cwiki?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/jackrabbit-api.cwiki (added)
+++ jackrabbit/site/trunk/content/jackrabbit-api.cwiki Tue Jan 10 18:50:59 2012
@@ -0,0 +1,9 @@
+This is the API component of the Apache Jackrabbit project. This component contains the interface extensions that Apache Jackrabbit supports in addition to the standard JCR API. You can use these interfaces to access Jackrabbit-specific functionality.
+
+h2. API documentation
+
+* [jackrabbit-api 1.4|http://jackrabbit.apache.org/api/1.4/org/apache/jackrabbit/api/package-summary.html]
+
+h2. External Dependencies
+
+* [JCR]
\ No newline at end of file
Propchange: jackrabbit/site/trunk/content/jackrabbit-api.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: jackrabbit/site/trunk/content/jackrabbit-api.mdtext
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/jackrabbit-api.mdtext?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/jackrabbit-api.mdtext (added)
+++ jackrabbit/site/trunk/content/jackrabbit-api.mdtext Tue Jan 10 18:50:59 2012
@@ -0,0 +1,15 @@
+Title: Jackrabbit API
+This is the API component of the Apache Jackrabbit project. This component
+contains the interface extensions that Apache Jackrabbit supports in
+addition to the standard JCR API. You can use these interfaces to access
+Jackrabbit-specific functionality.
+
+<a name="JackrabbitAPI-APIdocumentation"></a>
+## API documentation
+
+* [jackrabbit-api 1.4](http://jackrabbit.apache.org/api/1.4/org/apache/jackrabbit/api/package-summary.html)
+
+<a name="JackrabbitAPI-ExternalDependencies"></a>
+## External Dependencies
+
+* [JCR](jcr.html)
Propchange: jackrabbit/site/trunk/content/jackrabbit-api.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: jackrabbit/site/trunk/content/jackrabbit-architecture.cwiki
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/jackrabbit-architecture.cwiki?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/jackrabbit-architecture.cwiki (added)
+++ jackrabbit/site/trunk/content/jackrabbit-architecture.cwiki Tue Jan 10 18:50:59 2012
@@ -0,0 +1,57 @@
+* [How Jackrabbit works]
+* [Repository lifecycle]
+* [Search implementation]
+* [Index readers]
+* [Concurrency control]
+
+The general architecture of Jackrabbit can be described in three Layers: A Content Application Layer, an API Layer and a Content Repository Implementation Layer.
+
+!overview.png!
+
+h2. Content Applications
+
+Content Applications interact through the JSR-170 API with the Content Repository Implementation. There are numerous applications that are available for JSR-170 repositories, some of them are very generic (like a WebDAV server) other applications can be very specific and make use of the content repository as a store for the information that is used by the applications. Java Applications can use a JSR-170 content repository as a replacement for anything from property-files, XML-configuration, certain portions of relational database functionality to straight file system or blob-management. Using a content repository allows an application to deal with an arbitrarily large hierarchical space in a scalable manner automatically profiting from the repository services such as versioning, query, transactions or namespaces which make a content repository an ideal data store for many applications.
+
+A "Generic Content Application" (an application that has no particular functional focus but just allows for generic introspection and manipulation of the repository) uses the capabilities of the node types, access control and other facilities to display a user interface or a network protocol to the end user, seemingly independent from the content that is stored in the repository. Examples of such generic applications are "The Content Explorer", "WebDAV Server" or a "Subversion Server". (Or generic Portal, CMS or DMS applications).
+
+A "Specialized Content Application" operates under the assumption that there are certain node types that it operates on, and that it is familiar at least partially with the data model exposed by defined node types. Mostly these node types are defined by the application itself and ship with the application. These applications use a content repository as their persistence layer as a natural evolution from the use of an RDBMS or a file system. Examples of "Specialized Content Applications" have a very wide range from a "DVD Collection Management", to a "Message Board", to "Workflow and BPM" but also possibly complete next generation "Enterprise Resource Planning Systems".
+
+h2. Content Repository API
+
+The Content Repository API Layer is split into two major sections.
+
+* The Content Repository API defined by JSR-170
+* A number features of a content repository, that have been removed from the JSR-170 specification since they are difficult to implement on existing non-java-based content repositories and administrational Repository tasks that have also been deliberately excluded from JSR-170
+
+There are only very few (mostly administrational) applications which make use of the non-JSR-170 APIs provided by Jackrabbit.
+
+The boxes in the architecture chart do not symbolize package names or class names directly but mostly semantically grouped blocks of functionality.
+
+h2. Content Repository Implementation
+
+The content Repository Implementation portion of the architecture chart reflects the major building blocks of the jackrabbit content repository implementation.
+
+The size of the blocks symbolizes roughly the amount of code and therefore the complexity of the individual functional block. Again the functional blocks do not directly map to package or class names.
+
+There are three scopes in a content repository: A repository scope, a workspace scope and a session scope.
+
+Every function that is operated against a repository can be attributed to at least one of these scopes, some functions can operate on more than one scope.
+
+* Repository
+* Nodetype
+* Version
+* NamespaceRegistry
+* Workspace
+* Query
+* Observation
+* State
+* Xml
+* Session
+* Path
+* HierarchyManager
+* QName
+* ItemImpl, PropertyImpl, NodeImpl
+* ItemId, PropertyId, NodeId
+* ItemManager
+
+This is not a complete list but includes some of the most important component of the content repository implementation.
Propchange: jackrabbit/site/trunk/content/jackrabbit-architecture.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: jackrabbit/site/trunk/content/jackrabbit-architecture.mdtext
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/jackrabbit-architecture.mdtext?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/jackrabbit-architecture.mdtext (added)
+++ jackrabbit/site/trunk/content/jackrabbit-architecture.mdtext Tue Jan 10 18:50:59 2012
@@ -0,0 +1,104 @@
+Title: Jackrabbit Architecture
+* [How Jackrabbit works](how-jackrabbit-works.html)
+* [Repository lifecycle](repository-lifecycle.html)
+* [Search implementation](search-implementation.html)
+* [Index readers](index-readers.html)
+* [Concurrency control](concurrency-control.html)
+
+The general architecture of Jackrabbit can be described in three Layers: A
+Content Application Layer, an API Layer and a Content Repository
+Implementation Layer.
+
+!overview.png!
+
+<a name="JackrabbitArchitecture-ContentApplications"></a>
+## Content Applications
+
+Content Applications interact through the JSR-170 API with the Content
+Repository Implementation. There are numerous applications that are
+available for JSR-170 repositories, some of them are very generic (like a
+WebDAV server) other applications can be very specific and make use of the
+content repository as a store for the information that is used by the
+applications. Java Applications can use a JSR-170 content repository as a
+replacement for anything from property-files, XML-configuration, certain
+portions of relational database functionality to straight file system or
+blob-management. Using a content repository allows an application to deal
+with an arbitrarily large hierarchical space in a scalable manner
+automatically profiting from the repository services such as versioning,
+query, transactions or namespaces which make a content repository an ideal
+data store for many applications.
+
+A "Generic Content Application" (an application that has no particular
+functional focus but just allows for generic introspection and manipulation
+of the repository) uses the capabilities of the node types, access control
+and other facilities to display a user interface or a network protocol to
+the end user, seemingly independent from the content that is stored in the
+repository. Examples of such generic applications are "The Content
+Explorer", "WebDAV Server" or a "Subversion Server". (Or generic Portal,
+CMS or DMS applications).
+
+A "Specialized Content Application" operates under the assumption that
+there are certain node types that it operates on, and that it is familiar
+at least partially with the data model exposed by defined node types.
+Mostly these node types are defined by the application itself and ship with
+the application. These applications use a content repository as their
+persistence layer as a natural evolution from the use of an RDBMS or a file
+system. Examples of "Specialized Content Applications" have a very wide
+range from a "DVD Collection Management", to a "Message Board", to
+"Workflow and BPM" but also possibly complete next generation "Enterprise
+Resource Planning Systems".
+
+<a name="JackrabbitArchitecture-ContentRepositoryAPI"></a>
+## Content Repository API
+
+The Content Repository API Layer is split into two major sections.
+
+* The Content Repository API defined by JSR-170
+* A number features of a content repository, that have been removed from
+the JSR-170 specification since they are difficult to implement on existing
+non-java-based content repositories and administrational Repository tasks
+that have also been deliberately excluded from JSR-170
+
+There are only very few (mostly administrational) applications which make
+use of the non-JSR-170 APIs provided by Jackrabbit.
+
+The boxes in the architecture chart do not symbolize package names or class
+names directly but mostly semantically grouped blocks of functionality.
+
+<a name="JackrabbitArchitecture-ContentRepositoryImplementation"></a>
+## Content Repository Implementation
+
+The content Repository Implementation portion of the architecture chart
+reflects the major building blocks of the jackrabbit content repository
+implementation.
+
+The size of the blocks symbolizes roughly the amount of code and therefore
+the complexity of the individual functional block. Again the functional
+blocks do not directly map to package or class names.
+
+There are three scopes in a content repository: A repository scope, a
+workspace scope and a session scope.
+
+Every function that is operated against a repository can be attributed to
+at least one of these scopes, some functions can operate on more than one
+scope.
+
+* Repository
+* Nodetype
+* Version
+* NamespaceRegistry
+* Workspace
+* Query
+* Observation
+* State
+* Xml
+* Session
+* Path
+* HierarchyManager
+* QName
+* ItemImpl, PropertyImpl, NodeImpl
+* ItemId, PropertyId, NodeId
+* ItemManager
+
+This is not a complete list but includes some of the most important
+component of the content repository implementation.
Propchange: jackrabbit/site/trunk/content/jackrabbit-architecture.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: jackrabbit/site/trunk/content/jackrabbit-chair-2006-resolution.cwiki
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/jackrabbit-chair-2006-resolution.cwiki?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/jackrabbit-chair-2006-resolution.cwiki (added)
+++ jackrabbit/site/trunk/content/jackrabbit-chair-2006-resolution.cwiki Tue Jan 10 18:50:59 2012
@@ -0,0 +1,29 @@
+_From the [minutes|http://www.apache.org/foundation/records/minutes/2006/board_minutes_2006_08_16.txt] of the Apache board meeting on August 16th, 2006:_
+
+{code}
+ 6. Special Orders
+
+ A. Resolution to change the Chair of the Jackrabbit PMC
+
+ WHEREAS, the Board of Directors heretofore appointed Roy
+ T. Fielding to the office of Vice President, Apache Jackrabbit,
+ and
+
+ WHEREAS, the Board of Directors is in receipt of the
+ resignation of Roy T. Fielding from the office of Vice
+ President, Apache Jackrabbit;
+
+ NOW, THEREFORE, BE IT RESOLVED, that Roy T. Fielding is
+ relieved and discharged from the duties and responsibilities of
+ the office of Vice President, Apache Jackrabbit, and
+
+ BE IT FURTHER RESOLVED, that Jukka Zitting be and hereby is
+ appointed to the office of Vice President, Apache Jackrabbit,
+ to serve in accordance with and subject to the direction of the
+ Board of Directors and the Bylaws of the Foundation until
+ death, resignation, retirement, removal or disqualification, or
+ until a successor is appointed.
+
+ Special Order 6A, Change the Chair of the Jackrabbit PMC, was
+ approved by Unanimous Vote.
+{code}
\ No newline at end of file
Propchange: jackrabbit/site/trunk/content/jackrabbit-chair-2006-resolution.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: jackrabbit/site/trunk/content/jackrabbit-chair-2006-resolution.mdtext
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/jackrabbit-chair-2006-resolution.mdtext?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/jackrabbit-chair-2006-resolution.mdtext (added)
+++ jackrabbit/site/trunk/content/jackrabbit-chair-2006-resolution.mdtext Tue Jan 10 18:50:59 2012
@@ -0,0 +1,31 @@
+Title: Jackrabbit Chair 2006 Resolution
+_From the [minutes](http://www.apache.org/foundation/records/minutes/2006/board_minutes_2006_08_16.txt)
+ of the Apache board meeting on August 16th, 2006:_
+
+
+ 6. Special Orders
+
+ A. Resolution to change the Chair of the Jackrabbit PMC
+
+ WHEREAS, the Board of Directors heretofore appointed Roy
+ T. Fielding to the office of Vice President, Apache Jackrabbit,
+ and
+
+ WHEREAS, the Board of Directors is in receipt of the
+ resignation of Roy T. Fielding from the office of Vice
+ President, Apache Jackrabbit;
+
+ NOW, THEREFORE, BE IT RESOLVED, that Roy T. Fielding is
+ relieved and discharged from the duties and responsibilities of
+ the office of Vice President, Apache Jackrabbit, and
+
+ BE IT FURTHER RESOLVED, that Jukka Zitting be and hereby is
+ appointed to the office of Vice President, Apache Jackrabbit,
+ to serve in accordance with and subject to the direction of the
+ Board of Directors and the Bylaws of the Foundation until
+ death, resignation, retirement, removal or disqualification, or
+ until a successor is appointed.
+
+ Special Order 6A, Change the Chair of the Jackrabbit PMC, was
+ approved by Unanimous Vote.
+
Propchange: jackrabbit/site/trunk/content/jackrabbit-chair-2006-resolution.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: jackrabbit/site/trunk/content/jackrabbit-components.cwiki
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/jackrabbit-components.cwiki?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/jackrabbit-components.cwiki (added)
+++ jackrabbit/site/trunk/content/jackrabbit-components.cwiki Tue Jan 10 18:50:59 2012
@@ -0,0 +1,25 @@
+The Apache Jackrabbit project consists of a number of related components. The main components are:
+
+* [Jackrabbit API]
+* [Jackrabbit JCR Commons]
+* [Jackrabbit JCR Tests]
+* [Jackrabbit Core]
+* [Jackrabbit Text Extractors] (replaced by [Tika|http://lucene.apache.org/tika/] in Jackrabbit 2.x)
+* [Jackrabbit JCR-RMI]
+* [Jackrabbit WebDAV Library]
+* [Jackrabbit JCR Client]
+* [Jackrabbit JCR to DAV]
+* [Jackrabbit JCR Server]
+* [Jackrabbit JCR Servlet]
+* [Jackrabbit Web Application]
+* [Jackrabbit JCA Resource Adapter]
+* [Jackrabbit SPI]
+* [Jackrabbit SPI Commons]
+* [Jackrabbit JCR to SPI]
+* [Jackrabbit SPI to JCR]
+* [Jackrabbit SPI to DAV]
+* [Jackrabbit Standalone Server|Standalone Server]
+* [Jackrabbit OCM] ([Jackrabbit commons|http://jackrabbit.apache.org/commons/] component since Jackrabbit 1.6)
+* [Jackrabbit OCM Node Management] ([Jackrabbit commons|http://jackrabbit.apache.org/commons/] component since Jackrabbit 1.6)
+
+In addition there are a number of contributed components in the {{sandbox}} folder of the Jackrabbit project. These components are not yet considered stable enough to be included in the official Apache Jackrabbit releases.
Propchange: jackrabbit/site/trunk/content/jackrabbit-components.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: jackrabbit/site/trunk/content/jackrabbit-components.mdtext
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/jackrabbit-components.mdtext?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/jackrabbit-components.mdtext (added)
+++ jackrabbit/site/trunk/content/jackrabbit-components.mdtext Tue Jan 10 18:50:59 2012
@@ -0,0 +1,35 @@
+Title: Jackrabbit Components
+The Apache Jackrabbit project consists of a number of related components.
+The main components are:
+
+* [Jackrabbit API](jackrabbit-api.html)
+* [Jackrabbit JCR Commons](jackrabbit-jcr-commons.html)
+* [Jackrabbit JCR Tests](jackrabbit-jcr-tests.html)
+* [Jackrabbit Core](jackrabbit-core.html)
+* [Jackrabbit Text Extractors](jackrabbit-text-extractors.html)
+ (replaced by [Tika|http://lucene.apache.org/tika/]
+ in Jackrabbit 2.x)
+* [Jackrabbit JCR-RMI](jackrabbit-jcr-rmi.html)
+* [Jackrabbit WebDAV Library](jackrabbit-webdav-library.html)
+* [Jackrabbit JCR Client](jackrabbit-jcr-client.html)
+* [Jackrabbit JCR to DAV](jackrabbit-jcr-to-dav.html)
+* [Jackrabbit JCR Server](jackrabbit-jcr-server.html)
+* [Jackrabbit JCR Servlet](jackrabbit-jcr-servlet.html)
+* [Jackrabbit Web Application](jackrabbit-web-application.html)
+* [Jackrabbit JCA Resource Adapter](jackrabbit-jca-resource-adapter.html)
+* [Jackrabbit SPI](jackrabbit-spi.html)
+* [Jackrabbit SPI Commons](jackrabbit-spi-commons.html)
+* [Jackrabbit JCR to SPI](jackrabbit-jcr-to-spi.html)
+* [Jackrabbit SPI to JCR](jackrabbit-spi-to-jcr.html)
+* [Jackrabbit SPI to DAV](jackrabbit-spi-to-dav.html)
+* [Jackrabbit Standalone Server](standalone-server.html)
+* [Jackrabbit OCM](jackrabbit-ocm.html)
+ ([Jackrabbit commons|http://jackrabbit.apache.org/commons/] component
+since Jackrabbit 1.6)
+* [Jackrabbit OCM Node Management](jackrabbit-ocm-node-management.html)
+ ([Jackrabbit commons|http://jackrabbit.apache.org/commons/] component
+since Jackrabbit 1.6)
+
+In addition there are a number of contributed components in the *sandbox*
+folder of the Jackrabbit project. These components are not yet considered
+stable enough to be included in the official Apache Jackrabbit releases.
Propchange: jackrabbit/site/trunk/content/jackrabbit-components.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: jackrabbit/site/trunk/content/jackrabbit-configuration.cwiki
URL: http://svn.apache.org/viewvc/jackrabbit/site/trunk/content/jackrabbit-configuration.cwiki?rev=1229679&view=auto
==============================================================================
--- jackrabbit/site/trunk/content/jackrabbit-configuration.cwiki (added)
+++ jackrabbit/site/trunk/content/jackrabbit-configuration.cwiki Tue Jan 10 18:50:59 2012
@@ -0,0 +1,209 @@
+{toc:minLevel=2}
+
+Apache Jackrabbit needs two pieces of information to set up a runtime content repository instance:
+
+* *Repository home directory* The filesystem path of the directory containing the content repository accessed by the runtime instance of Jackrabbit. This directory usually contains all the repository content, search indexes, internal configuration, and other persistent information managed within the content repository. Note that this is not absolutely required and some persistence managers and other Jackrabbit components may well be configured to access files and even other resources (like remote databases) outside the repository home directory. A designated repository home directory is however always needed even if some components choose to not use it. Jackrabbit will automatically fill in the repository home directory with all the required files and subdirectories when the repository is first instantiated.
+
+* *Repository configuration file* The filesystem path of the repository configuration XML file. This file specifies the class names and properties of the various Jackrabbit components used to manage and access the content repository. Jackrabbit parses this configuration file and instantiates the specified components when the runtime content repository instance is created.
+
+These two configuration parameters are passed either directly to Jackrabbit when creating a repository instance or indirectly through settings for a JNDI object factory or some other component management system.
+
+For each workspace that was created, there will also be a workspace.xml file created inside the workspace home directory that will be used for the workspace - these files have to be changed, too, because the workspace-specific configuration inside repository.xml is only used as a template for new workspaces, ie. if you use the {{createWorkspace()}} method of the Jackrabbit API, the workspace.xml is just a copy of the [Workspace|#Workspace configuration] element inside repository.xml. You can also manually create the workspace folder with a workspace.xml file to create a new workspace yourself (Please note that depending on the [persistence manager|#Persistence configuration] you will also have to setup a database and configure the access to it).
+
+h2. Repository configuration
+
+The repository configuration file, typically called {{repository.xml}}, specifies global options like security, versioning and clustering settings. A default workspace configuration template is also included in the repository configuration file. The exact format of this XML configuration file is defined in the following document type definition (DTD) files published by the Apache Jackrabbit project.
+
+ * [-//The Apache Software Foundation//DTD Jackrabbit 1.5//EN|http://jackrabbit.apache.org/dtd/repository-1.5.dtd]
+ * [-//The Apache Software Foundation//DTD Jackrabbit 1.4//EN|http://jackrabbit.apache.org/dtd/repository-1.4.dtd]
+ * [-//The Apache Software Foundation//DTD Jackrabbit 1.2//EN|http://jackrabbit.apache.org/dtd/repository-1.2.dtd]
+ * [-//The Apache Software Foundation//DTD Jackrabbit 1.0//EN|http://jackrabbit.apache.org/dtd/repository-1.0.dtd]
+
+All Jackrabbit 1.x versions are fully backwards compatible, so you can use a recent Jackrabbit version without having to modify your existing repository configuration. Of course you will need to make configuration changes if you want to enable new features like the data store introduced in Jackrabbit 1.4.
+
+The top-level structure of the repository configuration file is shown below. The {{<!DOCTYPE>}} declaration is optional, but if you include it Jackrabbit 1.5 will use XML validation to make sure that the configuration file is correctly formatted.
+
+{code:xml}
+<!DOCTYPE Repository
+ PUBLIC "-//The Apache Software Foundation//DTD Jackrabbit 1.5//EN"
+ "http://jackrabbit.apache.org/dtd/repository-1.5.dtd">
+<Repository>
+ <FileSystem .../>
+ <Security .../>
+ <Workspaces .../>
+ <Workspace .../>
+ <Versioning .../>
+ <SearchIndex .../> <!-- optional -->
+ <Cluster .../> <!-- optional, available since 1.2 -->
+ <DataStore .../> <!-- optional, available since 1.4 -->
+</Repository>
+{code}
+
+Starting with Jackrabbit 1.5, the order of the configuration elements below {{<Repository/>}} is now fixed.
+
+The repository configuration elements are:
+
+ * {{[FileSystem|#File system configuration]}}: The virtual file system used by the repository to store things like registered namespaces and node types.
+ * {{[Security|#Security configuration]}}: Authentication and authorization configuration.
+ * {{[Workspaces|#Workspace configuration]}}: Configuration on where and how workspaces are managed.
+ * {{[Workspace|#Workspace configuration]}}: Default workspace configuration template.
+ * {{[Versioning|#Versioning configuration]}}: Configuration of the repository-wide version store.
+ * {{[SearchIndex|#Search configuration]}}: Configuration of the search index that covers the repository-wide {{/jcr:system}} content tree.
+ * {{[Cluster|#Cluster configuration]}}: Clustering configuration.
+ * {{[DataStore|#Data store configuration]}}: Data store configuration.
+
+See the Jackrabbit 1.5 [default configuration|^repository.xml], for an example repository configuration file.
+
+{tip}
+It is a good idea to place the {{repository.xml}} file _inside_ the repository home directory. This keeps your repository and its configuration nicely contained within a single directory tree.
+{tip}
+
+h3. Bean configuration elements
+
+Most of the entries in the configuration file are based on the following generic JavaBean configuration pattern. Such configuration specifies that the repository should use an instance of the specified class with the specified properties for the named functionality.
+
+{code:xml}
+<ConfigurationElement class="fully.qualified.ClassName">
+ <param name="property1" value="...">
+ <param name="property2" value="...">
+<ConfigurationElement>
+{code}
+
+h3. Configuration variables
+
+Jackrabbit supports configuration variables of the form _$\{name\}_. These variables can be used to avoid hardcoding specific options in the configuration files. The following variables are available in all Jackrabbit versions:
+
+* {{$\{rep.home\}:}} Repository home directory.
+* {{$\{wsp.name\}:}} Workspace name. Only available in workspace configuration.
+* {{$\{wsp.home\}:}} Workspace home directory. Only available in workspace configuration.
+
+Since Jackrabbit 1.4 (see [JCR-1304|https://issues.apache.org/jira/browse/JCR-1304]) it has been possible to use system properties or any application-specific settings as configuration variables.
+
+h2. Security configuration
+
+The security configuration element is used to specify authentication and authorization settings for the repository. The structure of the security configuration element is:
+
+{code:xml}
+<Security appName="Jackrabbit">
+ <SecurityManager .../> <!-- optional, available since 1.5 -->
+ <AccessManager .../> <!-- mandatory until 1.4, optional since 1.5 -->
+ <LoginModule .../> <!-- optional -->
+</Security>
+{code}
+
+By default Jackrabbit uses the [Java Authentication and Authorization Service|http://java.sun.com/j2se/1.4.2/docs/guide/security/jaas/JAASRefGuide.html] (JAAS) to authenticate users who try to access the repository. The {{appName}} parameter in the {{<Security/>}} element is used as the JAAS application name of the repository.
+
+If JAAS authentication is not available or (as is often the case) too complex to set up, Jackrabbit allows you to specify a repository-specific JAAS [LoginModule|http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/spi/LoginModule.html] that is then used for authenticating repository users. The default [SimpleLoginModule|http://jackrabbit.apache.org/api/1.5/org/apache/jackrabbit/core/security/SimpleLoginModule.html] class included in Jackrabbit implements a trivially simple authentication mechanism that accepts any username and any password as valid authentication credentials.
+
+Once a user has been authenticated, Jackrabbit will use the configured [AccessManager|http://jackrabbit.apache.org/api/1.5/org/apache/jackrabbit/core/security/AccessManager.html] to control what parts of the repository content the user is allowed to access and modify. The default [SimpleAccessManager|http://jackrabbit.apache.org/api/1.5/org/apache/jackrabbit/core/security/SimpleAccessManager.html] class included in Jackrabbit implements a trivially simple authorization mechanism that grants full read access to all users and write access to everyone except anonymous users.
+
+The slightly more advanced [SimpleJBossAccessManager|http://jackrabbit.apache.org/api/1.5/org/apache/jackrabbit/core/security/SimpleJBossAccessManager.html] class was added in Jackrabbit 1.3 (see [JCR-650|https://issues.apache.org/jira/browse/JCR-650]). This class is designed for use with the [JBoss Application Server|http://www.jboss.org/jbossas/], where it maps JBoss roles to Jackrabbit permissions.
+
+h2. Workspace configuration
+
+A Jackrabbit repository contains one or more workspaces that are each configured in a separate {{workspace.xml}} configuration file. The {{Workspaces}} element of the repository configuration specifies where and how the workspaces are managed. The repository configuration also contains a default workspace configuration template that is used to create the {{workspace.xml}} file of a new workspace unless more specific configuration is given when the workspace is created. See the {{createWorkspace}} methods in the [JackrabbitWorkspace|http://jackrabbit.apache.org/api/1.5/org/apache/jackrabbit/api/JackrabbitWorkspace.html] interface for more details on workspace creating workspaces.
+
+The workspace settings in the repository configuration file are:
+
+{code:xml}
+<Workspaces rootPath="${rep.home}/workspaces"
+ defaultWorkspace="default"
+ configRootPath="..." <!-- optional -->
+ maxIdleTime="..."/> <!-- optional -->
+
+<Workspace .../> <!-- default workspace configuration template -->
+{code}
+
+The following global workspace configuration options are specified in the {{Workspaces}} element:
+
+ * {{rootPath}}: The native file system directory for workspaces. A subdirectory is automatically created for each workspace, and the path of that subdirectory can be used in the workspace configuration as the {{$\{wsp.path\} }}variable.
+ * {{defaultWorkspace}}: Name of the default workspace. This workspace is automatically created when the repository is first started.
+ * {{configRootPath}}: By default the configuration of each workspace is stored in a {{workspace.xml}} file within the workspace directory within the {{rootPath}} directory. If this option is specified, then the workspace configuration files are stored within the specified path in the virtual file system (see above) configured for the repository.
+ * {{maxIdleTime}}: By default Jackrabbit only releases resources associated with an opened workspace when the entire repository is closed. This option, if specified, sets the maximum number of seconds that a workspace can remain unused before the workspace is automatically closed.
+
+The workspace configuration template and all {{workspace.xml}} configuration files have the following structure:
+
+{code:xml}
+<Workspace name="${wsp.name}">
+ <FileSystem .../>
+ <PersistenceManager .../>
+ <SearchIndex .../> <!-- optional -->
+ <ISMLocking .../> <!-- optional, available since 1.4 -->
+</Workspace>
+{code}
+
+The workspace configuration elements are:
+
+ * {{[FileSystem|#File system configuration]}}: The virtual file system passed to the persistence manager and search index.
+ * {{[PersistenceManager|#Persistence configuration]}}: Persistence configuration for workspace content.
+ * {{[SearchIndex|#Search configuration]}}: Configuration of the workspace search index.
+ * {{[ISMLocking|#Item state locking configuration]}}: Locking configuration for concurrent access to workspace content.
+
+{note}
+To modify the configuration of an existing workspace, you need to change the {{workspace.xml}} file of that workspace. Changing the {{<Workspace/>}} element in the repository configuration file will not affect existing workspaces.
+{note}
+
+h2. Versioning configuration
+
+The version histories of all versionable nodes are stored in a repository-wide version store configured in the {{Versioning}} element of the repository configuration. The versioning configuration is much like workspace configuration as they are both used by Jackrabbit for storing content. The main difference between versioning and workspace configuration is that no search index is specified for the version store as version histories are indexed and searched using the repository-wide search index. Another difference is that there are no {{$\{wsp.name\} }}or {{$\{wsp.path\} }}variables for the versioning configuration. Instead the native file system path of the version store is explicitly specified in the configuration.
+
+The structure of the versioning configuration is:
+
+{code:xml}
+<Versioning rootPath="${rep.home}/version">
+ <FileSystem .../>
+ <PersistenceManager .../>
+ <ISMLocking .../> <!-- optional, available since 1.4 -->
+</Versioning>
+{code}
+
+The versioning configuration elements are:
+
+ * {{[FileSystem|#File system configuration]}}: The virtual file system passed to the persistence manager.
+ * {{[PersistenceManager|#Persistence configuration]}}: Persistence configuration for the version store.
+ * {{[ISMLocking|#Item state locking configuration]}}: Locking configuration for concurrent access to workspace content.
+
+h2. Search configuration
+
+See the [Search|http://wiki.apache.org/jackrabbit/Search] page on the Jackrabbit wiki.
+
+h2. Persistence configuration
+
+The Persistence Manager is one of the most important parts of the configuration, because it actually takes care of storing the nodes and properties. There are various very different implementations, but most of them are using databases to store the data. If you use a database PM and like to connect to an external database, you might also have to setup the database. This might include access rights for the Jackrabbit database user to allow creation of tables, because the name of the table typically depends on the workspace name (see the individual PM's javadoc for more information).
+
+For large binary properties there is the option to use the {{[DataStore|#Data store configuration]}} instead of the Persistence Manager.
+
+For more detailed information and an overview of available PMs, see the [PersistenceManagerFAQ|http://wiki.apache.org/jackrabbit/PersistenceManagerFAQ] page on the Jackrabbit wiki.
+
+{note}
+If you use a database persistence manager, the configured database connection *must not* be under the control of an external transaction manager. Jackrabbit implements distributed XA transaction support on a higher level, and expects to be in full control of the underlying database connection.
+{note}
+
+h2. File system configuration
+
+Early versions on Jackrabbit were designed to abstract their persistence mechanism using a virtual file system layer defined in the [FileSystem|http://jackrabbit.apache.org/api/1.5/org/apache/jackrabbit/core/fs/FileSystem.html] interface. This low-level approach didn't work that well in practice, and so most of the persistence abstraction is now handled in a higher level. However, certain parts of Jackrabbit still use this file system abstraction.
+
+A virtual file system is configured in a {{<FileSystem/>}} bean configuration element. See the main file system implementations [LocalFileSystem|http://jackrabbit.apache.org/api/1.5/org/apache/jackrabbit/core/fs/local/LocalFileSystem.html], [DatabaseFileSystem|http://jackrabbit.apache.org/api/1.5/org/apache/jackrabbit/core/fs/db/DatabaseFileSystem.html] (including subclasses), and [MemoryFileSystem|http://jackrabbit.apache.org/api/1.5/org/apache/jackrabbit/core/fs/mem/MemoryFileSystem.html] for the available options. The recommended alternative is to use the LocalFileSystem implementation that simply maps abstract file system accesses to the specified directory within the native file system.
+
+h2. Cluster configuration
+
+See the [Clustering|http://wiki.apache.org/jackrabbit/Clustering] page on the Jackrabbit wiki.
+
+h2. Data store configuration
+
+See the [DataStore|http://wiki.apache.org/jackrabbit/DataStore] page on the Jackrabbit wiki.
+
+h2.Item state locking configuration
+
+TODO
+
+h2. Passwords in configuration (as of Jackrabbit 2.3)
+
+When using a database-backed persistence manager or another component, you usually need to include the database password in Jackrabbit configuration. If you don't want to store such passwords in plain text inside the configuration file, you can encode the password in base64 and prefix it with "\{base64}". Jackrabbit will automatically decode such a password before passing it to the underlying database.
+
+As an example, the following two password configuration parameters are equivalent ("dGVzdA==" is the base64 encoding of "test"):
+
+{code:xml}
+<param name="password" value="test"/>
+<param name="password" value="{base64}dGVzdA=="/>
+{code}
\ No newline at end of file
Propchange: jackrabbit/site/trunk/content/jackrabbit-configuration.cwiki
------------------------------------------------------------------------------
svn:eol-style = native