Fork me on GitHub
Built by Maven

filevault-package:generate-metadata

Full name:

org.apache.jackrabbit:filevault-package-maven-plugin:1.3.2:generate-metadata

Description:

Generates the metadata ending up in the content package like META-INF/MANIFEST.MF as well as the files ending up in META-INF/vault like filter.xml, properties.xml, config.xml and settings.xml. Those files will be written to the directory given via parameter workDirectory. In addition performs some validations. Also configures artifacts (like OSGi bundles or subpackages) to be embedded in the content package as those may affect metadata as well. The generated metadata is usually packaged in a content package in a subsequent goal package.

This goal is executed/bound by default for Maven modules of type content-package.

Attributes:

  • Requires a Maven project to be executed.
  • Requires dependency resolution of artifacts in scope: compile.
  • The goal is thread-safe and supports parallel builds.
  • Since version: 1.0.3.
  • Binds by default to the lifecycle phase: generate-test-sources.

Required Parameters

Name Type Since Description
<allowIndexDefinitions> boolean - Defines whether the package is allowed to contain index definitions. This will become the allowIndexDefinitions property of the properties.xml file.
Default value is: false.
User property is: vault.allowIndexDefinitions.
<failOnEmptyFilter> boolean - Deprecated. Controls if empty workspace filter fails the build.
Default value is: true.
User property is: vault.failOnEmptyFilter.
<failOnMissingEmbed> boolean - Defines whether to fail the build when an embedded artifact is not found in the project's dependencies
Default value is: false.
User property is: vault.failOnMissingEmbed.
<group> String - The groupId used for the generated content package. This will be part of the target installation path of the content package.
Default value is: ${project.groupId}.
User property is: vault.group.
<metaInfVaultDirectory> File[] - The directory that contains the META-INF/vault. Multiple directories can be specified as a comma separated list, which will act as a search path and cause the plugin to look for the first existing directory.

This directory is added as fileset to the package archiver before the the workDirectory. This means that files specified in this directory have precedence over the one present in the workDirectory. For example, if this directory contains a properties.xml it will not be overwritten by the generated one. A special case is the filter.xml which will be merged with inline filters if present.


Default value is: ${project.basedir}/META-INF/vault,${project.basedir}/src/main/META-INF/vault,${project.basedir}/src/main/content/META-INF/vault,${project.basedir}/src/content/META-INF/vault.
User property is: vault.metaInfVaultDirectory.
<name> String - The name of the content package
Default value is: ${project.artifactId}.
User property is: vault.name.
<requiresRoot> boolean - Defines whether the package requires an admin/privileged session for installation. This will become the requiresRoot property of the properties.xml file.
Default value is: false.
User property is: vault.requiresRoot.
<version> String - The version of the content package.
Default value is: ${project.version}.
User property is: vault.version.
<workDirectory> File - The output directory for goal "generate-metadata" and additional input directory containing the metadata to be packaged up into the content package for goal "package". The directory name is suffixed with -<classifier> in case a classifier is used. In case of the "package" goal this falls back to the non-suffixed directory name in case the one with suffix does not exist.
Default value is: ${project.build.directory}/vault-work.

Optional Parameters

Name Type Since Description
<accessControlHandling> AccessControlHandling - Defines the Access control handling. This will become the acHandling property of the properties.xml file.
Possible values:
  • ignore: Ignores the packaged access control and leaves the target unchanged.
  • overwrite: Applies the access control provided with the package to the target. this also removes existing access control.
  • merge: Merge access control provided with the package with the one in the content by replacing the access control entries of corresponding principals (i.e. package first). It never alters access control entries of principals not present in the package.
  • merge_preserve: Merge access control in the content with the one provided with the package by adding the access control entries of principals not present in the content (i.e. content first). It never alters access control entries already existing in the content.
  • clear: Clears all access control on the target system.

