Component

When creating several assemblies for a project with a custom assembly descriptor, it can't be helped that you will be duplicating some parts of a defined assembly. These duplicates can be extracted and placed in a separate file called a descriptor component.

Descriptor components contain FileSets, Files, and DependencySets meant to be shared by assembly descriptors by referencing them using <componentDescriptors>. It allows multiple assemblies to share a set of user defined collections. 

<component
>
  <fileSets>
    <fileSet
>
      <directory/>
      <lineEnding/>
      <filtered/>
      <useStrictFiltering/>
      <useDefaultExcludes/>
      <outputDirectory/>
      <includes/>
      <excludes/>
      <fileMode/>
      <directoryMode/>
    </fileSet>
  </fileSets>
  <files>
    <file
>
      <source/>
      <outputDirectory/>
      <destName/>
      <fileMode/>
      <lineEnding/>
      <filtered/>
    </file>
  </files>
  <dependencySets>
    <dependencySet
>
      <outputFileNameMapping/>
      <unpack/>
      <unpackOptions
>
        <includes/>
        <excludes/>
        <filtered/>
      </unpackOptions>
      <scope/>
      <useProjectArtifact/>
      <useProjectAttachments/>
      <useTransitiveDependencies/>
      <useTransitiveFiltering/>
      <useStrictFiltering/>
      <useDefaultExcludes/>
      <outputDirectory/>
      <includes/>
      <excludes/>
      <fileMode/>
      <directoryMode/>
    </dependencySet>
  </dependencySets>
  <repositories>
    <repository
>
      <includeMetadata/>
      <groupVersionAlignments>
        <groupVersionAlignment
>
          <id/>
          <version/>
          <excludes/>
        </groupVersionAlignment>
      </groupVersionAlignments>
      <scope/>
      <useStrictFiltering/>
      <useDefaultExcludes/>
      <outputDirectory/>
      <includes/>
      <excludes/>
      <fileMode/>
      <directoryMode/>
    </repository>
  </repositories>
  <containerDescriptorHandlers>
    <containerDescriptorHandler
>
      <handlerName/>
    </containerDescriptorHandler>
  </containerDescriptorHandlers>
</component>

component

Describes the component layout and packaging.

Element Description
fileSets Specifies which groups of files to include in the assembly. A fileSet is specified by providing one or more of <fileSet> subelements.
files Specifies which single files to include in the assembly. A file is specified by providing one or more of <file> subelements.
dependencySets Specifies which dependencies to include in the assembly. A dependencySet is specified by providing one or more of <dependencySet> subelements.
repositories Specifies a set of repositories to include in the assembly. A repository is specified by providing one or more of <repository> subelements.
containerDescriptorHandlers Set of components which filter various container descriptors out of the normal archive stream, so they can be aggregated then added.

fileSet

A fileSet allows the inclusion of groups of files into the assembly.

Element Description
directory Sets the absolute or relative location from the module's directory. For example, "src/main/bin" would select this subdirectory of the project in which this dependency is defined.
lineEnding Sets the line-endings of the files in this fileSet. Valid values:
  • "keep" - Preserve all line endings
  • "unix" - Use Unix-style line endings
  • "lf" - Use a single line-feed line endings
  • "dos" - Use DOS-style line endings
  • "crlf" - Use Carraige-return, line-feed line endings
