# Apache UIMA PEAR Packaging Maven Plugin Documentation

## Overview

This plugin supports creating PEAR packages using Maven.

The PEAR (Processing Engine ARchive) file format is designed to make UIMA analysis components easily consumable for other users, and is the preferred packaging format for UIMA analysis components. This format allows applications and tools to manage UIMA analysis components automatically for verification, deployment, invocation and testing.

## Using the PEAR Packaging Plugin

### Specifying the PEAR Packaging Pluging

To use the PEAR Packaging Plugin within a Maven build, the plugin must be added to the plugins section of the POM as shown below:

    <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> <!--this is the default, can be omitted-->
            <configuration>
            <!-- where you specify details of the thing being packaged -->
              <classpath>
                <!-- PEAR file component classpath settings -->
                <!-- Jars in the $main_root/lib are automatically put into the
                     classpath and do not need to be listed here -->
                $main_root/lib-alternative/sample.jar
              </classpath>

              <mainComponentDesc>
                <!-- PEAR file main component descriptor -->
                desc/${project.artifactId}.xml
              </mainComponentDesc>

              <componentId>
                <!-- PEAR file component ID -->
                ${project.artifactId}
              </componentId>

              <datapath>
                <!-- PEAR file UIMA datapath settings -->
                $main_root/resources
              </datapath>

            </configuration>
            <goals>
              <goal>package</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      ...
     </plugins>
    </build>

To configure the plugin with the specific settings of a PEAR package, the `<configuration>` 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:

- `<classpath>` - 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. The classpath element can be omitted if the component Jar artifact is the only classpath entry.

  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.

- `<mainComponentDesc>` - 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 `desc/${project.artifactId}.xml`.

- `<componentID>` - This element specifies the PEAR package component ID. A good default to use is `${project.artifactId}`.

- `<datapath>` - This element specifies the PEAR package UIMA datapath settings. If no datapath settings are necessary, this element can be omitted.

  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.

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.

- `<mainComponentDir>` - This element specifies the main component directory where the UIMA nature is applied. By default this parameter points to the project root directory - ${basedir}.

- `<targetDir>` - 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

### Automatically including dependencies

The PEAR Packaging Plugin does not take care of automatically adding its dependencies to the PEAR archive. However, this behavior can be manually added. The following two build plugins hook into the build cycle in order to make sure all runtime dependencies end up being packaged into the final PEAR file.

While the dependencies will be automatically included in the PEAR file using this procedure, you still need to add them manually to the PEAR classpath, using the `<classpath>` element described above.

The first uses the `maven-dependency-plugin` to resolve the runtime dependencies of the PEAR into the `lib` folder, which is where the PEAR packaging plugin expects them. The version is stripped from the file names of the dependencies so it is not necessary to adapt the PEAR classpath when changing the version of a dependency.

    <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>
          <stripVersion>true</stripVersion>
          <outputDirectory>${basedir}/lib</outputDirectory>
          <overWriteReleases>false</overWriteReleases>
          <overWriteSnapshots>true</overWriteSnapshots>
          <includeScope>runtime</includeScope>
         </configuration>
        </execution>
       </executions>
      </plugin>
      ...
     </plugins>
    </build>

The second hooks into the `clean` phase of the build phase. It deletes the `lib` folder again.

The `lib` folder is automatically filled 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.

    <build>
     <plugins>
      ...
      <plugin>
       <artifactId>maven-antrun-plugin</artifactId>
       <executions>
        <!-- Clean the libraries after packaging -->
        <execution>
         <id>CleanLib</id>
         <phase>clean</phase>
         <configuration>
          <tasks>
           <delete dir="lib" deleteOnExit="true" quiet="true"
                   failOnError="false">
            <fileset dir="lib" includes="*.jar"/>
           </delete>
          </tasks>
         </configuration>
         <goals>
          <goal>run</goal>
         </goals>
        </execution>
       </executions>
      </plugin>
      ...
     </plugins>
    </build>

## Installing The PEAR Packaging Plugin

If you specify the Apache Incubating Repository as one of the repositories for your maven configuration, then the `uima-pear-maven-plugin.jar` should be automatically fetched when needed. This is typically specified in the .settings file or in a parent POM, using this format:

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

Otherwise, the `uima-pear-maven-plugin.jar` file must be manually installed into your local repository. See . The information you need to do this is:

- `-DgroupId=org.apache.uima`

- `-DartifactId=PearPackagingMavenPlugin`

- `-Dversion=2.3.1` (change this to the version you want)

- `-Dpackaging=jar`

- `-DgeneratePom=true`

## Building the PEAR Packaging Plugin From Source

The plugin code is available in the Apache subversion repository at: . Use the following command line to build it (you will need the Maven build tool, available from Apache):

    #PearPackagingMavenPlugin> mvn install

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: `2.3.1`

    [INFO] Installing
    /code/apache/PearPackagingMavenPlugin/target/
    PearPackagingMavenPlugin-2.3.1.jar
    to
    /maven-repository/repository/org/apache/uima/PearPackagingMavenPlugin/
    2.3.0-incubating/
    PearPackagingMavenPlugin-2.3.1.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] --------------------------------------------------------------