User property is: vault.acHandling.
Alias is: acHandling.
<archive> MavenArchiveConfiguration - The archive configuration to use. See the documentation for Maven Archiver. All settings related to manifest are not relevant as this gets overwritten by the manifest in workDirectory
<classifier> String 1.1.4 Optional classifier to add to the generated package. If given, the artifact will be attached as a supplemental artifact having this classifier. Also all generated metadata will be pushed to <workDirectory>-<classifier> and will preferably be looked up from there. In addition the embedded file names will be exchanged leveraging a classifier specific property.
User property is: vault.classifier.
<dependencies> Collection<MavenBasedPackageDependency> - Defines the list of dependencies A dependency is declared as a <dependency> element of a list style <dependencies> element: 
<dependency>
    <group>theGroup</group>
    <name>theName</name>
    <version>1.5</version>
</dependency>

The dependency can also reference a maven project dependency, this is preferred as it yields to more robust builds.

<dependency>
    <groupId>theGroup</groupId>
    <artifactId>theName</artifactId>
</dependency>

The versionRange may be indicated as a single version, in which case the version range has no upper bound and defines the minimal version accepted. Otherwise, the version range defines a lower and upper bound of accepted versions, where the bounds are either included using parentheses () or excluded using brackets []


User property is: vault.dependencies.
<embeddeds> Embedded[] - List of filters for artifacts to embed in the package. The org.apache.jackrabbit.filevault.maven.packaging.Embedded class represents one or multiple embedded artifact dependencies from the project descriptor. Each item may configure any of the following fields

groupId String Filter criterion against the group id of a project dependency. A pattern as described below.
artifactId String Filter criterion against the artifact id of a project dependency. A pattern as described below.
scope org.apache.maven.artifact.resolver.filter.ScopeArtifactFilter Filter criterion against the scope of a project dependency. Possible values are
  • test, which allows every scope
  • compile+runtime which allows every scope except test
  • runtime+system which allows every scope except test and provided
  • compile which allows only scope compile, provided and system
  • runtime which only allows scope runtime and compile.
type String Filter criterion against the type of a project dependency. A pattern as described below.
classifier String Filter criterion against the classifier of a project dependency. A pattern as described below.
filter Boolean If set to true adds the embedded artifact location to the package's filter. Default = false.
isAllVersionsFilter Boolean If filter is true and this is true as well, the filter entry will contain all versions of the same artifact (by creating an according filter pattern). Default = false.
excludeTransitive Boolean If true only filters on direct dependencies (not on transitive ones). Default = false.
target String The parent folder location in the package where to place the embedded artifact. Falls back to embeddedTarget if not set.
All fields are optional. All filter criteria is concatenated with AND logic (i.e. every criterion must match for a specific dependency to be embedded).
All filter patterns follow the format <filter>{,<filter>}. Each filter is a string which is either an exclude (if it starts with a ~) or an include otherwise. If the first filter is an include the pattern acts as whitelist, otherwise as blacklist. The last matching filter determines the outcome. Only matching dependencies are being considered for being embedded.
The difference between embeddeds and subPackages is that for the former an explicit target is given while for the latter the target is being computed from the artifact's vault property file.
<embeddedTarget> String - Defines the path under which the embedded bundles are placed. defaults to '/apps/bundles/install'
User property is: vault.embeddedTarget.
<filters> Filters - Defines the content of the filter.xml file. Each filter consists of the mandatory element root and the optional mode and type elements. All those elements are simple strings. In addition optionally a number of include and exclude elements are supported below includes/excludes respectively.
<filterSource> File - Optional file that specifies the source of the workspace filter. The filters specified in the configuration and injected via emebedds or subpackages are merged into it.
<generatedImportPackage> File - File from which to read the generated manifest snippet generated by goal "analyze-classes". The contents of the file end up in the `import-package` entry in the manifest.
Default value is: ${project.build.directory}/vault-generated-import.txt.
User property is: vault.generatedImportPackage.
<importPackage> String - Defines additional package dependencies via the `import-package` entry in the manifest. Is merged with the input from generatedImportPackage.
Default value is: -org.apache.sling.scripting.sightly.compiler.expression.nodes,-org.apache.sling.scripting.sightly.java.compiler,-org.apache.sling.scripting.sightly.render.
User property is: vault.importPackage.
<installHooks> List<ArtifactCoordinates> 1.1.8 A list of artifact coordinates in the format <groupId>:<artifactId>[:<extension>[:<classifier>]]:<version>. The resolved artifacts are embedded as internal install hooks in the resulting content package.
<outputTimestamp> String 1.1.0 Timestamp for reproducible output archive entries, either formatted as ISO 8601 yyyy-MM-dd'T'HH:mm:ssXXX or as an int representing seconds since the epoch (like SOURCE_DATE_EPOCH).
Default value is: ${project.build.outputTimestamp}.
<packageDefinitionProperties> Map<String,String> - Specifies JCR package definition properties to be serialized into the META-INF/vault/definition/.content.xml file. Those are implementation-specific and not standardized by FileVault. Only non-namespaced string properties are allowed here. Properties canonically stored somewhere else (like package properties or filter rules) should not be set.
<packageType> PackageType - Defines the content package type. This is either 'application', 'content', 'container' or 'mixed'. If omitted, it is calculated automatically based on filter definitions. Certain package types imply restrictions, for example, 'application' and 'content' packages are not allowed to contain sub packages or embedded bundles.
Possible values:
  • 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.
  • 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 configuration or bundles.
  • container: A container package only contains sub packages and OSGi configuration and bundles. The container package is only used as container for deployment.
  • mixed: Catch all type for a combination of the above.

