[jackrabbit-filevault] branch master updated: Document package definition

[kw...@apache.org]

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 fe28f29c Document package definition
fe28f29c is described below

commit fe28f29cb8c793ec32ace8ebc5c4520a5d8cd42a
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Tue May 24 15:56:01 2022 +0200

    Document package definition
---
 src/site/markdown/metadata.md          |  4 +--
 src/site/markdown/packagedefinition.md | 50 ++++++++++++++++++++++++++++++++++
 2 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/src/site/markdown/metadata.md b/src/site/markdown/metadata.md
index 418edbb4..af666483 100644
--- a/src/site/markdown/metadata.md
+++ b/src/site/markdown/metadata.md
@@ -28,5 +28,5 @@ This is
 * [Settings (settings.xml)](settings.html), optional
 * [Nodetypes (*.cnd)](nodetypes.html), optional
 * [Privileges (privileges.xml)](privileges.html), optional
-* [Install Hooks](installhooks.html), optional
-* Package Definition (definition/.content.xml), TODO, optional
\ No newline at end of file
+* [Package Definition (definition/.content.xml)](packagedefinition.html), optional
+* [Install Hooks](installhooks.html), optional
\ No newline at end of file
diff --git a/src/site/markdown/packagedefinition.md b/src/site/markdown/packagedefinition.md
new file mode 100644
index 00000000..1765373a
--- /dev/null
+++ b/src/site/markdown/packagedefinition.md
@@ -0,0 +1,50 @@
+<!--
+   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 Definition
+===========
+
+Packages may *optionally* contain a serialized JCR node of type `vlt:PackageDefinition` at `META-INF/vault/definition/.content.xml`. Its format follows the [FileVault DocView serialization](docview.html). It is automatically deserialized to `/etc/packages/<group>/<name>-<version>.zip/jcr:content/vlt:definition` during package upload when the JCR based package manager is being used.
+
+The node type `vlt:PackageDefinition` is defined as 
+
+```
+[vlt:PackageDefinition] > nt:unstructured
+  orderable
+  - artifactId (string)
+  - jcr:created (date)
+  - jcr:createdBy (string)
+  - jcr:lastModified (date)
+  - lastUnpackedBy (string)
+  - jcr:description (string)
+  - groupId (string)
+  - lastUnpacked (date)
+  - version (string)
+  - jcr:lastModifiedBy (string)
+  - dependencies (string) multiple
+  + thumbnail (nt:base) = nt:unstructured
+  + filter (nt:base) = nt:unstructured
+```
+
+Due to it extending `nt:unstructured` it allows arbitrary properties and child nodes in addition to the explicitly defined ones.
+
+This node contains primarily the most important package properties and the package filter rules and in addition may carry additional *implementation specific properties*.
+Most of the properties are automatically (over)written during package upload with values coming from the [package properties](properties.html) (details at [JcrPackageDefinitionImpl.unwrap(..)](https://github.com/apache/jackrabbit-filevault/blob/39b4463904719a423a3ebe000b049b0653557591/vault-core/src/main/java/org/apache/jackrabbit/vault/packaging/impl/JcrPackageDefinitionImpl.java#L227)).
+
+The primary use case is easy access of the most important package meta data after upload to the JCR-based package manager (without doing extraction and parsing of the underlying archive). As the node may also contain other implementation-specific properties for some cases it may be useful to also include that serialized node in the package itself. 
+
+As most properties are redundant and automatically (over)written during package upload with values coming from the [package properties](properties.html) or the [filter](filter.html) only non-redundant properties should be included in the serialized node inside the content package package itself (details at [JcrPackageDefinitionImpl.unwrap(..)](https://github.com/apache/jackrabbit-filevault/blob/39b4463904719a423a3ebe000b049b0653557591/vault-core/src/main/java/org/apache/jackrabbit/vault/ [...]