src/site/apt/examples/single/using-components.apt.vm

 ------
  Using Component Descriptors
 ------
  Edwin Punzalan
 ------
  24-July-2006
 ------

~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html

Using Component Descriptors

* Introduction

  Suppose you have a project which will be distributed in two forms: one for
  use with appserver A and another for appserver B. And as customization for
  these two servers, you need to exclude some dependencies which are not used
  by the appserver you will be distributing.

  <<NOTE:>> <Although putting \<excludes\> inside \<dependencySets\> may provide
  the result we want, it is not recommended because if a new appserver becomes
  available, you will have to maintain the excludes of the other distributions
  to exclude dependencies meant for the new appserver.>

  This example demonstrate the use of \<componentDescriptors\>, more information
  can be found {{{../../assembly.html}here}}.

* The Assembly Descriptors

  First, let's write the assembly descriptor for appserver A distribution. It
  should like this:

+-----
<assembly xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
  <id>appserverA</id>
  <formats>
    <format>zip</format>
  </formats>
  <dependencySets>
    <dependencySet>
      <outputDirectory>/lib</outputDirectory>
      <includes>
        <include>application:logging</include>
        <include>application:core</include>
        <include>application:utils</include>
        <include>application:appserverA</include>
      </includes>
    </dependencySet>
  </dependencySets>
</assembly>
+-----

  The assembly descriptor for appserver B distribution would then be similar:

+-----
<assembly xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
  <id>appserverB</id>
  <formats>
    <format>zip</format>
  </formats>
  <dependencySets>
    <dependencySet>
      <outputDirectory>/lib</outputDirectory>
      <includes>
        <include>application:logging</include>
        <include>application:core</include>
        <include>application:utils</include>
        <include>application:appserverB</include>
      </includes>
    </dependencySet>
  </dependencySets>
</assembly>
+-----

  From the two descriptors shown, we can say that there are three artifacts
  common for both, thus we separate them into a common component descriptor
  and save it as <<<src/assembly/component.xml>>>.  Its contents would
  be:

+-----
<component>
  <dependencySets>
    <dependencySet>
      <outputDirectory>/lib</outputDirectory>
      <includes>
        <include>application:logging</include>
        <include>application:core</include>
        <include>application:utils</include>
      </includes>
    </dependencySet>
  </dependencySets>
</component>
+-----

  Then the final assembly descriptor for the appserver A would be:

+-----
<assembly xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
  <id>appserverA</id>
  <formats>
    <format>zip</format>
  </formats>
  <componentDescriptors>
    <componentDescriptor>src/assembly/component.xml</componentDescriptor>
  </componentDescriptors>
  <dependencySets>
    <dependencySet>
      <outputDirectory>/lib</outputDirectory>
      <includes>
        <include>application:appserverA</include>
      </includes>
    </dependencySet>
  </dependencySets>
</assembly>
+-----

  And the corresponding assembly descriptor for the appserver B then would be:

+-----
<assembly xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
  <id>appserverB</id>
  <formats>
    <format>zip</format>
  </formats>
  <componentDescriptors>
    <componentDescriptor>src/assembly/component.xml</componentDescriptor>
  </componentDescriptors>
  <dependencySets>
    <dependencySet>
      <outputDirectory>/lib</outputDirectory>
      <includes>
        <include>application:appserverB</include>
      </includes>
    </dependencySet>
  </dependencySets>
</assembly>
+-----

* The POM

  Now we should update the POM configuration of the project for the Assembly
  Plugin, which should look like:

+-----
<project>
  [...]
  <build>
    [...]
    <plugins>
      [...]
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <descriptors>
            <descriptor>src/assembly/appserverA-assembly.xml</descriptor>
            <descriptor>src/assembly/appserverB-assembly.xml</descriptor>
          </descriptors>
        </configuration>
      </plugin>
   [...]
</project>
+-----

* Creating The Distributions

  Since we didn't configure the assembly plugin to always generate the
  configured assemblies during the project's normal build lifecycle, we create
  the distributions by:

+-----
  mvn assembly:single
+-----