[jackrabbit-filevault] 01/01: JCRVLT-492 document install hooks

[kw...@apache.org]

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

kwin pushed a commit to branch feature/JCRVLT-492-installhook-documentation
in repository https://gitbox.apache.org/repos/asf/jackrabbit-filevault.git

commit a9a4404e92fecdd6a93d8fb53e86ba10fd9b134b
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Thu Jan 14 13:49:58 2021 +0100

    JCRVLT-492 document install hooks
---
 vault-doc/src/site/markdown/installhooks.md | 30 +++++++++++++++++++++++++++++
 vault-doc/src/site/markdown/metadata.md     |  1 +
 vault-doc/src/site/markdown/properties.md   |  2 +-
 vault-doc/src/site/site.xml                 |  1 +
 4 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/vault-doc/src/site/markdown/installhooks.md b/vault-doc/src/site/markdown/installhooks.md
new file mode 100644
index 0000000..5387aae
--- /dev/null
+++ b/vault-doc/src/site/markdown/installhooks.md
@@ -0,0 +1,30 @@
+Content Package Install Hooks
+================
+
+Overview
+------
+Hooks are just Java classes which are called during package installation. One can use them to execute arbitrary operations automatically on certain stages during package import.
+
+Install hooks must implement [`org.apache.jackrabbit.vault.packaging.InstallHook`][api.InstallHook].
+
+
+Internal Hooks
+------
+The internal hooks have to be packaged as JARs and placed in `META-INF/vault/hooks` within the content package. The JAR needs to have a [`Main-Class` attribute in its manifest](https://docs.oracle.com/javase/8/docs/technotes/guides/jar/jar.html#Main_Attributes) pointing to the hook class. 
+
+
+External Hooks
+-----
+External hooks are loaded through the class loader by their fully qualified class name. The class name is given in the [package property](properties.html) `installhook.<name>.class` where name is an arbitrary string (without a dot).
+
+The following class loaders are used by default to load the given class:
+
+1. The class loader which loaded the InstallHookProcessorImpl class (in OSGi context this is the bundle classloader of the FileVault bundle)
+2. The ThreadContext class loader of the current thread.
+
+The class loader can be overridden by calling [`ImportOptions.setHookClassLoader(...)`][api.ImportOptions] and pass the import options then to the package importer.
+
+You must make sure that the external hook class is accessible from the used class loader.
+
+[api.InstallHook]: apidocs/org/apache/jackrabbit/vault/packaging/InstallHook.html
+[api.ImportOptions]: apidocs/org/apache/jackrabbit/vault/fs/io/ImportOptions.html
\ No newline at end of file
diff --git a/vault-doc/src/site/markdown/metadata.md b/vault-doc/src/site/markdown/metadata.md
index ba916a1..418edbb 100644
--- a/vault-doc/src/site/markdown/metadata.md
+++ b/vault-doc/src/site/markdown/metadata.md
@@ -28,4 +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
diff --git a/vault-doc/src/site/markdown/properties.md b/vault-doc/src/site/markdown/properties.md
index fc95ece..95f2b6d 100644
--- a/vault-doc/src/site/markdown/properties.md
+++ b/vault-doc/src/site/markdown/properties.md
@@ -78,7 +78,7 @@ Example:
 | 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 [...]
-| installhook.* | The FQN of the class which acts as an InstallHook (code being executed while this package is being installed) | no | n/a
+| 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
 | groupId | The Maven groupId 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
diff --git a/vault-doc/src/site/site.xml b/vault-doc/src/site/site.xml
index 6f678c9..65acf97 100644
--- a/vault-doc/src/site/site.xml
+++ b/vault-doc/src/site/site.xml
@@ -42,6 +42,7 @@
         <item href="settings.html" name="Settings"/>
         <item href="nodetypes.html" name="Nodetypes"/>
         <item href="privileges.html" name="Privileges"/>
+        <item href="installhooks.html" name="Install Hooks"/>
      </item>
       <item href="rcp.html" name="Vault Remote Copy" />
     </menu>