filtered Whether to filter symbols in the files as they are copied, using properties from the build configuration. The default value is false.
useStrictFiltering When specified as true, any include/exclude patterns which aren't used to filter an actual artifact during assembly creation will cause the build to fail with an error. This is meant to highlight obsolete inclusions or exclusions, or else signal that the assembly descriptor is incorrectly configured. The default value is false.
useDefaultExcludes Whether standard exclusion patterns, such as those matching CVS and Subversion metadata files, should be used when calculating the files affected by this set. For backward compatibility, the default value is true. The default value is true.
outputDirectory Sets the output directory relative to the root of the root directory of the assembly. For example, "log" will put the specified files in the log directory.
includes When <include> subelements are present, they define a set of files and directory to include. If none is present, then <includes> represents all valid values.
excludes When <exclude> subelements are present, they define a set of files and directory to exclude. If none is present, then <excludes> represents no exclusions.
fileMode Similar to a UNIX permission, sets the file mode of the files included. Format: (User)(Group)(Other) where each component is a sum of Read = 4, Write = 2, and Execute = 1. For example, the value 0644 translates to User read-write, Group and Other read-only. (more on unix-style permissions)
directoryMode Similar to a UNIX permission, sets the directory mode of the directories included. Format: (User)(Group)(Other) where each component is a sum of Read = 4, Write = 2, and Execute = 1. For example, the value 0755 translates to User read-write, Group and Other read-only. (more on unix-style permissions)

file

A file allows individual file inclusion with the option to change the destination filename not supported by fileSets.

Element Description
source Sets the absolute or relative path from the module's directory of the file to be included in the assembly.
outputDirectory Sets the output directory relative to the root of the root directory of the assembly. For example, "log" will put the specified files in the log directory.
destName Sets the destination filename in the outputDirectory. Default is the same name as the source's file.
fileMode Similar to a UNIX permission, sets the file mode of the files included. Format: (User)(Group)(Other) where each component is a sum of Read = 4, Write = 2, and Execute = 1. For example, the value 0644 translates to User read-write, Group and Other read-only. (more on unix-style permissions)
lineEnding Sets the line-endings of the files in this file. Valid values are:
  • "keep" - Preserve all line endings
  • "unix" - Use Unix-style line endings
  • "lf" - Use a single line-feed line endings
  • "dos" - Use DOS-style line endings
  • "crlf" - Use Carraige-return, line-feed line endings
filtered Sets whether to determine if the file is filtered. The default value is false.

dependencySet

A dependencySet allows inclusion and exclusion of project dependencies in the assembly.

Element Description
outputFileNameMapping Sets the mapping pattern for all dependencies included in this assembly. Default is ${artifact.artifactId}-${artifact.version}${dashClassifier?}.${artifact.extension}. If the artifact doesn't have a classifier, that part of the pattern will be left off. (Since 2.2-beta-2; 2.2-beta-1 uses ${artifactId}-${version}${dashClassifier?}.${extension}) The default value is ${artifact.artifactId}-${artifact.version}${dashClassifier?}.${artifact.extension}.
unpack If set to true, this property will unpack all dependencies into the specified output directory. When set to false dependencies will be includes as archives (jars). Default value is false. The default value is false.
unpackOptions Allows the specification of includes and excludes, along with filtering options, for items unpacked from a dependency artifact.
scope Sets the dependency scope for this dependencySet. Default scope value is "runtime". The default value is runtime.
useProjectArtifact Determines whether the artifact produced during the current project's build should be included in this dependency set. Default value is true, for backward compatibility. (Since 2.2) The default value is true.
useProjectAttachments Determines whether the attached artifacts produced during the current project's build should be included in this dependency set. Default value is false. (Since 2.2) The default value is false.
useTransitiveDependencies Determines whether transitive dependencies will be included in the processing of the current dependency set. If true, includes/excludes/useTransitiveFiltering will apply to transitive dependency artifacts in addition to the main project dependency artifacts. If false, useTransitiveFiltering is meaningless, and includes/excludes only affect the immediate dependencies of the project. By default, this value is true. (Since 2.2) The default value is true.
useTransitiveFiltering Determines whether the include/exclude patterns in this dependency set will be applied to the transitive path of a given artifact. If true, and the current artifact is a transitive dependency brought in by another artifact which matches an inclusion or exclusion pattern, then the current artifact has the same inclusion/exclusion logic applied to it as well. By default, this value is false, in order to preserve backward compatibility with version 2.1. This means that includes/excludes only apply directly to the current artifact, and not to the transitive set of artifacts which brought it in. (Since 2.2) The default value is false.
useStrictFiltering When specified as true, any include/exclude patterns which aren't used to filter an actual artifact during assembly creation will cause the build to fail with an error. This is meant to highlight obsolete inclusions or exclusions, or else signal that the assembly descriptor is incorrectly configured. The default value is false.
useDefaultExcludes Whether standard exclusion patterns, such as those matching CVS and Subversion metadata files, should be used when calculating the files affected by this set. For backward compatibility, the default value is true. The default value is true.
outputDirectory Sets the output directory relative to the root of the root directory of the assembly. For example, "log" will put the specified files in the log directory.
includes When <include> subelements are present, they define a set of files and directory to include. If none is present, then <includes> represents all valid values.
excludes When <exclude> subelements are present, they define a set of files and directory to exclude. If none is present, then <excludes> represents no exclusions.
fileMode Similar to a UNIX permission, sets the file mode of the files included. Format: (User)(Group)(Other) where each component is a sum of Read = 4, Write = 2, and Execute = 1. For example, the value 0644 translates to User read-write, Group and Other read-only. (more on unix-style permissions)
directoryMode Similar to a UNIX permission, sets the directory mode of the directories included. Format: (User)(Group)(Other) where each component is a sum of Read = 4, Write = 2, and Execute = 1. For example, the value 0755 translates to User read-write, Group and Other read-only. (more on unix-style permissions)

