jackrabbit-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tri...@apache.org
Subject svn commit: r1582932 - in /jackrabbit/commons/filevault/trunk: ./ parent/ vault-doc/ vault-doc/src/ vault-doc/src/site/ vault-doc/src/site/markdown/ vault-doc/src/site/resources/ vault-doc/src/site/resources/css/
Date Sat, 29 Mar 2014 01:08:42 GMT
Author: tripod
Date: Sat Mar 29 01:08:41 2014
New Revision: 1582932

URL: http://svn.apache.org/r1582932
Log:
@trivial create proper filevault docu site

Added:
    jackrabbit/commons/filevault/trunk/vault-doc/
    jackrabbit/commons/filevault/trunk/vault-doc/README.md
    jackrabbit/commons/filevault/trunk/vault-doc/pom.xml
    jackrabbit/commons/filevault/trunk/vault-doc/src/
    jackrabbit/commons/filevault/trunk/vault-doc/src/site/
    jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/
    jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/filter.md
    jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/index.md
    jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/license.md
    jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/overview.md
    jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/usage.md
    jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/vault_api.png
    jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/vault_sample.png
    jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/vaultfs.md
    jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/vaultfs.png
    jackrabbit/commons/filevault/trunk/vault-doc/src/site/resources/
    jackrabbit/commons/filevault/trunk/vault-doc/src/site/resources/css/
    jackrabbit/commons/filevault/trunk/vault-doc/src/site/resources/css/site.css
    jackrabbit/commons/filevault/trunk/vault-doc/src/site/site.xml
Modified:
    jackrabbit/commons/filevault/trunk/parent/pom.xml
    jackrabbit/commons/filevault/trunk/pom.xml

Modified: jackrabbit/commons/filevault/trunk/parent/pom.xml
URL: http://svn.apache.org/viewvc/jackrabbit/commons/filevault/trunk/parent/pom.xml?rev=1582932&r1=1582931&r2=1582932&view=diff
==============================================================================
--- jackrabbit/commons/filevault/trunk/parent/pom.xml (original)
+++ jackrabbit/commons/filevault/trunk/parent/pom.xml Sat Mar 29 01:08:41 2014
@@ -167,11 +167,45 @@
                     <artifactId>maven-release-plugin</artifactId>
                     <version>2.1</version>
                 </plugin>
+                <!-- ====================================================================== -->
+                <!-- S I T E    P L U G I N                                                 -->
+                <!-- ====================================================================== -->
+                <plugin>
+                    <groupId>org.apache.maven.plugins</groupId>
+                    <artifactId>maven-site-plugin</artifactId>
+                    <version>3.3</version>
+                    <configuration>
+                        <generateReports>false</generateReports>
+                        <skip>true</skip>
+                        <skipDeploy>true</skipDeploy>
+                    </configuration>
+                    <dependencies>
+                        <dependency>
+                            <groupId>org.apache.maven.doxia</groupId>
+                            <artifactId>doxia-module-markdown</artifactId>
+                            <version>1.5</version>
+                        </dependency>
+                    </dependencies>
+                </plugin>
             </plugins>
         </pluginManagement>
     </build>
 
     <!-- ====================================================================== -->
+    <!-- R E P O R T I N G                                                      -->
+    <!-- ====================================================================== -->
+    <reporting>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-project-info-reports-plugin</artifactId>
+                <!--avoid child modules from inheriting anything from the apache parent pom -->
+                <inherited>false</inherited>
+            </plugin>
+        </plugins>
+    </reporting>
+
+    <!-- ====================================================================== -->
     <!-- D E P E N D E N C Y   M A N A G E M E N T                              -->
     <!-- ====================================================================== -->
     <dependencyManagement>

Modified: jackrabbit/commons/filevault/trunk/pom.xml
URL: http://svn.apache.org/viewvc/jackrabbit/commons/filevault/trunk/pom.xml?rev=1582932&r1=1582931&r2=1582932&view=diff
==============================================================================
--- jackrabbit/commons/filevault/trunk/pom.xml (original)
+++ jackrabbit/commons/filevault/trunk/pom.xml Sat Mar 29 01:08:41 2014
@@ -52,6 +52,7 @@
         <module>vault-diff</module>
         <module>vault-rcp</module>
         <module>vault-davex</module>
+        <module>vault-doc</module>
         <module>vault-vlt</module>
         <module>vault-cli</module>
         <module>vault-hook-example</module>
@@ -75,6 +76,8 @@
                     <excludePackageNames>
                         org.apache.jackrabbit.vault.cli*,org.apache.jackrabbit.vault.davex,*.impl*,org.apache.jackrabbit.vault.util.xml,org.apache.jackrabbit.vault.vlt.actions,org.apache.jackrabbit.vault.vlt.meta.*,org.apache.jackrabbit.vault.packaging.hotfix
                     </excludePackageNames>
+                    <reportOutputDirectory>${basedir}/vault-doc/target/site</reportOutputDirectory>
+                    <additionalparam>-notimestamp</additionalparam>
                 </configuration>
                 <executions>
                     <execution>

Added: jackrabbit/commons/filevault/trunk/vault-doc/README.md
URL: http://svn.apache.org/viewvc/jackrabbit/commons/filevault/trunk/vault-doc/README.md?rev=1582932&view=auto
==============================================================================
--- jackrabbit/commons/filevault/trunk/vault-doc/README.md (added)
+++ jackrabbit/commons/filevault/trunk/vault-doc/README.md Sat Mar 29 01:08:41 2014
@@ -0,0 +1,45 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+  -->
+
+FileVault Documentation
+=======================
+The FileVault documentation lives as Markdown files in `src/site/markdown` such
+that it easy to view e.g. from GitHub. Alternatively the Maven site plugin
+can be used to build and deploy a web site as follows:
+
+From the reactor use
+
+    mvn site
+
+to build the site without Javadoc or
+
+    mvn site -Psite-with-javadoc
+
+to build the site with Javadoc. Review the site at `vault-doc/target/site`.
+
+Then deploy the site to `http://jackrabbit.apache.org/filevault/` using
+
+    mvn site-deploy
+
+Finally review the site at `http://jackrabbit.apache.org/filevault/index.html`.
+To skip the final commit use `-Dscmpublish.skipCheckin=true`. You can then
+review all pending changes in `vault-doc/target/scmpublish-checkout` and follow
+up with `svn commit` manually.
+
+Every committer should be able to deploy the site. No fiddling with
+credentials needed since deployment is done via svn commit to
+`https://svn.apache.org/repos/asf/jackrabbit/site/live/filevault`.