User property is: vault.packageType.
<prefix> String - Adds a path prefix to all resources. Useful for shallower source trees. This does not apply to files in workDirectory nor metaInfVaultDirectory but e.g. is relevant for the default filter and for the jcr_root of the package. Must start with "/" if not empty. As separator only forward slashes are allowed. The trailing slash is automatically appended if not there.
User property is: vault.prefix.
<properties> Properties - Specifies additional package properties to be set in the properties.xml file. These properties cannot overwrite the following predefined properties:

group Use group parameter to set
name Use name parameter to set
version Use version parameter to set
groupId groupId of the Maven project descriptor
artifactId artifactId of the Maven project descriptor
dependencies Use dependencies parameter to set
createdBy The value of the user.name system property
created The current system time
requiresRoot Use requiresRoot parameter to set
allowIndexDefinitions Use allowIndexDefinitions parameter to set
packagePath Automatically generated from the group and package name
packageType Set via the package type parameter
acHandling Use accessControlHandling parameter to set
subPackageHandling Use subPackageHandlingEntries parameter to set

<subPackageHandlingEntries> List<SubPackageHandlingEntry> 1.1.10 Defines a list of sub package handling entries, which affect how sub packages are installed. Each entry has the following elements:
  • option, mandatory, one of the values from org.apache.jackrabbit.vault.packaging.SubPackageHandling.Option
  • groupName, optional, restricts the option to the given group name, if not set affects there is no package group restriction
  • packageName, optional, restricts the option to the given package name, if not set affects all package names
<subPackages> SubPackage[] - Defines the list of sub packages to be embedded in this package. The SubPackage class represents one or multiple subpackage artifact dependencies from the project descriptor. Each <subPackage> element may configure any of the following fields

groupId String Filter criterion against the group id of a project dependency. A pattern as described below.
artifactId String Filter criterion against the artifact id of a project dependency. A pattern as described below.
scope org.apache.maven.artifact.resolver.filter.ScopeArtifactFilter Filter criterion against the scope of a project dependency. Possible values are
  • test, which allows every scope
  • compile+runtime which allows every scope except test
  • runtime+system which allows every scope except test and provided
  • compile which allows only scope compile, provided and system
  • runtime which only allows scope runtime and compile.
type String Filter criterion against the type of a project dependency. A pattern as described below.
classifier String Filter criterion against the classifier of a project dependency. A pattern as described below.
filter Boolean If set to true adds the embedded artifact location to the package's filter. Default = false.
isAllVersionsFilter Boolean If filter is true and this is true as well, the filter entry will contain all versions of the same artifact (by creating an according filter pattern). Default = false.
excludeTransitive Boolean If true only filters on direct dependencies (not on transitive ones). Default = false.
All fields are optional. All filter criteria is concatenated with AND logic (i.e. every criterion must match for a specific dependency to be embedded as a sub package).
All filter patterns follow the format <filter>{,<filter>}. Each filter within a filter pattern is a string which is either an exclude (if it starts with a ~) or an include otherwise. If the first filter is an include the pattern acts as whitelist, otherwise as blacklist. The last matching filter determines the outcome. Only matching dependencies are being considered for being embedded.
The difference between embeddeds and subPackages is that for the former an explicit target is given while for the latter the target is being computed from the artifact's vault property file.
<thumbnailImage> File 1.0.1 Optional reference to PNG image that should be used as thumbnail for the content package. Should have a width of 64 pixels.