unpackOptions

Specifies options for including/excluding/filtering items extracted from an archive.

Element Description
includes Set of patterns for matching items to be included from an archive as it is unpacked.
excludes Set of patterns for matching items to be excluded from an archive as it is unpacked.
filtered Whether to filter symbols in the files as they are unpacked from the archive, using properties from the build configuration. The default value is false.

repository

Defines a Maven repository to be included in the assembly.

Element Description
includeMetadata If set to true, this property will trigger the creation of repository metadata which will allow the repository to be used as a functional remote repository. The default value is false.
groupVersionAlignments Align a group to a version or an individual artifact.
scope Specifies the scope for artifacts included in this repository. Default scope value is "runtime". The default value is runtime.
useStrictFiltering When specified as true, any include/exclude patterns which aren't used to filter an actual artifact during assembly creation will cause the build to fail with an error. This is meant to highlight obsolete inclusions or exclusions, or else signal that the assembly descriptor is incorrectly configured. The default value is false.
useDefaultExcludes Whether standard exclusion patterns, such as those matching CVS and Subversion metadata files, should be used when calculating the files affected by this set. For backward compatibility, the default value is true. The default value is true.
outputDirectory Sets the output directory relative to the root of the root directory of the assembly. For example, "log" will put the specified files in the log directory.
includes When <include> subelements are present, they define a set of files and directory to include. If none is present, then <includes> represents all valid values.
excludes When <exclude> subelements are present, they define a set of files and directory to exclude. If none is present, then <excludes> represents no exclusions.
fileMode Similar to a UNIX permission, sets the file mode of the files included. Format: (User)(Group)(Other) where each component is a sum of Read = 4, Write = 2, and Execute = 1. For example, the value 0644 translates to User read-write, Group and Other read-only. (more on unix-style permissions)
directoryMode Similar to a UNIX permission, sets the directory mode of the directories included. Format: (User)(Group)(Other) where each component is a sum of Read = 4, Write = 2, and Execute = 1. For example, the value 0755 translates to User read-write, Group and Other read-only. (more on unix-style permissions)

groupVersionAlignment

Defines a Maven repository to be included in the assembly.

Element Description
id The groupId for which you want to align the versions.
version The version you want to align this group to.
excludes Artifact Ids of the artifacts you want excluded from version alignment.

containerDescriptorHandler

Configures a filter for files headed into the assembly archive, to enable aggregation of various types of descriptor fragments, such as components.xml, web.xml, etc.

Element Description
handlerName The handler's plexus role-hint, for lookup from the container.