jackrabbit-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From k...@apache.org
Subject svn commit: r1865905 - /jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/filter.md
Date Mon, 26 Aug 2019 07:14:51 GMT
Author: kwin
Date: Mon Aug 26 07:14:51 2019
New Revision: 1865905

URL: http://svn.apache.org/viewvc?rev=1865905&view=rev
Log:
JCRVLT-120 document property filters

extend information about import/installation

Modified:
    jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/filter.md

Modified: 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=1865905&r1=1865904&r2=1865905&view=diff
==============================================================================
--- jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/filter.md (original)
+++ jackrabbit/commons/filevault/trunk/vault-doc/src/site/markdown/filter.md Mon Aug 26 07:14:51
2019
@@ -37,7 +37,7 @@ Example:
         <filter root="/etc/map" mode="merge" />
     </workspaceFilter>
 
-### filter elements
+### 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.
 
@@ -56,14 +56,14 @@ importing content. the following values
 
 For a more detailed description of the import mode, see [here](importmode.html)
 
-### 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
+### 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][api.Pattern]. The regexp
is matched against the full _path_ of the
+respective or potential JCR node, so it either must start with `/` (absolute regex) or a
wildcard (relative regex).
+
+#### 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.
 
@@ -79,11 +79,22 @@ The following example includes _all_ nod
         <exclude pattern=".*\.gif"/>
     </filter>
 
-Usage for export
+#### Property Filtering
+
+Since FileVault 3.1.28 ([JCRVLT-120](https://issues.apache.org/jira/browse/JCRVLT-120)) it
is not only possible to filter on node level but also only include/exclude certain properties
below a certain node by setting the attribute `matchProperties` on the `exlude`/`include`
element to `true`. 
+
+	<filter root="/tmp">
+        <exclude pattern="/tmp/property1" matchProperties="true"/>
+    </filter>
+
+Then the `pattern` is matched against property paths instead of node paths.
+If the attribute `matchProperties` is not set all properties below the given node paths are
included/excluded. Otherwise the excluded properties are not contained in the exported package
and during import not touched in the repository.
+
+
+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.
+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:
 
@@ -101,7 +112,70 @@ There is one exception, if **all** the p
 2. traverse **all** child nodes recursively
 3. if the path of the child node matches the regexp, include it in the export
 
+Usage for Import/Installation
+-------------------
+When importing (i.e. installing) content packages into a repository  the workspace filter
defines which nodes are deserialized and overwritten in the repository.
+Nodes/Properties being covered by some filter rules but not contained in the to be imported
content are **removed** from the repository.
+
+The exact rules are outlined below
+
+Item covered by filter rule | Item contained in the Content Package | Item contained in the
Repository (prior to Import/Installation) | State of Item in Repository after Import/Installation
+--- | --- | --- | ---
+no | yes | yes | not touched
+no | no | yes | not touched
+no | yes | no | deserialized from content package (for backwards compatibility reasons),
this should not be used, i.e. all items in the content package should always be covered by
some filter rule
+no | no | no | not existing (not touched)
+yes | yes | yes | overwritten
+yes | no | yes | removed
+yes | yes | no | deserialized from content package
+yes | no | no | not existing
+
+### Example
+
+Content Package Filter
+
+```
+<filter root="/tmp">
+    <include pattern="/tmp/a(/.*)?"/>
+    <include pattern="/tmp/b(/.*)?/>
+    <exclude pattern="/tmp/b/property1" matchProperties="true"/>
+    <include pattern="/tmp/c(/.*)?"/>
+</filter>
+```
+
+Content Package Serialized Content
+
+```
++ /jcr_root/
+  + tmp/
+  	 + a/
+  	   - property1="new"
+  	 + b/
+  	   - property1="new"
+  	   - property2="new"
+```
+
+#### Repository State Before Installation/Import
+```
++ /tmp/
+  + b/
+    - property1="old"
+    - property2="old"
+  + c/
+    - property1="old"
+```
+
+#### Repository State After Installation/Import
+```
++ /tmp/
+  + a/
+    - property1="new"
+  + b/
+    - property1="old"
+    - property2="new"
+```
 
 <!-- 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
+[api.ImportMode]: apidocs/org/apache/jackrabbit/vault/fs/api/ImportMode.html
+[api.Pattern]: https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html
\ No newline at end of file



Mime
View raw message