Parameter Details

<accessControlHandling>

Defines the Access control handling. This will become the acHandling property of the properties.xml file.
Possible values:
  • ignore: Ignores the packaged access control and leaves the target unchanged.
  • overwrite: Applies the access control provided with the package to the target. this also removes existing access control.
  • merge: Merge access control provided with the package with the one in the content by replacing the access control entries of corresponding principals (i.e. package first). It never alters access control entries of principals not present in the package.
  • merge_preserve: Merge access control in the content with the one provided with the package by adding the access control entries of principals not present in the content (i.e. content first). It never alters access control entries already existing in the content.
  • clear: Clears all access control on the target system.

<allowIndexDefinitions>

Defines whether the package is allowed to contain index definitions. This will become the allowIndexDefinitions property of the properties.xml file.
  • Type: boolean
  • Required: Yes
  • User Property: vault.allowIndexDefinitions
  • Default: false

<archive>

The archive configuration to use. See the documentation for Maven Archiver. All settings related to manifest are not relevant as this gets overwritten by the manifest in workDirectory

<classifier>

Optional classifier to add to the generated package. If given, the artifact will be attached as a supplemental artifact having this classifier. Also all generated metadata will be pushed to <workDirectory>-<classifier> and will preferably be looked up from there. In addition the embedded file names will be exchanged leveraging a classifier specific property.
  • Type: java.lang.String
  • Since: 1.1.4
  • Required: No
  • User Property: vault.classifier

<dependencies>

Defines the list of dependencies A dependency is declared as a <dependency> element of a list style <dependencies> element: 
<dependency>
    <group>theGroup</group>
    <name>theName</name>
    <version>1.5</version>
</dependency>

The dependency can also reference a maven project dependency, this is preferred as it yields to more robust builds.

<dependency>
    <groupId>theGroup</groupId>
    <artifactId>theName</artifactId>
</dependency>

The versionRange may be indicated as a single version, in which case the version range has no upper bound and defines the minimal version accepted. Otherwise, the version range defines a lower and upper bound of accepted versions, where the bounds are either included using parentheses () or excluded using brackets []

<embeddeds>

List of filters for artifacts to embed in the package. The org.apache.jackrabbit.filevault.maven.packaging.Embedded class represents one or multiple embedded artifact dependencies from the project descriptor. Each item may configure any of the following fields

groupId String Filter criterion against the group id of a project dependency. A pattern as described below.
artifactId String Filter criterion against the artifact id of a project dependency. A pattern as described below.
scope org.apache.maven.artifact.resolver.filter.ScopeArtifactFilter Filter criterion against the scope of a project dependency. Possible values are
  • test, which allows every scope
  • compile+runtime which allows every scope except test
  • runtime+system which allows every scope except test and provided
  • compile which allows only scope compile, provided and system
  • runtime which only allows scope runtime and compile.
type String Filter criterion against the type of a project dependency. A pattern as described below.
classifier String Filter criterion against the classifier of a project dependency. A pattern as described below.
filter Boolean If set to true adds the embedded artifact location to the package's filter. Default = false.
isAllVersionsFilter Boolean If filter is true and this is true as well, the filter entry will contain all versions of the same artifact (by creating an according filter pattern). Default = false.
excludeTransitive Boolean If true only filters on direct dependencies (not on transitive ones). Default = false.
target String The parent folder location in the package where to place the embedded artifact. Falls back to embeddedTarget if not set.
All fields are optional. All filter criteria is concatenated with AND logic (i.e. every criterion must match for a specific dependency to be embedded).
All filter patterns follow the format <filter>{,<filter>}. Each filter is a string which is either an exclude (if it starts with a ~) or an include otherwise. If the first filter is an include the pattern acts as whitelist, otherwise as blacklist. The last matching filter determines the outcome. Only matching dependencies are being considered for being embedded.
The difference between embeddeds and subPackages is that for the former an explicit target is given while for the latter the target is being computed from the artifact's vault property file.

