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 2021/01/18 11:21:08 UTC
[jackrabbit-filevault] 01/01: JCRVLT-493 document package types
This is an automated email from the ASF dual-hosted git repository.
kwin pushed a commit to branch feature/packagetypes
in repository https://gitbox.apache.org/repos/asf/jackrabbit-filevault.git
commit b3c2c13123375fbc2519f7b421dd1a88b3a40f3f
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Mon Jan 18 12:20:51 2021 +0100
JCRVLT-493 document package types
---
vault-doc/src/site/markdown/packagetypes.md | 66 +++++++++++++++++++++++++++++
vault-doc/src/site/markdown/properties.md | 2 +-
vault-doc/src/site/markdown/validation.md | 2 +-
vault-doc/src/site/site.xml | 4 +-
4 files changed, 71 insertions(+), 3 deletions(-)
diff --git a/vault-doc/src/site/markdown/packagetypes.md b/vault-doc/src/site/markdown/packagetypes.md
new file mode 100644
index 0000000..8aa9f62
--- /dev/null
+++ b/vault-doc/src/site/markdown/packagetypes.md
@@ -0,0 +1,66 @@
+<!--
+ 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.
+-->
+
+Package Types
+================
+
+Overview
+------
+Package types limit what repository locations a content package may contain ([JCRVLT-170](https://issues.apache.org/jira/browse/JCRVLT-170)). In addition they may impose other limitations in terms of install hooks, package dependencies and allowed filter rules.
+The package type classification helps to clarify the purpose and also the deployment of the package (e.g. when using the [Oak Composite Node Store](https://jackrabbit.apache.org/oak/docs/nodestore/compositens.html), which mounts several repository folders in read-only mode).
+The package type is set in the [package properties](properties.html).
+
+Package types are not enforced in any way (yet) when importing packages. Currently they are only enforced by the [jackrabbit-packagetype validator][validators] and to a certain degree by third party tools like [Apache Sling Content-Package to Feature Model Converter](https://github.com/apache/sling-org-apache-sling-feature-cpconverter).
+
+Restrictions
+--------
+
+Package Type | Allowed repository locations | Allows OSGi bundles/configurations/sub packages | Allows package dependencies | Allows [install hooks](installhooks.html)
+--- | --- | --- | --- | ---
+Application | `/apps`, `/libs` | no | yes | no
+Content | everything except `/apps`, `/libs` | partially (only `content` sub packages) | yes | yes
+Container | no regular content | yes | no | yes
+Mixed | all | yes | yes | yes
+
+Application Package
+----------
+
+This package type is supposed to be used for everything which makes up the "code" part of the application which is used directly from the repository, i.e. (non-bundled) scripts, resource types, ...
+To ease combination of multiple application packages they should contain only disjunct sub trees (i.e. no include/exclude filter patterns). As this [cannot always be achieved in reality](https://issues.apache.org/jira/browse/JCRVLT-403) this rule can be relaxed with the [validator setting `allowComplexFilterRulesInApplicationPackages`][validators].
+In addition they must not contain [install hooks](installhooks.html).
+
+Content Package
+----------
+
+This package must not contain any nodes below `/apps` or `/libs`. Sub packages of type `content` are allowed (but only below `/etc/packages`). All other sub package types are not valid in this type.
+
+
+Container Package
+---------
+
+Container packages act as deployment vehicle and don't contain regular nodes. Only OSGi bundles, configuration and sub packages (for use with the [OSGi Installer](https://sling.apache.org/documentation/bundles/jcr-installer-provider.html)) are allowed. In addition also sub packages below `/etc/packages/...` are supported.
+
+Containers may be nested which means they may contain itself packages of type `container`.
+
+
+Mixed Package
+-------
+
+This legacy package type imposes no restrictions and is only defined for backwards-compatibility reasons. For new packages rather one of the other types should be used as mixed packages may not deployable in certain scenarios.
+
+
+[validators]: validation.html#Standard_Validators
\ No newline at end of file
diff --git a/vault-doc/src/site/markdown/properties.md b/vault-doc/src/site/markdown/properties.md
index 95f2b6d..2200287 100644
--- a/vault-doc/src/site/markdown/properties.md
+++ b/vault-doc/src/site/markdown/properties.md
@@ -77,7 +77,7 @@ Example:
| noIntermediateSaves | If set to `true` indicates no intermediate saves should be performed while installing this package | no | `false`
| subPackageHandling | see [SubPackageHandling][api.SubPackageHandling] | no | `*;install`
| useBinaryReferences | If set to `true` indicates that binary references should be used instead of the actual binary | no | `false`
-| packageType | Possible values: <ul><li>`application`: An application package consists purely of application content. It serializes entire subtrees with no inclusion or exclusion filters. it does not contain any subpackages nor OSGi configuration or bundles.</li><li>`content`: A content package consists only of content and user defined configuration. It usually serializes entire subtrees but can contain inclusion or exclusion filters. it does not contain any subpackages nor OSGi configu [...]
+| packageType | Possible values: `application`, `content`, `container` or `mixed`. Further details at [Package Types](packagetypes.html). | no | ?
| installhook.\<name\>.class | The FQN of the class which acts as an [install hook](installhooks.html). The `<name>` can be an arbitrary string (but must not contain a dot). | no | n/a
| packageFormatVersion | The version of this package as integer value. Versions newer than 2 are not yet supported during installation. | no | 2
| allowIndexDefinitions | If set to `true` indicates that the package contains an [Oak Index Definition](https://jackrabbit.apache.org/oak/docs/query/indexing.html#index-defnitions). Otherwise the package is not supposed to contain an index definition. This may be important to know prior to installation as installing/updating an index definition might have a severe performance impact especially on large repositories| no | false
diff --git a/vault-doc/src/site/markdown/validation.md b/vault-doc/src/site/markdown/validation.md
index fce8950..d4df525 100644
--- a/vault-doc/src/site/markdown/validation.md
+++ b/vault-doc/src/site/markdown/validation.md
@@ -54,7 +54,7 @@ ID | Description | Options
`jackrabbit-emptyelements` | Check for empty elements within DocView files (used for ordering purposes, compare with [(extended) Document View Format](docview.html)) which are included in the filter with import=replace as those are actually not replaced! | none
`jackrabbit-mergelimitations` | Checks for the limitation of import mode=merge outlined at [JCRVLT-255][jcrvlt-255]. | none
`jackrabbit-oakindex` | Checks if the package (potentially) modifies/creates an OakIndexDefinition. This is done by evaluating both the filter.xml for potential matches as well as the actual content for nodes with jcr:primaryType `oak:indexDefinition`. | none
-`jackrabbit-packagetype` | Checks if the package type is correctly set for this package, i.e. is compliant with all rules outlined at [JCRVLT-170][jcrvlt-170]. | *jcrInstallerNodePathRegex*: the regex of the node paths which all OSGi bundles and configurations within packages must match ([JCR Installer](https://sling.apache.org/documentation/bundles/jcr-installer-provider.html)) (default=`/([^/]*/){0,4}?(install|config)(\\.[^/]*)*/(\\d{1,3}/)?.+?\\.`).<br/>*additionalJcrInstallerFileNode [...]
+`jackrabbit-packagetype` | Checks if the package type is correctly set for this package, i.e. is compliant with all rules outlined at [Package Types](packagetypes.html). | *jcrInstallerNodePathRegex*: the regex of the node paths which all OSGi bundles and configurations within packages must match ([JCR Installer](https://sling.apache.org/documentation/bundles/jcr-installer-provider.html)) (default=`/([^/]*/){0,4}?(install|config)(\\.[^/]*)*/(\\d{1,3}/)?.+?\\.`).<br/>*additionalJcrInstall [...]
`jackrabbit-nodetypes` | Checks if all non empty elements within [DocView files](docview.html) have the mandatory property `jcr:primaryType` set and follow the [node type definition of their given type](https://jackrabbit.apache.org/jcr/node-types.html). | *cnds*: A URI pointing to one or multiple [CNDs](https://jackrabbit.apache.org/jcr/node-type-notation.html) (separated by `,`) which define the additional namespaces and nodetypes used apart from the [default ones defined in JCR 2.0](h [...]
`jackrabbit-accesscontrol` | Checks that [access control list nodes (primary type `rep:ACL`, `rep:CugPolicy` and `rep:PrincipalPolicy`)](https://jackrabbit.apache.org/oak/docs/security/accesscontrol/default.html#Representation_in_the_Repository) are only used when the [package property's](./properties.html) `acHandling` is set to something but `ignore` or `clear`. | none
diff --git a/vault-doc/src/site/site.xml b/vault-doc/src/site/site.xml
index 65acf97..9f4827d 100644
--- a/vault-doc/src/site/site.xml
+++ b/vault-doc/src/site/site.xml
@@ -37,7 +37,9 @@
<item href="filter.html" name="Workspace Filter">
<item href="importmode.html" name="Import Mode" />
</item>
- <item href="properties.html" name="Package Properties"/>
+ <item href="properties.html" name="Package Properties">
+ <item href="packagetypes.html" name="Package Types" />
+ </item>
<item href="config.html" name="Vault FS Configuration"/>
<item href="settings.html" name="Settings"/>
<item href="nodetypes.html" name="Nodetypes"/>