You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jackrabbit.apache.org by kw...@apache.org on 2025/01/03 15:41:02 UTC

(jackrabbit-filevault) branch master updated: JCRVLT-788 improve exception message for invalid import modes

This is an automated email from the ASF dual-hosted git repository.

kwin pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/jackrabbit-filevault.git


The following commit(s) were added to refs/heads/master by this push:
     new a2629fd3 JCRVLT-788 improve exception message for invalid import modes
a2629fd3 is described below

commit a2629fd3a24d35f31f0168bd6b8982db6ac62c8b
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Fri Dec 20 12:13:30 2024 +0100

    JCRVLT-788 improve exception message for invalid import modes
    
    Clarify documentation of import modes/package properties to explicitly
    mention lowercase values.
---
 src/site/markdown/filter.md                                    |  2 +-
 src/site/markdown/importmode.md                                | 10 +++++-----
 src/site/markdown/properties.md                                |  4 +++-
 .../jackrabbit/vault/fs/config/DefaultWorkspaceFilter.java     |  2 +-
 4 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/src/site/markdown/filter.md b/src/site/markdown/filter.md
index 02339d09..3837cafc 100644
--- a/src/site/markdown/filter.md
+++ b/src/site/markdown/filter.md
@@ -53,7 +53,7 @@ importing content. The following values are possible:
 1. `update` : Existing content is updated, new content is added and none is deleted. Deprecated, as not handled consistently, use `update_properties` instead.
 1. `update_properties`: Existing content is updated, new content is added and none is deleted.
 
