From 13b048eeef5f990906f2e96d0435a2fa20765c59 Mon Sep 17 00:00:00 2001 From: Konrad Windszus Date: Fri, 20 Dec 2024 12:13:30 +0100 Subject: [PATCH] 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 +++- .../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 02339d096..3837cafc1 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 thought for nodes which are supposed to be removed during package installation (i.e. nodes which are not contained in any serialization files/folders). diff --git a/src/site/markdown/importmode.md b/src/site/markdown/importmode.md index f00c87978..3879fe5ef 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 repository, the importer keeps track of the remapping and calculates the filters accordingly. -**`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 f06ec2385..b006a01eb 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 f0122147a..f347c9aa9 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 @@ private void readDef(Element elem) throws ConfigurationException { 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");