Added: jackrabbit/commons/filevault/trunk/vault-doc/pom.xml
URL: http://svn.apache.org/viewvc/jackrabbit/commons/filevault/trunk/vault-doc/pom.xml?rev=1582932&view=auto
==============================================================================
--- jackrabbit/commons/filevault/trunk/vault-doc/pom.xml (added)
+++ jackrabbit/commons/filevault/trunk/vault-doc/pom.xml Sat Mar 29 01:08:41 2014
@@ -0,0 +1,133 @@
+<?xml version="1.0"?><!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+  -->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd ">
+    <modelVersion>4.0.0</modelVersion>
+    <!-- ====================================================================== -->
+    <!-- P A R E N T  P R O J E C T  D E S C R I P T I O N                      -->
+    <!-- ====================================================================== -->
+    <parent>
+        <groupId>org.apache.jackrabbit.vault</groupId>
+        <artifactId>parent</artifactId>
+        <relativePath>../parent/pom.xml</relativePath>
+        <version>3.1.1-SNAPSHOT</version>
+    </parent>
+
+    <!-- ====================================================================== -->
+    <!-- P R O J E C T  D E S C R I P T I O N                                   -->
+    <!-- ====================================================================== -->
+    <artifactId>org.apache.jackrabbit.vault</artifactId>
+    <version>3.1.1-SNAPSHOT</version>
+    <packaging>jar</packaging>
+
+    <name>Apache Jackrabbit FileVault Documentation</name>
+
+    <!-- ====================================================================== -->
+    <!-- S C M  D E F I N I T I O N                                             -->
+    <!-- ====================================================================== -->
+    <scm>
+        <connection>scm:svn:http://svn.apache.org/repos/asf/jackrabbit/commons/filevault/trunk/vault-doc</connection>
+        <developerConnection>scm:svn:https://svn.apache.org/repos/asf/jackrabbit/commons/filevault/trunk/vault-doc
+        </developerConnection>
+        <url>http://svn.apache.org/viewvc/asf/jackrabbit/commons/filevault/trunk/vault-doc</url>
+    </scm>
+
+    <!-- ====================================================================== -->
+    <!-- B U I L D                                                             -->
+    <!-- ====================================================================== -->
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-site-plugin</artifactId>
+                <configuration>
+                    <generateReports>true</generateReports>
+                    <skip>false</skip>
+                    <relativizeDecorationLinks>false</relativizeDecorationLinks>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-scm-publish-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>scm-publish</id>
+                        <phase>site-deploy</phase>
+                        <goals>
+                            <goal>publish-scm</goal>
+                        </goals>
+                    </execution>
+                </executions>
+                <configuration>
+                    <content>target/site</content>
+                    <checkinComment>@trivial: Site checkin for project ${project.name}-${project.version}
+                    </checkinComment>
+                    <ignorePathsToDelete>
+                        <ignorePathToDelete>apidocs</ignorePathToDelete>
+                    </ignorePathsToDelete>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-resources-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <phase>pre-site</phase>
+                        <goals>
+                            <goal>resources</goal>
+                        </goals>
+                    </execution>
+                </executions>
+                <configuration>
+                    <outputDirectory>${project.build.directory}/site</outputDirectory>
+                </configuration>
+            </plugin>
+        </plugins>
+
+        <resources>
+            <resource>
+                <directory>src/site/markdown</directory>
+                <includes>
+                    <include>*.png</include>
+                    <include>*.jpg</include>
+                    <include>*.jpeg</include>
+                    <include>*.gif</include>
+                </includes>
+            </resource>
+        </resources>
+    </build>
+
+    <reporting>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-project-info-reports-plugin</artifactId>
+                <reportSets>
+                    <reportSet/>
+                </reportSets>
+            </plugin>
+        </plugins>
+    </reporting>
+
+    <distributionManagement>
+        <site>
+            <id>jackrabbit.filevault.site-deploy</id>
+            <url>scm:svn:https://svn.apache.org/repos/asf/jackrabbit/site/live/filevault</url>
+        </site>
+    </distributionManagement>
+
+</project>