<embeddedTarget>

Defines the path under which the embedded bundles are placed. defaults to '/apps/bundles/install'

<failOnEmptyFilter>

Deprecated. This is no longer evaluated as every package is supposed to come with a non-empty filter
Controls if empty workspace filter fails the build.
  • Type: boolean
  • Required: Yes
  • User Property: vault.failOnEmptyFilter
  • Default: true

<failOnMissingEmbed>

Defines whether to fail the build when an embedded artifact is not found in the project's dependencies
  • Type: boolean
  • Required: Yes
  • User Property: vault.failOnMissingEmbed
  • Default: false

<filters>

Defines the content of the filter.xml file. Each filter consists of the mandatory element root and the optional mode and type elements. All those elements are simple strings. In addition optionally a number of include and exclude elements are supported below includes/excludes respectively.

<filterSource>

Optional file that specifies the source of the workspace filter. The filters specified in the configuration and injected via emebedds or subpackages are merged into it.

<generatedImportPackage>

File from which to read the generated manifest snippet generated by goal "analyze-classes". The contents of the file end up in the `import-package` entry in the manifest.
  • Type: java.io.File
  • Required: No
  • User Property: vault.generatedImportPackage
  • Default: ${project.build.directory}/vault-generated-import.txt

<group>

The groupId used for the generated content package. This will be part of the target installation path of the content package.
  • Type: java.lang.String
  • Required: Yes
  • User Property: vault.group
  • Default: ${project.groupId}

<importPackage>

Defines additional package dependencies via the `import-package` entry in the manifest. Is merged with the input from generatedImportPackage.
  • Type: java.lang.String
  • Required: No
  • User Property: vault.importPackage
  • Default: -org.apache.sling.scripting.sightly.compiler.expression.nodes,-org.apache.sling.scripting.sightly.java.compiler,-org.apache.sling.scripting.sightly.render

<installHooks>

A list of artifact coordinates in the format <groupId>:<artifactId>[:<extension>[:<classifier>]]:<version>. The resolved artifacts are embedded as internal install hooks in the resulting content package.

<metaInfVaultDirectory>

The directory that contains the META-INF/vault. Multiple directories can be specified as a comma separated list, which will act as a search path and cause the plugin to look for the first existing directory.

This directory is added as fileset to the package archiver before the the workDirectory. This means that files specified in this directory have precedence over the one present in the workDirectory. For example, if this directory contains a properties.xml it will not be overwritten by the generated one. A special case is the filter.xml which will be merged with inline filters if present.

  • Type: java.io.File[]
  • Required: Yes
  • User Property: vault.metaInfVaultDirectory
  • Default: ${project.basedir}/META-INF/vault,${project.basedir}/src/main/META-INF/vault,${project.basedir}/src/main/content/META-INF/vault,${project.basedir}/src/content/META-INF/vault

<name>

The name of the content package
  • Type: java.lang.String
  • Required: Yes
  • User Property: vault.name
  • Default: ${project.artifactId}

<outputTimestamp>

Timestamp for reproducible output archive entries, either formatted as ISO 8601 yyyy-MM-dd'T'HH:mm:ssXXX or as an int representing seconds since the epoch (like SOURCE_DATE_EPOCH).
  • Type: java.lang.String
  • Since: 1.1.0
  • Required: No
  • Default: ${project.build.outputTimestamp}

<packageDefinitionProperties>

Specifies JCR package definition properties to be serialized into the META-INF/vault/definition/.content.xml file. Those are implementation-specific and not standardized by FileVault. Only non-namespaced string properties are allowed here. Properties canonically stored somewhere else (like package properties or filter rules) should not be set.

<packageType>

Defines the content package type. This is either 'application', 'content', 'container' or 'mixed'. If omitted, it is calculated automatically based on filter definitions. Certain package types imply restrictions, for example, 'application' and 'content' packages are not allowed to contain sub packages or embedded bundles.
Possible values:
  • 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.
  • 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 configuration or bundles.
  • container: A container package only contains sub packages and OSGi configuration and bundles. The container package is only used as container for deployment.
  • mixed: Catch all type for a combination of the above.