-For a more detailed description of the import mode, see [here](importmode.html).
+For a more detailed description of the import mode, see [here](importmode.html). Note that all values must be given in **lowercase letters** (despite the underlying Java enum type using uppercase letters).
 
 In addition it is possible to influence the auto-detection of the package type (if not explicitly specified in the `properties.xml`) with the attribute `type`. The only supported value as of now is `cleanup` which means that the filter rule is ignored for the auto-detection of the package type ([JCRVLT-220](https://issues.apache.org/jira/browse/JCRVLT-220)) as well as ignored for [validation of orphaned filter entries](validation.html) with the `jackrabbit-filter` validator. This is thou [...]
 
diff --git a/src/site/markdown/importmode.md b/src/site/markdown/importmode.md
index f00c8797..3879fe5e 100644
--- a/src/site/markdown/importmode.md
+++ b/src/site/markdown/importmode.md
@@ -17,7 +17,7 @@
 
 Import Mode
 ===========
-The import mode defines how imported content affects existing content in the repository. It is controlled by the [ImportMode][api.ImportMode] set in the [Workspace Filter](filter.html) and defaults to `REPLACE`. 
+The import mode defines how imported content affects existing content in the repository. It is controlled by the [ImportMode][api.ImportMode] set in the [Workspace Filter](filter.html) and defaults to `replace`. The import mode is supposed to be given in **lowercase letters** (in contrast to the actual enum values outlined in the javadoc).
 
 Details on how node ids are treated during import are outlined at [Referenceable Nodes](referenceablenodes.html)
 
@@ -25,7 +25,7 @@ Details on how node ids are treated during import are outlined at [Referenceable
 
 Regular content
 ----------------
-The import mode handling is inconsistent and has many edge cases for the mode `MERGE` and `UPDATE`. Therefore FileVault 3.5.0 introduces the new modes `MERGE_PROPERTIES` and `UPDATE_PROPERTIES` (in [JCRVLT-255][JCRVLT-255]) which behave much more predicatable. The details are outlined at the [JavaDoc][api.ImportMode].
+The import mode handling is inconsistent and has many edge cases for the mode `merge` and `update`. Therefore FileVault 3.5.0 introduces the new modes `merge_properties` and `update_properties` (in [JCRVLT-255][JCRVLT-255]) which behave much more predictable. The details are outlined at the [JavaDoc][api.ImportMode].
 
 Access control list
 ----------------------------------------------------
@@ -36,7 +36,7 @@ Authorizables
 ----------------------------------------------------
 If an authorizable with the same name already exists, the active `ImportMode` controls how the existing authorizables are affected:
 
-**`ImportMode.REPLACE`**
+**`replace`**
 : Replaces the authorizable node completely with the content in the package. The importer effectively deletes and re-creates the authorizable at the path specified in the package (internally the content is imported using the content handler with `IMPORT_UUID_COLLISION_REMOVE_EXISTING`). Note that any sub-nodes of the authorizable are treated like normal content and obey the normal filter rules. so the following filter should only replace the users's node, but not its sub nodes:
 
 ````
@@ -46,11 +46,11 @@ If an authorizable with the same name already exists, the active `ImportMode` co
 ````
 
 
-**`ImportMode.UPDATE`,`ImportMode.UPDATE_PROPERTIES`**
+**`update`,`update_properties`**
 : Replaces the authorizable node completely with the content in the package **in place**. The importer effectively deletes and re-creates the authorizable at the path specified in the package (internally the content is imported using the content handler with `IMPORT_UUID_COLLISION_REPLACE_EXISTING`). Note that any sub-nodes of the authorizable are treated like normal content and obey the normal filter rules. However, if the authorizable existed at a different path as specified in the rep [...]
 
 
-**`ImportMode.MERGE`,`ImportMode.MERGE_PROPERTIES`**
+**`merge`,`merge_properties`**
 : Has no effect if the authorizable already existed except for group memberships (see below). Note that any sub-nodes of the authorizable are treated like normal content and obey the normal filter rules. However, if the authorizable existed at a different path as specified in the repository, the importer keeps track of the remapping and calculates the filters accordingly.
 
 ### Merging Group Members
diff --git a/src/site/markdown/properties.md b/src/site/markdown/properties.md
index f06ec238..b006a01e 100644
--- a/src/site/markdown/properties.md
+++ b/src/site/markdown/properties.md
@@ -72,7 +72,7 @@ Example:
 | generator | Information about the generator of the package | no | for packages created by filevault: `org.apache.jackrabbit.vault:version`
 | lastWrapped | A date string in the format `±YYYY-MM-DDThh:mm:ss.SSSTZD` specifying when the package has been last wrapped (i.e. rebuilt) (see also [ISO8601][api.ISO8601]) | no | empty
 | lastWrappedBy | A user name indicating who last modified this package | no | empty
-| acHandling | See [AccessControlHandling][api.AccessControlHandling]. | no | ignore
+| acHandling | See [AccessControlHandling][api.AccessControlHandling]. Values must be given in lowercase letters. | no | ignore
 | cndPattern | A [Java regular expression pattern](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) which specifies where to look for CND files within the given package (in addition to all `*.cnd` files below `META-INF/vault`) | no | `^/(apps|libs)/([^/]+/){1,2}nodetypes/.+\\.cnd$`
 | requiresRoot | If set to `true` indicates that only admin sessions can install this package | no | `false`
 | requiresRestart | If set to `true` indicates that the system should be restarted after this package has been installed | no | `false`
@@ -87,6 +87,8 @@ Example:
 | artifactId | The Maven artifactId of the underlying Maven module from which this package was built. Only set if built via the [FileVault Package Maven Plugin](https://jackrabbit.apache.org/filevault-package-maven-plugin/index.html) | no | n/a
 | vault.feature.stashPrincipalPolicies | If set to `true` will always restore existing principal policies after installing a package with `AccessControlHandling` being set to anything but `CLEAR` or `OVERWRITE`. Only evaluated since 3.8.10 ([JCRVLT-683](https://issues.apache.org/jira/browse/JCRVLT-683)). | no | The system property `vault.feature.stashPrincipalPolicies` is used as default. This is described with its default value at [Configuration](config.html).
 
+All values of enum types (`acHandling`, `packageType`) are always in lowercase letters.
+
 Manifest File
 ---------------
 
diff --git a/vault-core/src/main/java/org/apache/jackrabbit/vault/fs/config/DefaultWorkspaceFilter.java b/vault-core/src/main/java/org/apache/jackrabbit/vault/fs/config/DefaultWorkspaceFilter.java
index f0122147..f347c9aa 100644
--- a/vault-core/src/main/java/org/apache/jackrabbit/vault/fs/config/DefaultWorkspaceFilter.java
+++ b/vault-core/src/main/java/org/apache/jackrabbit/vault/fs/config/DefaultWorkspaceFilter.java
@@ -430,7 +430,7 @@ public class DefaultWorkspaceFilter implements Dumpable, WorkspaceFilter {
                 propFilters.setImportMode(importMode);
                 bothFilters.setImportMode(importMode);
             } catch (IllegalArgumentException e) {
-                throw new ConfigurationException("Invalid value given for attribute 'mode'", e);
+                throw new ConfigurationException("Invalid value given for attribute 'mode': '" + mode + "'", e);
             }
         }
         String type = elem.getAttribute("type");