uimaj-2.3.0-incubating/uima-docbooks/src/docbook/tools/tools.pear.packager.maven.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY imgroot "../images/tools/tools.pear.packager.maven/" >
<!ENTITY % uimaents SYSTEM "../entities.ent" >  
%uimaents;
]>
<!--
  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.
-->

  <chapter id="ugr.tools.pear.packager.maven.plugin.usage">
    <title>The PEAR Packaging Maven Plugin</title>
    <para>
      UIMA includes a Maven plugin that supports creating PEAR packages using Maven. 
      When configured for a project, it assumes that the project has the PEAR layout, 
      and will copy the standard directories that are part of a PEAR structure under the
      project root into the PEAR, excluding files that start with a period (".").  
      It also will put the Jar that is built for the project
      into the lib/ directory and include it first on the generated classpath. 
    </para>
    
    <para>
      The classpath that is generated for this includes the artifact's Jar first, any user specified
      entries second (in the order they are specified), and finally, entries for all Jars 
      found in the lib/ directory (in some arbitrary order).
    </para>
    
    <section id="ugr.tools.pear.packager.maven.plugin.usage.configure">
      <title>Specifying the PEAR Packaging Maven Plugin</title>
      
    <para>
      To use the PEAR Packaging Plugin within a Maven build, 
      the plugin must be added to the plugins section of the 
      Maven POM as shown below:
    </para>
    <para>
    <programlisting><![CDATA[<build>
 <plugins>
  ...
  <plugin>
    <groupId>org.apache.uima</groupId>
    <artifactId>PearPackagingMavenPlugin</artifactId>
    
    <!-- if version is omitted, then --> 
    <!-- version is inherited from parent's pluginManagement section -->
    <!-- otherwise, include a version element here --> 
    
    <!-- says to load Maven extensions 
         (such as packaging and type handlers) from this plugin -->
    <extensions>true</extensions>  
    <executions>
      <execution>
        <phase>package</phase>
        <!-- where you specify details of the thing being packaged -->
        <configuration>  
          
          <classpath>
            <!-- PEAR file component classpath settings -->
            $main_root/lib/sample.jar
          </classpath>
          
          <mainComponentDesc>
            <!-- PEAR file main component descriptor -->
            desc/${artifactId}.xml
          </mainComponentDesc>
          
          <componentId>
            <!-- PEAR file component ID -->
            ${artifactId}
          </componentId>
          
          <datapath>
            <!-- PEAR file UIMA datapath settings -->
            $main_root/resources
          </datapath>
          
        </configuration>
        <goals>
          <goal>package</goal>
        </goals>
      </execution>
    </executions>
  </plugin>
  ...
 </plugins>
</build>
]]></programlisting>
    </para>
    
    <para>
      To configure the plugin with the specific settings of a PEAR package, the 
      <code>&lt;configuration></code> element section is used. This sections contains all parameters 
      that are used by the PEAR Packaging Plugin to package the right content and set the specific PEAR package settings.
      The details about each parameter and how it is used is shown below:
    </para>
    <para>
      <itemizedlist>
        <listitem>
          <para>
            <code>&lt;classpath></code>
              - This element specifies the classpath settings for the 
              PEAR component. The Jar artifact that is built during the current Maven build is 
              automatically added to the PEAR classpath settings and does not have to be added manually.
              In addition, all Jars in the lib directory and its subdirectories will be added to the
              generated classpath when the PEAR is installed.  
          </para>
          <note>
            <para>Use $main_root variables to refer to libraries inside 
              the PEAR package. For more details about PEAR packaging please refer to the 
              Apache UIMA PEAR documentation.</para>
          </note>
        </listitem>
        <listitem>
          <para>
            <code>&lt;mainComponentDesc></code>
              - This element specifies the relative path to the main component descriptor 
              that should be used to run the PEAR content. The path must be relative to the 
              project root. A good default to use is <code>desc/${artifactId}.xml</code>.
          </para>
        </listitem>
        <listitem>
          <para>
            <code>&lt;componentID></code>
              - This element specifies the PEAR package component ID. A good default
              to use is <code>${artifactId}</code>.
          </para>
        </listitem>
        <listitem>
          <para>
            <code>&lt;datapath></code>
              - This element specifies the PEAR package UIMA datapath settings.
              If no datapath settings are necessary, this element can be omitted. 
          </para>
          <note>
            <para>Use $main_root variables to refer libraries inside 
              the PEAR package. For more details about PEAR packaging please refer to the 
              Apache UIMA PEAR documentation.</para>
          </note>
        </listitem>
      </itemizedlist>
    </para>
    <para>
      For most Maven projects it is sufficient to specify the parameters described above. In some cases, for 
      more complex projects, it may be necessary to specify some additional configuration 
      parameters. These parameters are listed below with the default values that are used if they are not 
      added to the configuration section shown above.
    </para>
    <para>
      <itemizedlist>
        <listitem>
          <para>
            <code>&lt;mainComponentDir></code>
              - This element specifies the main component directory where the UIMA
              nature is applied. By default this parameter points to the project root 
              directory - ${basedir}.  
          </para>
        </listitem>
        <listitem>
          <para>
            <code>&lt;targetDir></code>
              - This element specifies the target directory where the result of the plugin 
              are written to. By default this parameters points to the default Maven output 
              directory - ${basedir}/target
          </para>
        </listitem>
      </itemizedlist>
    </para>
    </section>
    
    <section id="ugr.tools.pear.packager.maven.plugin.usage.dependencies">
      <title>Automatically including dependencies</title>

      <para>
        A key concept in PEARs is that they allow specifying other Jars in the classpath.
        You can optionally include these Jars within the PEAR package.
      </para>
      <para>
          The PEAR Packaging Plugin does not take care of automatically
          adding these Jars (that the PEAR might depend on) to the PEAR archive. 
          However, this
          behavior can be manually added to your Maven POM. 
          The following two build plugins
          hook into the build cycle and insure that all runtime
          dependencies are included in the PEAR file.
      </para>

      
        <para>
        The dependencies will be automatically included in the 
        PEAR file using this procedure; the pear install process also will automatically
        adds all files in the lib directory (and sub directories) to the 
        classpath.
        </para>
      

      <para>
        The <code>maven-dependency-plugin</code>
        copies the runtime dependencies of the PEAR into the
        <code>lib</code> folder, which is where the PEAR packaging
        plugin expects them.  
      </para>

        <programlisting><![CDATA[<build>
 <plugins>
  ...
  <plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-dependency-plugin</artifactId>
   <executions>
    <!-- Copy the dependencies to the lib folder for the PEAR to copy -->
    <execution>
     <id>copy-dependencies</id>
     <phase>package</phase>
     <goals>
      <goal>copy-dependencies</goal>
     </goals>
     <configuration>
      <outputDirectory>${basedir}/lib</outputDirectory>
      <overWriteSnapshots>true</overWriteSnapshots>
      <includeScope>runtime</includeScope>
     </configuration>
    </execution>
   </executions>
  </plugin>
  ...
 </plugins>
</build>
]]></programlisting>

      <para>
        The second Maven plug-in hooks into the <code>clean</code>
        phase of the build life-cycle, and deletes the
        <code>lib</code> folder.
      </para>

      <note>
        <para>
          With this approach, the <code>lib</code> folder is 
          automatically created, populated, and removed
          during the build process. Therefore it should not go into
          the source control system and neither should you
          manually place any jars in there.
        </para>
      </note>
      
        <programlisting><![CDATA[<build>
 <plugins>
  ...
  <plugin>
   <artifactId>maven-antrun-plugin</artifactId>
   <executions>
    <!-- Clean the libraries after packaging -->
    <execution>
     <id>CleanLib</id>
     <phase>clean</phase>
     <configuration>
      <tasks>
       <delete quiet="true" 
               failOnError="false">
        <fileset dir="lib" includes="**/*.jar"/>
       </delete>
      </tasks>
     </configuration>
     <goals>
      <goal>run</goal>
     </goals>
    </execution>                      
   </executions>
  </plugin>
  ...
 </plugins>
</build>
]]></programlisting>

    </section>

  <section id="ugr.tools.pear.packager.maven.plugin.install">
    <title>Installing The PEAR Packaging Plugin</title>

    <para>If you specify the Apache Incubating Repository as one of the repositories 
      for your maven configuration, then the <code>uima-pear-maven-plugin.jar</code> 
      will be automatically fetched when needed.  
      This is typically specified in the POM, the Maven .settings file or in 
      a parent POM, using this format:
    </para>
    <programlisting><![CDATA[<repositories>
  <repository>
    <id>apache-incubating-repository</id>
    <url>http://people.apache.org/repo/m2-incubating-repository</url>
    <releases>
      <!-- never: because artifacts are never updated in the repo -->
      <updatePolicy>never</updatePolicy> 
    </releases>
  </repository>
</repositories>]]></programlisting>

    <para>
      Otherwise, the 
      <code>uima-pear-maven-plugin.jar</code> file must be manually installed into your local
      repository.  See <ulink url="http://maven.apache.org/general.html#importing-jars"/>.
      The information you need to do this is:
      <itemizedlist spacing="compact">
        <listitem><para><code>-DgroupId=org.apache.uima</code></para></listitem>
        <listitem><para><code>-DartifactId=PearPackagingMavenPlugin</code></para></listitem>
        <listitem><para><code>-Dversion=2.3.0-incubating</code>  (change this to the version you want)</para></listitem>
        <listitem><para><code>-Dpackaging=jar</code></para></listitem>
        <listitem><para><code>-DgeneratePom=true</code></para></listitem>
      </itemizedlist>
    </para>
  </section>

  <section id="ugr.tools.pear.packager.maven.plugin.commandline">
    <title>Running from the command line</title>
    <para>
      The pear packager can be run as a maven command.  To enable this, you have to add the following to your
      maven settings file:
      <programlisting><![CDATA[<settings>
  ...
  <pluginGroups>
    <pluginGroup>org.apache.uima</pluginGroup>
  </pluginGroups>]]></programlisting>
      To invoke the pear packager using maven, use the command:
      <programlisting><![CDATA[mvn uima-pear:package <parameters...>]]></programlisting>
      The settings are the same ones used in the configuration above, specified as -D variables 
      where the variable name is pear.parameterName.
      For example:
      <programlisting><![CDATA[mvn uima-pear:package -Dpear.mainComponentDesc=desc/mydescriptor.xml
                      -Dpear.componentId=foo]]></programlisting> 
    </para>
  </section>
  
  <section id="ugr.tools.pear.packager.maven.plugin.install.src">
    <title>Building the PEAR Packaging Plugin From Source</title>
    <para>
      The plugin code is available in the Apache
      subversion repository at:
      <ulink url="http://svn.apache.org/repos/asf/incubator/uima/uimaj/trunk/PearPackagingMavenPlugin"/>.
      Use the following command line to build it (you will need the Maven build tool, available from Apache):
    </para>
    <para>
    <programlisting><![CDATA[#PearPackagingMavenPlugin> mvn install]]></programlisting>
    </para>
    <para>
      This maven command will build the tool and install it in your local maven repository, 
      making it available for use by other maven POMs.  The plugin version number
      is displayed at the end of the Maven build as shown in the example below. For this example, the plugin 
      version number is: <code>2.3.0-incubating</code> 
    </para>
    <para>
    <programlisting><![CDATA[[INFO] Installing 
/code/apache/PearPackagingMavenPlugin/target/
PearPackagingMavenPlugin-2.3.0-incubating.jar 
to 
/maven-repository/repository/org/apache/uima/PearPackagingMavenPlugin/
2.3.0-incubating/
PearPackagingMavenPlugin-2.3.0-incubating.jar
[INFO] [plugin:updateRegistry]
[INFO] --------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] --------------------------------------------------------------
[INFO] Total time: 6 seconds
[INFO] Finished at: Tue Nov 13 15:07:11 CET 2007
[INFO] Final Memory: 10M/24M
[INFO] --------------------------------------------------------------]]></programlisting>
    </para>
  </section>
</chapter>