<prefix>

Adds a path prefix to all resources. Useful for shallower source trees. This does not apply to files in workDirectory nor metaInfVaultDirectory but e.g. is relevant for the default filter and for the jcr_root of the package. Must start with "/" if not empty. As separator only forward slashes are allowed. The trailing slash is automatically appended if not there.

<properties>

Specifies additional package properties to be set in the properties.xml file. These properties cannot overwrite the following predefined properties:

group Use group parameter to set
name Use name parameter to set
version Use version parameter to set
groupId groupId of the Maven project descriptor
artifactId artifactId of the Maven project descriptor
dependencies Use dependencies parameter to set
createdBy The value of the user.name system property
created The current system time
requiresRoot Use requiresRoot parameter to set
allowIndexDefinitions Use allowIndexDefinitions parameter to set
packagePath Automatically generated from the group and package name
packageType Set via the package type parameter
acHandling Use accessControlHandling parameter to set
subPackageHandling Use subPackageHandlingEntries parameter to set

<requiresRoot>

Defines whether the package requires an admin/privileged session for installation. This will become the requiresRoot property of the properties.xml file.
  • Type: boolean
  • Required: Yes
  • User Property: vault.requiresRoot
  • Default: false

<subPackageHandlingEntries>

Defines a list of sub package handling entries, which affect how sub packages are installed. Each entry has the following elements:
  • option, mandatory, one of the values from org.apache.jackrabbit.vault.packaging.SubPackageHandling.Option
  • groupName, optional, restricts the option to the given group name, if not set affects there is no package group restriction
  • packageName, optional, restricts the option to the given package name, if not set affects all package names

<subPackages>

Defines the list of sub packages to be embedded in this package. The SubPackage class represents one or multiple subpackage artifact dependencies from the project descriptor. Each <subPackage> element may configure any of the following fields

groupId String Filter criterion against the group id of a project dependency. A pattern as described below.
artifactId String Filter criterion against the artifact id of a project dependency. A pattern as described below.
scope org.apache.maven.artifact.resolver.filter.ScopeArtifactFilter Filter criterion against the scope of a project dependency. Possible values are
  • test, which allows every scope
  • compile+runtime which allows every scope except test
  • runtime+system which allows every scope except test and provided
  • compile which allows only scope compile, provided and system
  • runtime which only allows scope runtime and compile.
type String Filter criterion against the type of a project dependency. A pattern as described below.
classifier String Filter criterion against the classifier of a project dependency. A pattern as described below.
filter Boolean If set to true adds the embedded artifact location to the package's filter. Default = false.
isAllVersionsFilter Boolean If filter is true and this is true as well, the filter entry will contain all versions of the same artifact (by creating an according filter pattern). Default = false.
excludeTransitive Boolean If true only filters on direct dependencies (not on transitive ones). Default = false.
All fields are optional. All filter criteria is concatenated with AND logic (i.e. every criterion must match for a specific dependency to be embedded as a sub package).
All filter patterns follow the format <filter>{,<filter>}. Each filter within a filter pattern is a string which is either an exclude (if it starts with a ~) or an include otherwise. If the first filter is an include the pattern acts as whitelist, otherwise as blacklist. The last matching filter determines the outcome. Only matching dependencies are being considered for being embedded.
The difference between embeddeds and subPackages is that for the former an explicit target is given while for the latter the target is being computed from the artifact's vault property file.

<thumbnailImage>

Optional reference to PNG image that should be used as thumbnail for the content package. Should have a width of 64 pixels.

<version>

The version of the content package.
  • Type: java.lang.String
  • Required: Yes
  • User Property: vault.version
  • Default: ${project.version}

<workDirectory>

The output directory for goal "generate-metadata" and additional input directory containing the metadata to be packaged up into the content package for goal "package". The directory name is suffixed with -<classifier> in case a classifier is used. In case of the "package" goal this falls back to the non-suffixed directory name in case the one with suffix does not exist.
  • Type: java.io.File
  • Required: Yes
  • Default: ${project.build.directory}/vault-work