Fork me on GitHub

filevault-package:generate-metadata

Full name:

org.apache.jackrabbit:filevault-package-maven-plugin:1.0.5-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.
<failOnDependencyErrors> boolean - Controls if errors during dependency validation should fail the build.
Default value is: true.
User property is: vault.failOnDependencyErrors.
<failOnEmptyFilter> boolean - 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 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 AbstractPackageMojo.workDirectory
<dependencies> Dependency[] - 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 []
<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.
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
<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.
<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.
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

<repositoryStructurePackages> Dependency[] - Defines the packages that define the repository structure. For the format description look at dependencies.

The repository-init feature of sling-start can define initial content that will be available in the repository before the first package is installed. Packages that depend on those nodes have no way to reference any dependency package that provides these nodes. A "real" package that would creates those nodes cannot be installed in the repository, because it would void the repository init structure. On the other hand would filevault complain, if the package was listed as dependency but not installed in the repository. So therefor this repository-structure packages serve as indicator packages that helps satisfy the structural dependencies, but are not added as real dependencies to the package.
<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.
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 AbstractPackageMojo.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: org.apache.jackrabbit.filevault.maven.packaging.Dependency[]
  • Required: No

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

<failOnDependencyErrors>

Controls if errors during dependency validation should fail the build.
  • Type: boolean
  • Required: Yes
  • User Property: vault.failOnDependencyErrors
  • Default: true

<failOnEmptyFilter>

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

<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.
  • 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

<repositoryStructurePackages>

Defines the packages that define the repository structure. For the format description look at dependencies.

The repository-init feature of sling-start can define initial content that will be available in the repository before the first package is installed. Packages that depend on those nodes have no way to reference any dependency package that provides these nodes. A "real" package that would creates those nodes cannot be installed in the repository, because it would void the repository init structure. On the other hand would filevault complain, if the package was listed as dependency but not installed in the repository. So therefor this repository-structure packages serve as indicator packages that helps satisfy the structural dependencies, but are not added as real dependencies to the package.

  • Type: org.apache.jackrabbit.filevault.maven.packaging.Dependency[]
  • 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.
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