filevault-package:generate-metadata
Full name:
org.apache.jackrabbit:filevault-package-maven-plugin:1.4.0-SNAPSHOT: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: false User Property: vault.allowIndexDefinitions |
<failOnEmptyFilter> |
boolean |
- |
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. Default: true User Property: vault.failOnEmptyFilter |
<failOnMissingEmbed> |
boolean |
- |
Defines whether to fail the build when an embedded artifact is not found in the project's dependencies Default: false User Property: 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: ${project.groupId} User Property: 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 This directory must be outside the 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 User Property: vault.metaInfVaultDirectory |
<name> |
String |
- |
The name of the content package Default: ${project.artifactId} User Property: 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: false User Property: vault.requiresRoot |
<version> |
String |
- |
The version of the content package. Default: ${project.version} User Property: 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.
This directory must not contain any other files/directories than those being generated by the Default: ${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:
User Property: vault.acHandling Alias: 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: 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 User Property: vault.dependencies | ||||||||||||||||||||||||||||
<embeddedTarget> |
String |
- |
Defines the default parent directory path in the package ZIP archive which contains the embedded bundles (/ needs to be used as file separator). Must be relative to root entry jcr_root . Defaults to apps/bundles/install .User Property: vault.embeddedTarget | ||||||||||||||||||||||||||||
<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
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. | ||||||||||||||||||||||||||||
<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 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: ${project.build.directory}/vault-generated-import.txt User Property: vault.generatedImportPackage | ||||||||||||||||||||||||||||
<importPackage> |
String |
- |
Defines additional package dependencies via the `import-package` entry in the manifest. Is merged with the input from generatedImportPackage .Default: -org.apache.sling.scripting.sightly.compiler.expression.nodes,-org.apache.sling.scripting.sightly.java.compiler,-org.apache.sling.scripting.sightly.render User Property: 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: ${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:
User Property: 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: vault.prefix | ||||||||||||||||||||||||||||
<properties> |
Properties |
- |
Specifies additional package properties to be set in the properties.xml file. These properties cannot overwrite the following predefined properties:
| ||||||||||||||||||||||||||||
<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:
| ||||||||||||||||||||||||||||
<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
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>
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>
allowIndexDefinitions
property of the properties.xml file.- Type:
boolean
- Required:
Yes
- User Property:
vault.allowIndexDefinitions
- Default:
false
<archive>
workDirectory
- Type:
org.apache.maven.archiver.MavenArchiveConfiguration
- Required:
No
<classifier>
<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>
<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<org.apache.jackrabbit.filevault.maven.packaging.MavenBasedPackageDependency>
- Required:
No
- User Property:
vault.dependencies
<embeddedTarget>
/
needs to be used as file separator). Must be relative to root entry jcr_root
. Defaults to apps/bundles/install
.- Type:
java.lang.String
- Required:
No
- User Property:
vault.embeddedTarget
<embeddeds>
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
|
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 directory path in the package ZIP archive where to place the embedded artifact (/ needs to be used as file separator). Must be relative to root entry jcr_root . Falls back to embeddedTarget if not set. |
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.- Type:
org.apache.jackrabbit.filevault.maven.packaging.Embedded[]
- Required:
No
<failOnEmptyFilter>
This is no longer evaluated as every package is supposed to come with a non-empty filter
- Type:
boolean
- Required:
Yes
- User Property:
vault.failOnEmptyFilter
- Default:
true
<failOnMissingEmbed>
- Type:
boolean
- Required:
Yes
- User Property:
vault.failOnMissingEmbed
- Default:
false
<filterSource>
- Type:
java.io.File
- Required:
No
<filters>
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>
- Type:
java.io.File
- Required:
No
- User Property:
vault.generatedImportPackage
- Default:
${project.build.directory}/vault-generated-import.txt
<group>
- Type:
java.lang.String
- Required:
Yes
- User Property:
vault.group
- Default:
${project.groupId}
<importPackage>
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>
<groupId>:<artifactId>[:<extension>[:<classifier>]]:<version>
. The resolved artifacts are embedded as internal install hooks in the resulting content package.- Type:
java.util.List<org.apache.jackrabbit.filevault.maven.packaging.ArtifactCoordinates>
- Since:
1.1.8
- Required:
No
<metaInfVaultDirectory>
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.
This directory must be outside the workDirectory
.
- 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>
- Type:
java.lang.String
- Required:
Yes
- User Property:
vault.name
- Default:
${project.artifactId}
<outputTimestamp>
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>
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.- Type:
java.util.Map<java.lang.String, java.lang.String>
- Required:
No
<packageType>
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>
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>
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 |
- Type:
java.util.Properties
- Required:
No
<requiresRoot>
requiresRoot
property of the properties.xml file.- Type:
boolean
- Required:
Yes
- User Property:
vault.requiresRoot
- Default:
false
<subPackageHandlingEntries>
- 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
- Type:
java.util.List<org.apache.jackrabbit.filevault.maven.packaging.SubPackageHandlingEntry>
- Since:
1.1.10
- Required:
No
<subPackages>
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
|
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 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.- Type:
org.apache.jackrabbit.filevault.maven.packaging.SubPackage[]
- Required:
No
<thumbnailImage>
- Type:
java.io.File
- Since:
1.0.1
- Required:
No
<version>
- Type:
java.lang.String
- Required:
Yes
- User Property:
vault.version
- Default:
${project.version}
<workDirectory>
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.
This directory must not contain any other files/directories than those being generated by the generate-metadata
goal.
- Type:
java.io.File
- Required:
Yes
- Default:
${project.build.directory}/vault-work