Apache UIMA PEAR Packaging Maven Plugin Documentation

Authors: The Apache UIMA Development Community

Apache UIMA Sandbox

Version 2.2.2

Incubation Notice and Disclaimer. Apache UIMA is an effort undergoing incubation at the Apache Software Foundation (ASF). Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.

License and Disclaimer. The ASF licenses this documentation to you under the Apache License, Version 2.0 (the "License"); you may not use this documentation except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, this documentation and its contents are distributed under the License 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.

Trademarks. All terms mentioned in the text that are known to be trademarks or service marks have been appropriately capitalized. Use of such terms in this book should not be regarded as affecting the validity of the the trademark or service mark.


Table of Contents

Overview
1. Installing The PEAR Packaging Plugin From Source
2. Installing The PEAR Packaging Plugin Using The Binary
3. Using the PEAR Packaging Plugin
3.1. Calling The PEAR Packaging Plugin

Overview

To make UIMA analysis components easily consumable for other users, UIMA defines the PEAR (Processing Engine ARchive) file format. This allows applications and tools to manage UIMA analysis components automatically for verification, deployment, invocation and testing. So far the PEAR file format is the desired output format for an UIMA analysis component. With the PEAR packaging Maven plugin it is possible to create such a PEAR package for the analysis component automatically during the Maven artifact build.

Chapter 1. Installing The PEAR Packaging Plugin From Source

The PEAR packaging Maven plugin is modeled as custom plugin for the Maven build system. To use it, the plugin must be available in the local Maven repository. So far the plugin is not available by default when building the UIMA SDK, so it have to be built manually using the provided Maven build. The plugin code is available in the Apache subversion repository at:

After downloading the code to the Apache UIMA build environment just call the provided maven build in the main directory of the PEAR Packaging plugin as shown in the listing below.

#PearPackagingMavenPlugin> mvn install

After successfully building the plugin is available in the local Maven repository and can be used in other Maven artifact builds from now. To integrate the plugin into other builds it is necessary to know the PEAR Packaging plugin version number as it is available in the Maven repository. 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.2.2-incubating

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

To use the PEAR packaging plugin in a Maven build, it is necessary to add it as dependency to the POM. Important while adding the dependency is the version number of the plugin. With that the correct version of the plugin is used and can be found in the local Maven repository. The version number of the plugin was displayed when installing the PEAR packaging Maven plugin to the Maven repository. The snippet below shows how the plugin dependency is added to the dependencies sections of the POM.

<dependencies>
   ...
   <dependency>
     <groupId>org.apache.uima</groupId>
     <artifactId>PearPackagingMavenPlugin</artifactId>
     <version>2.2.0-incubating-SNAPSHOT</version>
     <scope>package</scope>
   </dependency>
   ....
</dependencies>

Chapter 2. Installing The PEAR Packaging Plugin Using The Binary

It is also possible to use the binary version of the plugin. In that case the uima-pear-maven-plugin.jar file must be added to the dependency set of your POM like for example:

<dependencies>
   ...
   <dependency>
     <groupId>org.apache.uima</groupId>
     <artifactId>PearPackagingMavenPlugin</artifactId>
     <version>2.2.2-incubating</version>
     <scope>system</scope>
     <systemPath>${basedir}/lib/uima-pear-maven-plugin.jar</systemPath>
   </dependency>
   ....
</dependencies>

Chapter 3. Using the PEAR Packaging Plugin

3.1. Calling The PEAR Packaging Plugin

To call 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>
    <extensions>true</extensions>
    <executions>
      <execution>
        <phase>package</phase>
        <configuration>
          
          <classpath>
            <!-- PEAR file component classpath settings -->
            $main_root/lib/sample.jar
          </classpath>
          
          <mainComponentDesc>
            <!-- PEAR file main component descriptor -->
            desc/RegExAnnotator.xml
          </mainComponentDesc>
          
          <componentId>
            <!-- PEAR file component ID -->
            SampleComponentID
          </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 provided 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 that are necessary to start up the PEAR component. The jar artifact that is built during the current Maven build is automatically added to the PEAR classpath settings and do not have to be added manually. The classpath element can be removed if the component jar artifact is the only classpath entry.

    Note

    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.

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

  • <componentID> - This element specifies the PEAR package component ID.

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

    Note

    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