Added: jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/filter.md
URL: http://svn.apache.org/viewvc/jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/filter.md?rev=1582932&view=auto
==============================================================================
--- jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/filter.md (added)
+++ jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/filter.md Sat Mar 29 01:08:41 2014
@@ -0,0 +1,105 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+Workspace Filter
+================
+One of the most important meta files of a vault checkout or a content package is the `filter.xml` which is present in
+the `META-INF/vault` directory. The `filter.xml` is used to load and initialize
+the [WorkspaceFilter][api.WorkspaceFilter]. The workspace filter defines what parts of the JCR repository are
+imported or exported during the respective operations through `vlt` or package management.
+
+General Structure
+-----------------
+The `filter.xml` consists of a set of `filter` elements, each with a `root` attribute and an optional list of
+`include` and `exclude` child elements.
+
+Example:
+
+    <workspaceFilter version="1.0">
+        <filter root="/apps/project1" />
+        <filter root="/etc/project1">
+            <exclude pattern=".*\.gif" />
+            <include pattern="/etc/project1/static(/.*)?" />
+        </filter>
+        <filter root="/etc/map" mode="merge" />
+    </workspaceFilter>
+
+### filter elements
+The filter elements are independent of each other and define include and exclude patters for subtrees. The root of a
+subtree is defined by the `root` attribute, which must be an absolute path.
+
+The filter element can have an optional `mode` attribute which specified the [import mode][api.ImportMode] used when
+importing content. the following values are possible:
+
+"replace"
+: This is the normal behavior. Existing content is replaced completely by the imported content, i.e. is overridden or
+  deleted accordingly.
+
+"merge"
+: Existing content is not modified, i.e. only new content is added and none is deleted or modified.
+
+"update"
+: Existing content is updated, new content is added and none is deleted.
+
+### include and exclude elements
+the include and exclude elements allow more fine grained filtering of the subtree during import and export. they have a
+mandatory `pattern` attribute which has the format of a regexp. the regexp is matched against the _path_ of the
+respective or potential JCR node, thus can be relative or absolute.
+
+#### order
+the order of the include and exclude elements is important. the paths are tested in a sequential order against all
+patterns and the type of the last matching element determines if the path is included or not. One caveat is, that
+the type of the first pattern defines the default behavior, so that the filter is more natural to write. If the first
+pattern is include, then the default is exclude and vice versa.
+
+The following example _only_ includes the nodes in `/tmp` that end with `.gif`.
+
+    <filter root="/tmp">
+        <include pattern=".*\.gif"/>
+    </filter>
+
+The following example includes _all_ nodes in `/tmp` except those that end with `.gif`.
+
+    <filter root="/tmp">
+        <exclude pattern=".*\.gif"/>
+    </filter>
+
+Usage for export
+----------------
+When exporting content into the filesystem or a content package, the workspace filter defines which nodes are
+serialized. It is important to know, that only the nodes that match the filter are actually traversed, which can lead
+to unexpected results.
+
+for example:
+
+    <filter root="/tmp">
+        <include pattern="/tmp/a(/.*)?"/>
+        <include pattern="/tmp/b/c(/.*)?"/>
+    </filter>
+
+Will include the `/tmp/a` subtree, but not the `/tmp/b/c` subtree, since `/tmp/b` does not match the filter and is
+therefor not traversed.
+
+There is one exception, if **all** the pattern are relative (i.e. don't start with a slash), then the algorithm is:
+
+1. start at the filter root
+2. traverse **all** child nodes recursively
+3. if the path of the child node matches the regexp, include it in the export
+
+
+<!-- references -->
+[api.WorkspaceFilter]: apidocs/org/apache/jackrabbit/vault/fs/api/WorkspaceFilter.html
+[api.ImportMode]: apidocs/org/apache/jackrabbit/vault/fs/api/ImportMode.html
\ No newline at end of file

Added: jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/index.md
URL: http://svn.apache.org/viewvc/jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/index.md?rev=1582932&view=auto
==============================================================================
--- jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/index.md (added)
+++ jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/index.md Sat Mar 29 01:08:41 2014
@@ -0,0 +1,59 @@
+Welcome to Apache Jackrabbit FileVault
+======================================
+
+Jackrabbit FileVault introduces a JCR repository to filesystem mapping. The mapping is exposed by and API and used by the
+_CRX Content Packaging_  that allows to create portable packages of repository content.
+The Vault Command Line Interface aka _vlt_ that provides a subversion like utility to work and develop with repository content.
+
+Apache Jackrabbit FileVault is a project of the Apache Software Foundation.
+
+Downloads
+---------
+The latest filevault sources are available for checkout from [svn]
+(https://svn.apache.org/repos/asf/jackrabbit/commons/filevault/trunk), or you can [fork them]
+(https://github.com/apache/jackrabbit-filevault) on GitHub.
+
+See also our [releases](http://jackrabbit.apache.org/downloads.html) on the Jackrabbit
+download page for slightly more stable versions of the codebase.
+
+Building FileVault
+------------------
+
+You can build FileVault like this:
+
+    mvn clean install
+
+You need Maven 2.0.9 (or higher) with Java 5 (or higher) for the build.
+For more instructions, please see the documentation at:
+
+   http://jackrabbit.apache.org/building-jackrabbit.html
+
+Mailing Lists
+-------------
+
+To get involved with the Apache Jackrabbit project, start by having a
+look at our website and joining our mailing lists. For more details about
+Jackrabbit mailing lists as well as links to list archives, please see:
+
+   http://jackrabbit.apache.org/mailing-lists.html
+
+Latest development
+------------------
+
+The latest FileVault source code is available via Subversion at
+
+   https://svn.apache.org/repos/asf/commons/filevault/trunk
+
+or with ViewVC at
+
+   https://svn.apache.org/viewvc/commons/filevault/trunk
+
+To checkout the main Jackrabbit source tree, run
+
+   svn checkout https://svn.apache.org/repos/asf/commons/filevault/trunk filevault
+
+Credits
+-------
+
+See http://jackrabbit.apache.org/jackrabbit-team.html for the list of
+Jackrabbit committers and main contributors.

Added: jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/license.md
URL: http://svn.apache.org/viewvc/jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/license.md?rev=1582932&view=auto
==============================================================================
--- jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/license.md (added)
+++ jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/license.md Sat Mar 29 01:08:41 2014
@@ -0,0 +1,23 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+License
+=======
+Jackrabbit Filevault and any of its parts are licensed according to the terms listed in the
+[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html).
+
+For further information regarding licensing of Apache Software refer to The Apache
+Software Foundation [licensing information](http://www.apache.org/licenses/).

Added: jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/overview.md
URL: http://svn.apache.org/viewvc/jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/overview.md?rev=1582932&view=auto
==============================================================================
--- jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/overview.md (added)
+++ jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/overview.md Sat Mar 29 01:08:41 2014
@@ -0,0 +1,148 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+Overview
+========
+
+**NOTE**: Parts of the following documentation is outdated and needs review
+- - - 
+
+Jackrabbit FileVault introduces a JCR repository to filesystem mapping. The mapping is exposed by and API and used by several tools:
+
+* JackrabbitVaultPackaging that defines a package including the files, configuration and filter information that allows export/import packages of content.
+* Vault Command Line Interface aka `vlt` that provides a subversion like utility to work and develop with repository content.
+
+The base of the Jackrabbit FileVault is the [VautFs](vaultfs.html) which provides the api for accessing repository through a filesystem like mapping.
+
+![Vault API](vault_api.png?raw=true)
+
+How it works
+------------
+Jackrabbit FileVault works similar to subversion. Usually you checkout a local copy of the (partial) content of the repository and make modifications to it. Once you're finished you upload the modified stuff again. The content is mapped to a local filesystem structure using the JcrFs API. The mechanism works like subversion where you have a copy of the unmodified file and some information about the entries.
+
+Subversion & Vault living together
+----------------------------------
+One of the goals of Jackrabbit FileVault is to provide the ability to store repository content in a SCM for example in subversion. One problem occurs that the _control files_ of vault are not to be checked into subversion since this could cause problem in concurrent development. Those files are kept in the `.vlt` directory which must be excluded from subversion. Using the `svn:ignore` property is not advisable because one can forget to define it. A better option is to use the `global-ignores` option in the subversion user configuration:
+
+    ...
+    ### Section for configuring miscellaneous Subversion options.
+    [miscellany]
+    ### Set global-ignores to a set of whitespace-delimited globs
+    ### which Subversion will ignore in its 'status' output, and
+    ### while importing or adding files and directories.
+    global-ignores = .vlt
+    ...
+### Use Cases
+The following workflows illustrate that the Vault/Subversion coupling works and could easily be automated. Plans are to propagate additions and removals automatically using javahl or a similar java-svn binding.
+
+Imagine the following scenario:
+
+* The application XYZ has some repository content that is exported and stored in subversion
+* User A and B both have a local checkout
+* User A and B work with local test repositories
+
+
+**Workflow 1 - Modification:**
+
+1. User A does a fix in a jsp, checks it into his local repository and tests if the fix works
+2. User A commits the jsp into subversion
+3. User B update this copy via subversion and gets the modifications of the jsp
+4. User B can now checkin the modifications to his local repository
+
+**Workflow 2 - Addition:**
+
+1. User A creates a new file on his local filesystem
+2. User A uses `vlt` to add and commit it to his local repository
+3. User A also adds the file to his subversion working copy and commits it
+4. User B updates subversion and gets the new file
+5. User B updates vault and notifies that this new file is not added to the vault yet
+6. User B adds the file as well to his vault and commits it to the repository.
+
+**Workflow 3 - Deletion:**
+
+1. User A deletes a file using `vlt`. This marks the file as deleted and removes it from disk
+2. User A commits the changes to his local repository
+3. User A marks the file as deleted using =svn= and commits the changes
+4. User B updates subversion which deletes his local copy
+5. User B marks the file as deleted using `vlt` and commits the changes to his local repository
+
+Export/Checkout directory structure
+-----------------------------------
+The root directory of a vault checkout contains a `META-INF/vault` directory which holds the serialization configuration (`config.xml`) the filter information (`filter.xml`) and other settings. The repository content is placed in a directory named `jcr_root`. eg:
+
+    + mycheckeout
+      + META-INF
+      + jcr_root
+
+### `META-INF/vault/config.xml`
+Contains the VaultFs configuration that is (was) used for this checkout (export).
+
+### `META-INF/vault/filter.xml`
+Contains the workspace filter that is (was) used for this checkout (export). also see [Workspace Filter](filter.html) for more details.
+
+### User specific config files 
+Some configuration files are stored in the user's home directory. usually under `~/.vault`.
+
+#### `~/.vault/settings.xml`
+Holds some per user configuration like globally ignored files, etc.
+
+#### `~/.vault/auth.xml`
+Holds authorization information for known repositories.
+
+Usage
+-----
+The console tool is called `vlt` and has the following usage:
+
+    $vlt --help
+    
+    ----------------------------------------------------------------------------------------------
+    Jackrabbit FileVault [version 3.0.0] Copyright 2013 by Apache Software Foundation.
+    See LICENSE.txt for more information.
+    ----------------------------------------------------------------------------------------------
+    Usage:
+      vlt [options] <command> [arg1 [arg2 [arg3] ..]]
+    ----------------------------------------------------------------------------------------------
+    
+    Global options:
+      -Xjcrlog <arg>           Extended JcrLog options (omit argument for help)
+      -Xdavex <arg>            Extended JCR remoting options (omit argument for help)
+      --credentials <arg>      The default credentials to use
+      --config <arg>           The JcrFs config to use
+      -v (--verbose)           verbose output
+      -q (--quiet)             print as little as possible
+      --version                print the version information and exit
+      --log-level <level>      the log4j log level
+      -h (--help) <command>    print this help
+    Commands:
+      export                   Export the Vault filesystem
+      import                   Import a Vault filesystem
+      checkout (co)            Checkout a Vault file system
+      status (st)              Print the status of working copy files and directories.
+      update (up)              Bring changes from the repository into the working copy.
+      info                     Displays information about a local file.
+      commit (ci)              Send changes from your working copy to the repository.
+      revert (rev)             Restore pristine working copy file (undo most local edits).
+      resolved (res)           Remove 'conflicted' state on working copy files or directories.
+      propget (pg)             Print the value of a property on files or directories.
+      proplist (pl)            Print the properties on files or directories.
+      propset (ps)             Set the value of a property on files or directories.
+      add                      Put files and directories under version control.
+      delete (del,rm)          Remove files and directories from version control.
+      diff (di)                Display the differences between two paths.
+      rcp                      Remote copy of repository content.
+      sync                     Control vault sync service
+      console                  Run an interactive console
+    ----------------------------------------------------------------------------------------------

Added: jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/usage.md
URL: http://svn.apache.org/viewvc/jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/usage.md?rev=1582932&view=auto
==============================================================================
--- jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/usage.md (added)
+++ jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/usage.md Sat Mar 29 01:08:41 2014
@@ -0,0 +1,280 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+Usage
+=====
+
+**NOTE**: Parts of the following documentation is outdated and needs review
+- - - 
+
+Vault Console Tool
+------------------
+The console tool is called `vlt` and has the following usage:
+
+    $vlt --help
+    
+    ----------------------------------------------------------------------------------------------
+    Jackrabbit FileVault [version 3.0.0] Copyright 2013 by Apache Software Foundation.
+    See LICENSE.txt for more information.
+    ----------------------------------------------------------------------------------------------
+    Usage:
+      vlt [options] <command> [arg1 [arg2 [arg3] ..]]
+    ----------------------------------------------------------------------------------------------
+    
+    Global options:
+      -Xjcrlog <arg>           Extended JcrLog options (omit argument for help)
+      -Xdavex <arg>            Extended JCR remoting options (omit argument for help)
+      --credentials <arg>      The default credentials to use
+      --config <arg>           The JcrFs config to use
+      -v (--verbose)           verbose output
+      -q (--quiet)             print as little as possible
+      --version                print the version information and exit
+      --log-level <level>      the log4j log level
+      -h (--help) <command>    print this help
+    Commands:
+      export                   Export the Vault filesystem
+      import                   Import a Vault filesystem
+      checkout (co)            Checkout a Vault file system
+      status (st)              Print the status of working copy files and directories.
+      update (up)              Bring changes from the repository into the working copy.
+      info                     Displays information about a local file.
+      commit (ci)              Send changes from your working copy to the repository.
+      revert (rev)             Restore pristine working copy file (undo most local edits).
+      resolved (res)           Remove 'conflicted' state on working copy files or directories.
+      propget (pg)             Print the value of a property on files or directories.
+      proplist (pl)            Print the properties on files or directories.
+      propset (ps)             Set the value of a property on files or directories.
+      add                      Put files and directories under version control.
+      delete (del,rm)          Remove files and directories from version control.
+      diff (di)                Display the differences between two paths.
+      rcp                      Remote copy of repository content.
+      sync                     Control vault sync service
+      console                  Run an interactive console
+    ----------------------------------------------------------------------------------------------
+
+Checkout
+--------
+_todo_
+
+Checkin
+-------
+_todo_
+
+Adding / Removing Files
+-----------------------
+_todo_
+
+Vault Sync
+----------
+The vault sync service is used to synchronize repository content with a local filesystem representation and vice versa.
+This is achieved by installing an OSGi service that will listen for repository changes and scans the filesystem contents
+periodically. It uses the same serialization format as vault for mapping the repository contents to disk.
+
+The vault sync service is a development tool and it is highly discouraged to use it on a productive system.
+Also note that the service can only sync with the local filesystem and cannot be used for remote development.
+
+The initial version (2.3.22 / 2.4.24) only supports simple files and folders but detects special vault serialized files
+(`.content.xml`, `dialog.xml`, etc) and ignores them silently. Thus it is possible to use vault sync on a default vlt
+checkout.
+
+### Installation and Configuration
+The vault sync service is provided as bundle which needs to be installed in Oak (or any other sling runtime). Once the
+service is running it can be configured with the following parameters:
+
+vault.sync.syncroots
+: One or many local filesystem paths that define the sync roots.
+
+vault.sync.fscheckinterval
+: Frequency (in seconds) of which the filesystem should be scanned for changes. default is 5 seconds.
+
+vault.sync.enabled
+: General flag that enables/disables the service
+
+Note: It is advisable to configure the service via a `sling:OsgiConfig` node with the name
+`org.apache.jackrabbit.vault.sync.impl.VaultSyncServiceImpl`. Once the service has configured sync roots it will
+initialize the sync root with the following files:
+
+`.vlt-sync-config.properties`
+: Per sync-root config
+
+`.vlt-sync.log`
+: log file that contains information about the operations performed during syncing
+
+`.vlt-sync-filter.xml`
+: filter that is neede to configure what portions of the repository are synced.
+
+The vault sync service can also be installed using the vlt command line tool. See _Vlt Integration_ below.
+
+### .vlt-sync-filter.xml
+The sync filter has the format of a normal vault workspace filter. If the sync root lies on a vlt checkout, specifically
+points to a jcr_root directory of a such, then no `.vlt-sync-filter.xml` is initialized in the sync root, but the one
+defined by the respective vlt checkout is used. this is usually `META-INF/vault/filter.xml`.
+
+### .vlt-sync-config.properties
+This config has the following default content:
+
+    #
+    # Vault Sync Config File
+    #
+    # Note: Changes to this file are detected automatically if the Vault Sync Service is
+    # running and this directory is configured as sync root.
+    #
+    # Supported Properties:
+    # ---------------------
+    #
+    # disabled = ( "true" | "false" )
+    #     Defines if syncing of this directory is generally disabled. It can be useful
+    #     to disabled syncing temporarily if structural changes need to be done that required
+    #     several modifications.
+    #
+    #     defaults to: false
+    disabled=false
+
+    # sync-once= ( "" | "JCR2FS" | "FS2JCR" )
+    #     If non empty the next scan will trigger a full sync in the direction indicated.
+    #
+    #     JCR2FS: 'export' all content in the JCR repository and write to the local disk.
+    #     FS2JCR: 'import' all content from the disk into the JCR repository.
+    #
+    #     defaults to: ""
+    sync-once=
+
+    # sync-log = <filename>
+    #     Defines the filename of the sync log.
+    #
+    #     defaults to: .vlt-sync.log
+    #
+    #sync-log=.vlt-sync.log
+
+A note to _sync-one_: This property is used to trigger a directional full sync between the repository and the file
+system (usinig `JCR2FS`) or vice versa (using `FS2JCR`). This is especially useful when installing vault sync for the
+first time or adding a new sync root. Allow a maximum of 5 seconds (or whatever you configured the sync interval to be)
+for a configuration change to be detected. Check the `.vlt-sync.log` or the `error.log` of your instance for progress or
+errors.
+
+For example you started of a project directly in the repository using CRXDE Lite and now decide to use your local IDE
+for further development. After configuring the sync root and the filter, you would set the sync-once property to
+`JCR2FS` to get all your files created in the local sync root.
+
+For example you start with a fresh repository and want to import local files that you retrieved from a SCM. After
+configuring the sync root and the filter (which should be under SCM, too), you would set the sync-once property
+to `FS2JCR`.
+
+### Operation
+Once properly configured and running you should do an initial full sync to get system in a synchronized state.
+to do so, follow the notes above regarding the sync-once configuration property. After that each repository modification
+within the specified filter will trigger a repository-to-filesystem synchronization of the modified nodes
+(see initial note on supported serializations). The repository changes are applied almost immediately since JCR
+observation events are pushed to it's listeners.
+
+On each sync interval, the service scans the filesystem for changes and eventually synchronizes the changes back with
+the repository. So allow a maximum of 5 seconds (or whatever you configured the sync interval to be) after you made
+changes to the local files.
+
+Note: Be very careful on structural changes on the local filesystem as they might result in removing potentially large
+trees in the repository.
+
+### vlt integration
+The vault sync service can be used standalone or together with a vlt checkout. using the later, using the later
+initialization is easy as executing: `vlt sync` on the command line. the following sync related commands are available
+by vlt (as of version 2.3.22):
+
+    $ vlt sync --help
+    Usage:
+     sync -v|--force|-u <uri> <command> <localPath>
+
+    Description:
+      Allows to control the vault sync service. Without any arguments this command tries to put the current CWD under sync control. If executed within a vlt checkout, it uses the respective filter and host to configure the syncing. If executed outside of a vlt checkout, it registers synchronization only if the directory is empty.
+
+      Subcommands:
+        install      Installs the Vault Sync service on the remote server
+        status (st)  Display status information.
+        register     Register a new sync directory
+        unregister   Unregisters a sync directory
+
+      Most of the commands take an optional local path as argument which then specifies the sync directory. If the --uri is omitted it is auto-detected from the current vault checkout.
+
+      Note: the vault sync service creates a .vlt-sync-config.properties in the sync directory. See the inline comments for further options.
+
+      Examples:
+
+      Listing sync roots of a server:
+        vlt --credentials admin:admin sync --uri http://localhost:8080/crx status
+
+      Add the current CWD as sync directory:
+        vlt sync register
+
+    Options:
+      -v (--verbose)      verbose output
+      --force             force certain commands to execute.
+      -u (--uri) <uri>    Specifies the URI of the sync host.
+      <command>           Sync Command
+      <localPath>         local path (optional)
+
+### installing the service using vlt
+The vlt sync install command can be used to install the vault sync service bundle and configuration automatically.
+the bundle is installed below `/libs/system/vault/install` and the config node is created at
+`/libs/system/vault/org.apache.jackrabbit.vault.sync.impl.VaultSyncServiceImpl`. Initially the service is enabled but
+no sync roots are configured.
+
+Example:
+
+    $ vlt --credentials admin:admin sync --uri http://localhost:8080/crx install
+
+### displaying the service status
+The status command can be used to display information about the running sync service. Note that the status command does
+not fetch any live data from the service but rather reads the configuration at `/libs/system/vault/org.apache.jackrabbit.vault.sync.impl.VaultSyncServiceImpl`
+
+Example:
+
+    $ vlt sync status --uri http://localhost:4502/crx
+    Connecting via JCR remoting to http://localhost:4502/crx/server
+    Listing sync status for http://localhost:4502/crx/server/-/jcr:root
+    - Sync service is enabled.
+    - No sync directories configured.
+
+### adding/removing sync roots
+The register and unregister commands are used to add and remove sync roots from the configuration.
+
+Example (executed in a vlt checkout):
+
+    $ vlt sync register
+    Connecting via JCR remoting to http://localhost:4502/crx/server
+    Added new sync directory: /tmp/workspace/vltsync/jcr_root
+    $ vlt sync status
+    Connecting via JCR remoting to http://localhost:4502/crx/server
+    Listing sync status for http://localhost:4502/crx/server/-/jcr:root
+    - Sync service is enabled.
+    - syncing directory: /tmp/workspace/vltsync/jcr_root
+
+### Quick setup
+The most common task is probably installing the service and register the current vlt checkout as sync root. this can be
+done using the sync command without arguments.
+
+Example (executed in a vlt checkout):
+
+    $ vlt sync
+    Connecting via JCR remoting to http://localhost:4502/crx/server
+    Starting initialization of sync service in existing vlt checkout /tmp/workspace/vltsync/jcr_root for http://localhost:4502/crx/server/-/jcr:root
+    Preparing to install vault-sync-2.3.22.jar...
+    Updated bundle: vault-sync-2.3.22.jar
+    Created new config at /libs/crx/vault/config/com.day.jcr.sync.impl.VaultSyncServiceImpl
+    Added new sync directory: /tmp/workspace/vltsync/jcr_root
+
+The directory `/tmp/workspace/vltsync/jcr_root` is now enabled for syncing.
+You might perform a 'sync-once' by setting the
+appropriate flag in the `/tmp/workspace/vltsync/jcr_root/.vlt-sync-config.properties` file.
+

Added: jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/vault_api.png
URL: http://svn.apache.org/viewvc/jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/vault_api.png?rev=1582932&view=auto
==============================================================================
Files jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/vault_api.png (added) and jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/vault_api.png Sat Mar 29 01:08:41 2014 differ

Added: jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/vault_sample.png
URL: http://svn.apache.org/viewvc/jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/vault_sample.png?rev=1582932&view=auto
==============================================================================
Files jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/vault_sample.png (added) and jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/vault_sample.png Sat Mar 29 01:08:41 2014 differ

Added: jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/vaultfs.md
URL: http://svn.apache.org/viewvc/jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/vaultfs.md?rev=1582932&view=auto
==============================================================================
--- jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/vaultfs.md (added)
+++ jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/vaultfs.md Sat Mar 29 01:08:41 2014
@@ -0,0 +1,326 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+Vault FS
+========
+**NOTE**: Parts of the following documentation is outdated and needs review
+- - - 
+
+Introduction
+------------
+we see in various applications the need for a simple jcr repository to filesystem mapping. for example in source management tools, fileserver bindings, import/export stuff etc. if a jcr repository would only consist of `nt:file` and `nt:folder`, this would be easy. but if other nodetypes are used (even a simple as extending from `nt:file`) the mapping to the filesystem is not so trivial anymore. the idea is to provide a general all-purpose mechanism to export to and import from a standard (java.io based) filesystem.
+
+The VaultFs is designed to provide a general filesystem abstraction of a JCR repository. It provides the following features:
+
+intuitive mapping
+: A `nt:file` should just map to a simple file, a `nt:folder` to a directory. More complex node types should map to a `nodename.xml` and a possible `nodename` folder that contains the child nodes or be aggregated to a complete or partial serialization.
+
+universal api
+: the api should be suitable for all filesystem based applications like WebDAV, CIFS, SCM Integration, FileVault, etc.
+
+extendable
+: A plugin mechanism should allow to extend the mapping layer for further conversions filters and aggregators.
+
+Overview
+--------
+![VaultFS Overview](vaultfs.png)
+
+VaultFs consists mainly of 2 layers that map the repository's nodes to VaultFs files: The _Aggregate Node Tree_ that is managed by the _aggregate manager_ represents a hierarchical view of the content aggregates. Each aggregate is addressed by a path and allows access to its artifacts. The artifacts nodes are built using _aggregators_ that define which repository items belong to an aggregate and what artifacts they produce. For each artifact there is a _serializer_ defined that is used to export and import the respective content. 
+
+On top of the aggregate tree is the _Vault File System_ that accesses the aggregates and exposes them as tree of _vault files_. They can be used to export and import the actual repository content. The mapping from aggregates and its artifacts to vault files is done in an intuitive way so that clients (and users) can deal with them in a natural filesystem like fashion.
+
+![VaultFS Example](vault_sample.png)
+
+Aggregate Manager
+-----------------
+The aggregate manager is configured with a set of aggregators and serializers. Once the manager is mounted on a jcr repository it exposes a tree of aggregates. They are collected using an aggregator that matches the respective repository node. For example the _nt:file aggregator_ produces an artifacts node that allows no further child nodes and provides (usually) one primary artifact (which represents the content of the file).
+
+### Artifacts
+an artifact is one aspect or part of a content aggregation. the following artifact types exist:
+
+Directory Artifacts 
+: represent the folder aspect of an aggregate. For example a pure `nt:folder` would produce an aggregate with just one sole directory artifact.
+
+File Artifacts
+: represent file aggregates. since the `nt:file` handling is very special there is an special type for it.
+
+Primary Artifacts
+: represent the main aggregate. This usually contains all nodes and properties that belong to the aggregate that cannot be expressed by another type.
+
+Binary Artifacts 
+: represent binary content that is not included in the primary or file artifacts. This is for example suitable for binary properties that were not included in a xml deserialization. This allows keeping the deserializations leaner and more efficient.
+
+Content Aggregation
+-------------------
+A subtree of nodes will be aggregated semantically into one entity, the aggregate. This mainly consists of a path and a set of artifacts and may have child aggregates.
+
+the mechanism how content aggregation works is defined by a set of _filters_ with corresponding _aggregators_. if we look at the export in a recursive way, it would work as follows:
+
+1. traverse the repository starting at the root node
+2. for each node check which filter matches
+3. execute the respective aggregator and create a new aggregate
+4. if aggregator allows child nodes descend into the excluded nodes
+
+### Aggregates
+an aggregate is a tree of repository items that belong together and are mapped to (a set of) artifacts. the artifacts represent filesystem resources. the aggregate type is defined by the aggregator type and not primarily by the content. i.e. the selected aggregator must return stable coverage information which is not dependent of the actual content.
+
+there can be identified 4 types of aggregates.
+
+#### Full coverage aggregates
+they aggregate an entire subtree. for example the complete serialization of a `nt:nodeType` node or a _dialog definition_. they are very simple to deal with, since the root node of the aggregate is usually serialized into 1 filesystem file.
+
+The following repository structure:
+
+    + nodetypes [nt:unstructured]
+      + nt1 [nt:nodeType]
+        + jcr:propertyDefinition [nt:propertyDefinition]
+        + jcr:propertyDefinition [nt:propertyDefinition]
+        + jcr:childNodeDefinition [nt:childNodeDefinition]
+      + nt2 [nt:nodeType]
+        ...
+
+could be mapped to:
+
+    `- nodetypes
+       |- nt1.cnd
+       `- nt2.cnd
+
+#### Generic aggregates
+generic aggregates cover a part of a content subtree, hence they have not a full coverage. they always consist at least of a primary artifact and a directory artifact. examples of those are the aggregation of a `cq:Page` structure or of `nt:unstructured` nodes. 
+
+the following repository structure:
+
+    + en [cq:Page]
+      + jcr:content [cq:Content]
+      + about [cq:Page]
+        + jcr:content [cq:Content]
+          + header [cq:Content]
+            + image.jpg
+      + solutions [cq:Page
+        + jcr:content [cq:Content]
+
+are mapped to:
+
+    `- en
+       |- .content.xml
+       |- about
+       |  |- _jcr_content
+       |  |  `- header
+       |  |     `- image.jpg
+       |  `- .content.xml
+       `- solution
+          `- .content.xml
+
+the example above just excluded some direct child nodes of the aggregate root from the aggregation (with the exception of the `image.jpg` node). but this could be more complicated.
+
+overlapping example:
+
+    + apps [nt:unstructured]
+      + example [nt:unstructured]
+        + components [nt:unstructured]
+          + image [cq:Component]
+            + dialog [cq:Dialog]
+              ...  
+            + default.jsp [nt:file] 
+
+is be mapped to:
+
+    `- apps
+       |- .content.xml
+       `- example
+          |- .content.xml
+          `- components
+            |- .content.xml
+             `- image
+                |- .content.xml
+                |- dialog.xml
+                `- default.jsp
+
+this example has 6 aggregates:
+
+ 1. the generic aggregate for `apps`
+ 2. the generic aggregate for `example`
+ 3. the generic aggregate for `components`
+ 4. the generic aggregate for `image`
+ 5. the `default.jsp` file aggregate
+ 6. the `dialog.xml` full coverage aggregate
+
+#### Simple File aggregates
+since files (`nt:file` nodes and extents) are common they are treated differently in aggregation. the simplest mapping is to create a filesystem file for each `nt:file`. unfortunately there is some information in a default `nt:file` that cannot be preserved in the filesystem. namely:
+
+* `jcr:created` property
+* `jcr:content/jcr:uuid` property
+* `jcr:content/jcr:encoding` property
+* `jcr:content/jcr:mimeType` property
+
+so in order to achieve a complete serialization there is an extra artifact needed to store this info.
+but to keep the mapping lean, those properties are not part of the file aggregate but 'delegated' to its parent aggregate.
+
+example:
+
+    + foo [nt:folder]
+      + example.jsp [nt:file]
+        - jcr:created ...
+        + jcr:content [nt:resource]
+          - jcr:data
+          - jcr:lastModified
+          - jcr:mimeType
+
+is mapped to:
+
+    `- foo
+       |- .content.xml
+       `- example.jsp
+
+the `.content.xml` will include the properties that are not handled by the `example.jsp`
+
+#### Extended File aggregates
+when `nt:file` nodes are extended, either by primary or mixin type, the primary artifact remains the generic serialization of the resource. additional information needs to be serialized to an extra artifact.
+
+example:
+
+    + sample.jpg [dam:file]
+      - jcr:created
+      + jcr:content [dam:resource]
+        - jcr:lastModified
+        + dam:thumbnails [nt:folder]
+          - 90.jpg [nt:file]
+          - 120.jpg [nt:file]
+
+are be mapped to:
+
+    |- sample.jpg
+    `- sample.jpg.dir
+       |- .content.xml
+       `- _jcr_content
+          `- _dam_thumbnails
+             |- 90.jpg
+             `- 120.jpg
+
+#### Folder aggregates
+pure `nt:folder` aggregates will result in one directory and mostly in an additional `.content.xml`
+
+#### Binary Properties
+There is some special handling for binary properties other than `jcr:data` in a `jcr:content` node. 
+example (although this is probably very rare):
+
+    + foo [nt:unstructured]
+      + bar [nt:unstructured]
+        + 0001 [nt:unstructured]
+          - data1 (binary)
+          - data2 (binary)
+        + 0002 [nt:unstructured]
+          - data1 (binary)
+          - data2 (binary)
+
+is mapped to:
+
+    `- foo
+       |- .content.xml
+       `- bar
+          |- 0001
+          |  |- data1.bin
+          |  `- data2.bin
+          `- 0002
+             |- data1.bin
+             `- data2.bin      
+
+#### Resource Nodes
+there are some cases where `nt:resource` like structures are used that are not held below a `nt:file` node.
+
+    + foo [nt:unstructured]
+      + cq:content [nt:resource]
+        - jcr:mimeType "image/jpg"
+        - jcr:data  
+        - jcr:lastModified
+
+this is mapped to:
+
+    `- foo
+       |- .content.xml
+       `- _cq_content.jpg
+
+where as the mimetype and modification date can be recorded in the primary artifact. possible other properties like `jcr:uuid` etc would go to the parent aggregate.
+
+#### Filename escaping
+not all of the character in a jcr name are allowed filesystem characters and need escaping. the normal case is to use the _url encoding_, i.e. using a `%` followed by the hexnumber of the character. but this look ugly, especially for the colon `:`, eg a `cq:content` would become `cq%3acontent`. so for the namespace prefix there is a special escaping by replacing it by a underscores. eg: `cq:content` will be `_cq_content`. nodes already having this patter will be escaped using a double underscore. eg: `_test_image.jpg` would be `__test_image.jpg`.
+
+more examples:
+
+| node name | file name |
+|---------------------|-------------------------------|
+| `test.jpg`          | `test.jpg`                    |
+| `cq:content`        | `_cq_content`                 |
+| `test_image.jpg`    | `test_image.jpg`              |
+| `_testimage.jpg`    | `_testimage.jpg`              |
+| `_test_image.jpg`   | `__test_image.jpg`            |
+| `cq:test:image.jpg` | `_cq_test%3aimage.jpg` <sup>1</sup> |
+
+<sup>1</sup> this is a very rare case and justifies the ugly `%3a` escaping.
+
+Serialization
+-------------
+The serialization of the artifacts is defined by the =serializer= that is provided by the aggregator. Currently there are only 3 kind of serializations used: a direct data serialization for the contents of file or binary artifacts, a _CND_ serialized for `nt:nodeType` nodes and an enhanced _docview_ serialization for the rest. The _docview_ serialization that is used allows multi value properties (and might be enhanced by a better property type support).
+
+Deserialization
+---------------
+Although for exporting only 3 serialization types are used this is a bit different for importing. The importer analyzes the provided input sources and determines the following serialization types:
+
+* generic XML
+* docview XML
+* sysview XML
+* generic data
+
+Depending on the configuration those input sources can be handled differently. currently they are imported as follows:
+
+**generic XML** produces a `nt:file` having a `jcr:content` of the deserialization of the xml document (if importing into CRX then the `crx:XmlDocument` nodetypes and friends are used).
+
+**docview XML** is more or less imported directly below the respective import root.
+
+**sysview XML** is more or less imported directly below the respective import root.
+
+**generic data** produces a `nt:file` having the data as `nt:resource` content.
+
+Vault File System Layer
+-----------------------
+The VaultFs layer provides a mapping from the aggregate tree to a file system. The goal is to keep the amount of files lean and as natural as possible with a minimum amount of extra files. 
+
+Terminology
+-----------
+
+VaultFs
+: The File Vault Filesystem. Provides file-like abstraction of a JCR repository.
+
+VaultFile
+: A VaultFs entity that represents a file-like abstraction of a (partial) repository node tree.
+
+Aggregate
+: Represents an addressable collection of artifacts.
+
+Aggregator
+: Interface that defines the methods for building content aggregates.
+
+Serializer
+: Interface that defines the methods for serializing an artifact. 
+ 
+Artifact handler
+: Interface that defines methods for deserializing artifacts.
+
+Artifact
+: Representation of a content aggregate. An aggregator can provide several artifacts. 
+  An artifact is either mapped to a file or a directory and can be of the 
+  type: **primary**, **file**, **binary** or **directory**
+

Added: jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/vaultfs.png
URL: http://svn.apache.org/viewvc/jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/vaultfs.png?rev=1582932&view=auto
==============================================================================
Files jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/vaultfs.png (added) and jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/vaultfs.png Sat Mar 29 01:08:41 2014 differ

Added: jackrabbit/commons/filevault/trunk/vault-doc/src/site/resources/css/site.css
URL: http://svn.apache.org/viewvc/jackrabbit/commons/filevault/trunk/vault-doc/src/site/resources/css/site.css?rev=1582932&view=auto
==============================================================================
--- jackrabbit/commons/filevault/trunk/vault-doc/src/site/resources/css/site.css (added)
+++ jackrabbit/commons/filevault/trunk/vault-doc/src/site/resources/css/site.css Sat Mar 29 01:08:41 2014
@@ -0,0 +1,25 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+tt {
+    white-space: nowrap;
+    border: 1px solid #eaeaea;
+    background-color: #f5f5f5;
+}
+pre {
+    font-size: 12px;
+}
+

Added: jackrabbit/commons/filevault/trunk/vault-doc/src/site/site.xml
URL: http://svn.apache.org/viewvc/jackrabbit/commons/filevault/trunk/vault-doc/src/site/site.xml?rev=1582932&view=auto
==============================================================================
--- jackrabbit/commons/filevault/trunk/vault-doc/src/site/site.xml (added)
+++ jackrabbit/commons/filevault/trunk/vault-doc/src/site/site.xml Sat Mar 29 01:08:41 2014
@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+  -->
+
+<project xmlns="http://maven.apache.org/DECORATION/1.3.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/DECORATION/1.3.0 http://maven.apache.org/xsd/decoration-1.3.0.xsd"
+         name="Jackrabbit Filevault">
+  <body>
+    <menu name="Overview">
+      <item href="index.html" name="Jackrabbit Filevault" />
+      <item href="license.html" name="License" />
+    </menu>
+    <menu name="Concepts and architecture">
+      <item href="overview.html" name="Overview" />
+      <item href="vaultfs.html" name="Vault FS" />
+    </menu>
+    <menu name="Using Filevault">
+      <item href="usage.html" name="Getting Started" />
+      <item href="filter.html" name="Workspace Filter" />
+    </menu>
+    <menu name="Developing">
+      <item href="apidocs/index.html" name="API docs" />
+    </menu>
+    <menu name="Links">
+      <item href="http://jackrabbit.apache.org/" name="Apache Jackrabbit" />
+    </menu>
+  </body>
+
+  <skin>
+    <groupId>org.apache.maven.skins</groupId>
+    <artifactId>maven-fluido-skin</artifactId>
+    <version>1.3.0</version>
+  </skin>
+
+  <custom>
+    <fluidoSkin>
+      <sourceLineNumbersEnabled>true</sourceLineNumbersEnabled>
+      <topBarEnabled>true</topBarEnabled>
+      <sideBarEnabled>true</sideBarEnabled>
+      <gitHub>
+        <projectId>apache/jackrabbit-filevault</projectId>
+        <ribbonOrientation>right</ribbonOrientation>
+      </gitHub>
+      <ohloh>
+        <projectId>jackrabbit-filevault</projectId>
+      </ohloh>
+      <googlePlusOne />
+    </fluidoSkin>
+  </custom>
+</project>



Mime
View raw message