Fork me on GitHub

filevault-package:generate-metadata

Full name:

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

Description:

Maven goal which generates the metadata ending up in the 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.

Attributes:

  • Requires a Maven project to be executed.
  • Requires dependency resolution of artifacts in scope: compile.
  • Binds by default to the lifecycle phase: process-classes.

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. This is no longer evaluated as every package is supposed to come with a non-empty filter
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 root. 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 directory containing the metadata to be packaged up into the content package. Basically containing all files/folders being generated by goal "generate-metadata".
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 AbstractMetadataPackageMojo.workDirectory
<dependencies> Collection - 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.
<embeddedTarget> String - Defines the path under which the embedded bundles are placed. defaults to '/apps/bundles/install'
User property is: vault.embeddedTarget.
<embeddeds> Embedded[] - List of filters for artifacts to embed in the package. The Embedded class represents one or multiple embedded artifact dependencies from the project descriptor. Each <embedded> 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 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.
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).
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 &lt;filter&gt;{,&lt;filter&gt;}. 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.
<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.
<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.
<generatedImportPackage> File - File to store the generated manifest snippet.
Default value is: ${project.build.directory}/vault-generated-import.txt.
User property is: vault.generatedImportPackage.
<importPackage> String - Defines additional bundle dependency via the osgi import-package entry in the manifest.
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.
<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}.
<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 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

<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 ids of a project dependency. A pattern as described below.
scope 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.
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).
filter Boolean If set to true adds the embedded artifact location to the package's filter
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 &lt;filter&gt;{,&lt;filter&gt;}. 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 - Optional reference to PNG image that should be used as thumbnail for the content package.

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.
  • Type: org.apache.jackrabbit.vault.fs.io.AccessControlHandling
  • Required: No
  • User Property: vault.acHandling
  • Alias: acHandling

<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 AbstractMetadataPackageMojo.workDirectory
  • Type: org.apache.maven.archiver.MavenArchiveConfiguration
  • Required: No

<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 []

  • Type: java.util.Collection
  • Required: No
  • User Property: vault.dependencies

<embeddedTarget>

Defines the path under which the embedded bundles are placed. defaults to '/apps/bundles/install'
  • Type: java.lang.String
  • Required: No
  • User Property: vault.embeddedTarget

<embeddeds>

List of filters for artifacts to embed in the package. The Embedded class represents one or multiple embedded artifact dependencies from the project descriptor. Each <embedded> 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 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.
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).
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 &lt;filter&gt;{,&lt;filter&gt;}. 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.
  • Type: org.apache.jackrabbit.filevault.maven.packaging.Embedded[]
  • Required: No

<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

<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.
  • Type: java.io.File
  • Required: No

<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.
  • Type: org.apache.jackrabbit.filevault.maven.packaging.Filters
  • Required: No

<generatedImportPackage>

File to store the generated manifest snippet.
  • 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 bundle dependency via the osgi import-package entry in the manifest.
  • 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

<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}

<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.
  • Type: org.apache.jackrabbit.vault.packaging.PackageType
  • Required: No
  • User Property: vault.packageType

<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.
  • Type: java.lang.String
  • Required: No
  • User Property: vault.prefix

<properties>

Specifies additional 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
  • Type: java.util.Properties
  • Required: No

<requiresRoot>

Defines whether the package requires root. This will become the requiresRoot property of the properties.xml file.
  • Type: boolean
  • Required: Yes
  • User Property: vault.requiresRoot
  • Default: false

<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 ids of a project dependency. A pattern as described below.
scope 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.
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).
filter Boolean If set to true adds the embedded artifact location to the package's filter
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 &lt;filter&gt;{,&lt;filter&gt;}. 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.
  • Type: org.apache.jackrabbit.filevault.maven.packaging.SubPackage[]
  • Required: No

<thumbnailImage>

Optional reference to PNG image that should be used as thumbnail for the content package.
  • Type: java.io.File
  • Required: No

<version>

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

<workDirectory>

The directory containing the metadata to be packaged up into the content package. Basically containing all files/folders being generated by goal "generate-metadata".
  • Type: java.io.File
  • Required: Yes
  • Default: ${project.build.directory}/vault-work