You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by mb...@apache.org on 2008/06/20 14:26:20 UTC
svn commit: r669872 - in /incubator/uima/site/trunk/uima-website:
docs/doc-uima-pears.html docs/images/getting-started/pear-structure.jpg
xdocs/doc-uima-pears.xml
Author: mbaessler
Date: Fri Jun 20 05:26:20 2008
New Revision: 669872
URL: http://svn.apache.org/viewvc?rev=669872&view=rev
Log:
UIMA-1083
add first version of UIMA Getting Started "Working with PEARs"
https://issues.apache.org/jira/browse/UIMA-1083
Added:
incubator/uima/site/trunk/uima-website/docs/doc-uima-pears.html
incubator/uima/site/trunk/uima-website/docs/images/getting-started/pear-structure.jpg (with props)
incubator/uima/site/trunk/uima-website/xdocs/doc-uima-pears.xml
Added: incubator/uima/site/trunk/uima-website/docs/doc-uima-pears.html
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/docs/doc-uima-pears.html?rev=669872&view=auto
==============================================================================
--- incubator/uima/site/trunk/uima-website/docs/doc-uima-pears.html (added)
+++ incubator/uima/site/trunk/uima-website/docs/doc-uima-pears.html Fri Jun 20 05:26:20 2008
@@ -0,0 +1,558 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+
+<!--
+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.
+-->
+
+
+<!-- Content Stylesheet for Site -->
+
+
+<!-- start the processing -->
+ <!-- ====================================================================== -->
+ <!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->
+ <!-- Main Page Section -->
+ <!-- ====================================================================== -->
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
+
+ <meta name="author" value="
+ UIMA Team
+ ">
+ <meta name="email" value="uima-dev@incubator.apache.org">
+
+
+
+
+
+
+
+ <title>Apache UIMA - Getting Started: Working With PEARs</title>
+ </head>
+
+ <body bgcolor="#ffffff" text="#000000" link="#525D76">
+ <table border="0" width="100%" cellspacing="0">
+ <!-- TOP IMAGE -->
+ <tr>
+ <td align='LEFT'>
+ <td align="left">
+<a href="http://incubator.apache.org/"><img src="./images/apache-incubator-logo.png" alt="Apache UIMA" border="0"/></a>
+</td>
+ </td>
+ <td align='CENTER'>
+ <td width="80%" align="center" valign="bottom" bgcolor="#ffffff">
+ <font color="#625972" size="+3" face="arial,helvetica,sanserif">
+ <b>Getting Started: Working With PEARs</b>
+</font>
+</td>
+ </td>
+ <td align='RIGHT'>
+ <td align="left">
+<img src="./images/UIMA_banner.png" alt="UIMA project logo" border="0"/>
+</td>
+ </td>
+ </tr>
+ </table>
+ <table border="0" width="100%" cellspacing="4">
+ <tr><td colspan="2">
+ <hr noshade="" size="1"/>
+ </td></tr>
+
+ <tr>
+ <!-- LEFT SIDE NAVIGATION -->
+ <td width="20%" valign="top" nowrap="true">
+
+ <!-- special ACon Logo - leave here for next time
+ <a href="http://apachecon.com/2005/US/">
+ <img src="http://apache.org/images/ac2005us_blue_125x125.jpg" height="125"
+ width="125" border="0" alt="ApacheCon US 2005" />
+ </a> -->
+
+ <!-- regular menu -->
+
+
+ <!-- ============================================================ -->
+
+ <p><strong>General</strong></p>
+ <ul>
+ <li> <a href="./index.html">Home</a>
+</li>
+ <li> <a href="./news.html">News</a>
+</li>
+ <li> <a href="./documentation.html">Documentation</a>
+</li>
+ <li> <a href="./downloads.cgi">Downloads</a>
+</li>
+ <li> <a href="./license.html">License</a>
+</li>
+ <li> <a href="http://www.apache.org/">ASF</a>
+</li>
+ <li> <a href="http://apache.org/foundation/thanks.html">Thanks</a>
+</li>
+ <li> <a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
+</li>
+ </ul>
+ <p><strong>Community</strong></p>
+ <ul>
+ <li> <a href="./project-guidelines.html">Project Guidelines</a>
+</li>
+ <li> <a href="./contribution-policy.html">Contribution Policies</a>
+</li>
+ <li> <a href="./get-involved.html">Get Involved</a>
+</li>
+ <li> <a href="./team-list.html">Project Team</a>
+</li>
+ <li> <a href="./mail-lists.html">Mailing Lists</a>
+</li>
+ <li> <a href="./faq.html">FAQ</a>
+</li>
+ <li> <a href="http://cwiki.apache.org/UIMA/">Wiki</a>
+</li>
+ <li> <a href="./external-resources.html">External UIMA Resources</a>
+</li>
+ </ul>
+ <p><strong>Development</strong></p>
+ <ul>
+ <li> <a href="./svn.html">Source Code</a>
+</li>
+ <li> <a href="./distribution.html">Creating a Distribution</a>
+</li>
+ <li> <a href="./release.html">Doing a UIMA release</a>
+</li>
+ <li> <a href="./codeConventions.html">Code Conventions</a>
+</li>
+ <li> <a href="http://issues.apache.org/jira/browse/uima ">JIRA</a>
+</li>
+ <li> <a href="./uima-specification.html">UIMA Specification</a>
+</li>
+ <li> <a href="./sandbox.html">Sandbox</a>
+</li>
+ </ul>
+ <p><strong>Conferences</strong></p>
+ <ul>
+ <li> <a href="./gldv07.html">GLDV 2007</a>
+</li>
+ <li> <a href="./lrec08.html">LREC 2008</a>
+</li>
+ </ul>
+ </td>
+ <td width="80%" align="left" valign="top">
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+ <tr><td bgcolor="#726982">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Getting Started: Working With PEARs"><strong>Getting Started: Working With PEARs</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+ The "Getting Started: Working With PEARs"
+ guide should help you to understand what a PEAR (Processing Engine ARchive) file is
+ and how PEARS can easily be used and integrated into UIMA applications.
+ </p>
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+
+
+ <tr><td bgcolor="#9289A2">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="What are UIMA PEAR files"><strong>What are UIMA PEAR files</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+ A PEAR (Processing Engine ARchive) file is the UIMA standard packaging format for UIMA components like
+ analysis engines (annotators) or CAS consumers. The PEAR package can be used to distribute
+ and reuse components within other components or applications. The UIMA framework also provides
+ APIs and methods to automatically deploy, verify and run PEAR packages. So when having a correct
+ packaged PEAR, the application doesn't need any additional information or any manual deployed settings to
+ run the PEAR package.
+ </p>
+ <p>
+ To guarantee these characteristics, each PEAR package has the same internal
+ structure as shown in the picture below.
+ <table cellpadding="5">
+ <tr>
+ <td>
+ <img src="./images/getting-started/pear-structure.jpg" alt="PEAR file structure" border="0" />
+ </td>
+ <td valign="top">
+ <ul>
+ <li>
+ <p>
+ <b>metadata</b> - The metadata folder contains the PEAR package installation descriptor
+ that contains all the necessary information about the PEAR package.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>desc</b> - The desc folder contains the component descriptor files e.g. analysis engine
+ descriptor files or aggregate analysis engine descriptor files.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>src</b> - The src folder contains the component source (if it is packaged).
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>bin</b> - The bin folder contains the compiled classes and script files.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>lib</b> - The lib folder contains dependent jar files and libraries.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>doc</b> - The doc folder contains the component documentation materials.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>data</b> - The data folder contains some test or example data files.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>conf</b> - The conf folder contains some component configuration files.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>resources</b> - The resources folder contains the component resources and dependencies.
+ </p>
+ </li>
+ </ul>
+ </td>
+ </tr>
+ </table>
+ </p>
+ <p>
+ The most important file in a PEAR package is the installation descriptor (metadata/install.xml) that contains
+ all the necessary information about the PEAR package. It it used to install and run the PEAR package
+ and defines all necessary dependencies and settings. These are for example the ID/name of the PEAR package,
+ Java classpath settings, UIMA datapath settings or the descriptor file that should be used to
+ run the PEAR package component. For more details about the installation descriptor,
+ please refer to the UIMA documentation at
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.2-incubating/docs/html/references/references.html#ugr.ref.pear.installation_descriptor">
+ Documented template for the installation descriptor</a>
+ </p>
+ </blockquote>
+ </td></tr>
+ <tr><td><br/></td></tr>
+ </table>
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+
+
+ <tr><td bgcolor="#9289A2">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Generating PEAR files"><strong>Generating PEAR files</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+ In this section we will discuss how to generate a PEAR package. The UIMA framework distribution provides
+ different possibilities to create PEAR packages. The details are discussed below.
+ </p>
+ <p>
+ A more general thing that should be recognized independent of the PEAR packaging method are the
+ PEAR macros or PEAR variables. The PEAR structure defines different macros or variables, but the most
+ important one is the <code>$main_root</code> macro. When using this macro in the installation descriptor
+ or within a UIMA descriptor it will be substituted with the real PEAR package installation
+ path to the main component root directory after the PEAR package is installed on the target system.
+ For example, this macro should be used to specify the classpath settings for a PEAR component
+ as shown in some of the examples below. This guarantees that in each scenario the classpath settings
+ are interpreted correctly. For more details about PEAR macros or PEAR variables, please refer to the
+ UIMA documentation at
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.2-incubating/docs/html/references/references.html#ugr.ref.pear.installation_descriptor">
+ Documented template for the installation descriptor</a>.
+ </p>
+ <p>
+ <ul>
+ <li>
+ <h4>PearPackaging Eclipse plugin</h4>
+ <p>
+ The PearPackaging Eclipse plugin is automatically installed in your Eclipse environment if you have
+ installed the UIMA Eclipse plugins. The plugin allows you to package a PEAR based on the content of
+ an eclipse project having a UIMA nature. This plugin can for example be used in an analysis engine
+ development environment. I will not give more details here since it
+ is already explained in the <a href="http://incubator.apache.org/uima/doc-uima-annotator.html#Packaging the annotator">
+ Getting Started: Writing My First UIMA Annotator</a> guide.
+ </p>
+ </li>
+ <li>
+ <h4>PearPackaging Ant task</h4>
+ <p>
+ The PEAR packaging Ant task can be used in an Ant build environment to create PEAR packages for UIMA
+ components. The PEAR package content as well as the PEAR package settings can be specified.
+ An example how this can look like is shown below:
+ </p>
+ <p>
+ <table cellpadding="10"><tr><td bgcolor="lightgrey">
+ <pre><!-- PEAR packaging Ant task -->
+<packagePear
+ componentID="SampleAnnotator"
+ mainComponentDesc="desc/mainComponentDesc.xml"
+ classpath="$main_root/pearClasspahtEntry;$main_root/anotherPearClasspahtEntry"
+ datapath="$main_root/resources"
+ mainComponentDir="/home/user/workspace/SampeAnntotator"
+ targetDir="/home/user/pearArchive">
+
+ <envVar name="ENV_VAR_NO1" value="value1"/>
+ <envVar name="ENV_VAR_NO2" value="value2"/>
+
+</packagePear></pre>
+ </td></tr></table>
+ </p>
+ <p>
+ For additional information on how to integrate the PEAR packaging Ant taks, please refer to the
+ <a href="http://svn.apache.org/repos/asf/incubator/uima/sandbox/trunk/PearPackagingAntTask/doc/pdf/PearPackagingAntTaskUserGuide.pdf">
+ PEAR packaging Ant task documentation</a>.
+ </p>
+
+ </li>
+ <li>
+ <h4>PearPackaging Maven plugin</h4>
+ <p>
+ The PEAR packaging Maven plugin can be used in a Maven build environment to create PEAR
+ packages for UIMA component. The PEAR package content as well as the PEAR package settings
+ can be specified. An example how this can look like is shown below:
+ </p>
+ <p>
+ <table cellpadding="10"><tr><td bgcolor="lightgrey">
+ <pre><!-- PEAR packaging Maven plugin -->
+<build>
+ <plugins>
+ ...
+ <plugin>
+ <groupId>org.apache.uima</groupId>
+ <artifactId>PearPackagingMavenPlugin</artifactId>
+ <extensions>true</extensions>
+ <executions>
+ <execution>
+ <phase>package</phase>
+ <configuration>
+ <classpath>$main_root/lib/sample.jar</classpath>
+ <mainComponentDesc>desc/${artifactId}.xml</mainComponentDesc>
+ <componentId>${artifactId}</componentId>
+ <datapath>$main_root/resources</datapath>
+ </configuration>
+ <goals>
+ <goal>package</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ ...
+ </plugins>
+</build></pre>
+ </td></tr></table>
+ </p>
+ <p>
+ For additional information how to integrate the PEAR packaging Maven plugin, please refer to the
+ <a href="http://svn.apache.org/repos/asf/incubator/uima/sandbox/trunk/PearPackagingMavenPlugin/doc/pdf/PearPackagingMavenPluginUserGuide.pdf">
+ PEAR packaging Maven plugin documentation</a>.
+ </p>
+ </li>
+ <li>
+ <h4>PearPackaging command line</h4>
+ <p>
+ The PearPackaging command line can be used if script files should be used to create PEAR packages.
+ Details about how to use the PearPackaging command line is available in the UIMA documentation at
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.2-incubating/docs/html/tools/tools.html#ugr.tools.pear.packager.using_command_line">
+ Using the PEAR command line packager</a>.
+ </p>
+ </li>
+ <li>
+ <h4>PearPackaging API</h4>
+ <p>
+ If there is a need to create PEAR packages out of Java source code, the PEAR packaging
+ API can be used. With the API is either possible to create complete PEAR packages or to create the PEAR
+ packages step by step - first create the installation descriptor and later package the PEAR. Detailed
+ information about the PEAR packaging API is available in the UIMA documentation at
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.2-incubating/docs/html/references/references.html#ugr.ref.pear.packaging_into_1_file">
+ Packaging the PEAR structure into one file</a> and in the
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.2-incubating/docs/api/index.html?org/apache/uima/pear/tools/PackageCreator.html">
+ JavaDocs</a>.
+ </p>
+ </li>
+ </ul>
+ </p>
+ </blockquote>
+ </td></tr>
+ <tr><td><br/></td></tr>
+ </table>
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+
+
+ <tr><td bgcolor="#9289A2">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Installing PEAR files"><strong>Installing PEAR files</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+ But before a component that is packaged as PEAR can be used in an application, the PEAR package
+ must be installed on the target system. During the installation, the package content is extracted
+ and the internal PEAR settings (PEAR macros) are updated with some target system information.
+ This also means that an installed PEAR package cannot be moved to
+ another directory without any internal changes. By default the PEAR packages are not installed directly
+ to the specified installation directory. For each PEAR a subdirectory with the name of the PEAR's ID
+ is created where the PEAR package is installed to. If the PEAR installation directory already exists,
+ the old content is automatically deleted before the new content is installed.
+ </p>
+ <p>
+ To check the most important PEAR settings (classpath, datapath, ...), or to read the settings with an
+ application a <code>setenv.txt</code> file containing all these information is generated in the
+ <code>metadata</code> directory during the installation.
+ </p>
+ <p>
+ After the PEAR file is installed, the installed package is automatically verified using a separate
+ verification step. The verification checks if the installed PEAR package is runnable inside UIMA.
+ </p>
+ <p>
+ Another imported point during the PEAR installation is the generation of the PEAR package descriptor. The
+ PEAR package descriptor is a special UIMA descriptor that can be used to run installed PEAR packages in every
+ UIMA application out of the box. For details about the PEAR descriptor, please refer to the
+ UIMA documentation at
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.2-incubating/docs/html/references/references.html#ugr.ref.pear.specifier">
+ PEAR package descriptor</a>
+ </p>
+ <p>
+ To install a PEAR package you have two possibilities.
+ </p>
+ <p>
+ <ul>
+ <li>
+ <h4>PearInstaller UI</h4>
+ <p>
+ The PearInstaller UI is a standalone Swing application to install PEAR packages.
+ AFter the PEAR package and the install directory is selected, the installaion is
+ performed and the installation and verification results are displayed. Out of the tool
+ it is also possible to test the installed PEAR package directly using the Cas Visual Debugger.
+ For more details about PearInstall, please refer to the UIMA documentation at
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.2-incubating/docs/html/tools/tools.html#ugr.tools.pear.installer">
+ PEAR Installer User's Guide</a>.
+ </p>
+ </li>
+ <li>
+ <h4>PEAR API</h4>
+ <p>
+ The PearInstaller API should be used if you want to integrate the PEAR installation
+ with a custom application. With the PEAR API it is possible to install PEAR packages
+ to a given installation directory and to optional verify the installed packages.
+ Details about the PearInstaller API are available in the UIMA documentation at
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.2-incubating/docs/html/references/references.html#ugr.ref.pear.installing_pear_using_API">
+ Installing a PEAR file using the PEAR APIs</a>.
+ </p>
+ </li>
+ </ul>
+ </p>
+ </blockquote>
+ </td></tr>
+ <tr><td><br/></td></tr>
+ </table>
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+
+
+ <tr><td bgcolor="#9289A2">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Running installed PEAR files"><strong>Running installed PEAR files</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+ The UIMA framework has an integrated PEAR runtime to run installed PEAR packages out of the box.
+ For this, the PEAR runtime makes use of the PEAR's installation descriptor settings.
+ To use the PEAR runtime, the generated
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.2-incubating/docs/html/references/references.html#ugr.ref.pear.specifier">
+ PEAR package descriptor</a> must be used to integrate or run PEAR components. The PEAR package descriptor
+ is generated in the main component root directory of the installed PEAR package during the PEAR installation.
+ As PEAR package descriptor name <code><componentID>_pear.xml</code> is used.
+ </p>
+ <p>
+ The PEAR package descriptor can be treated similar to an analysis engine descriptor. It can be added
+ at any place where an analysis engine descriptor or cas consumer descriptor can be used. So for example
+ to run an installed PEAR package in the CAS Visual Debugger or in the Document Analyzer just use
+ the PEAR package descriptor as analysis engine - and you don't have to take care about classpath
+ and datapath settings.
+ </p>
+ <p>
+ The PEAR package descriptor can also be added to an aggregate analysis engine descriptor as one of the
+ delegates. So given that, a PEAR can easily be integrated into an analysis chain. But note, the integrated PEAR
+ is treated as black box and the aggregate analysis engine cannot override any PEAR specific parameters or
+ settings since the PEAR is executed in an own environment with an own classloader. This also means that resources
+ cannot be shared easily between PEARs. An advantage of this concept is, that for example the PEAR specific
+ JCAS classes do not affect the application in case of minor feature differences.
+ </p>
+ </blockquote>
+ </td></tr>
+ <tr><td><br/></td></tr>
+ </table>
+ </blockquote>
+ </p>
+ </td></tr>
+ <tr><td><br/></td></tr>
+ </table>
+
+ </td>
+ </tr>
+
+ <!-- FOOTER -->
+ <tr><td colspan="2">
+ <hr noshade="" size="1"/>
+ </td></tr>
+ <tr><td colspan="2">
+ <div align="center"><font color="#525D76" size="-1"><em>
+ Copyright © 2006-2008, The Apache Software Foundation
+ </em></font></div>
+ </td></tr>
+ </table>
+ </body>
+ </html>
+<!-- end the processing -->
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Added: incubator/uima/site/trunk/uima-website/docs/images/getting-started/pear-structure.jpg
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/docs/images/getting-started/pear-structure.jpg?rev=669872&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/docs/images/getting-started/pear-structure.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/xdocs/doc-uima-pears.xml
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/xdocs/doc-uima-pears.xml?rev=669872&view=auto
==============================================================================
--- incubator/uima/site/trunk/uima-website/xdocs/doc-uima-pears.xml (added)
+++ incubator/uima/site/trunk/uima-website/xdocs/doc-uima-pears.xml Fri Jun 20 05:26:20 2008
@@ -0,0 +1,359 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<!--
+ 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.
+-->
+
+<document>
+
+ <properties>
+ <title>Getting Started: Working With PEARs</title>
+ <author email="uima-dev@incubator.apache.org">
+ UIMA Team
+ </author>
+ </properties>
+
+ <body>
+ <section
+ name="Getting Started: Working With PEARs">
+ <p>
+ The "Getting Started: Working With PEARs"
+ guide should help you to understand what a PEAR (Processing Engine ARchive) file is
+ and how PEARS can easily be used and integrated into UIMA applications.
+ </p>
+
+
+ <!--
+ Content:
+ - What are PEAR files
+ - PEAR file structure
+ - Generating PEARs (explained in another tutorial)
+ - PEAR packaging plugin
+ - Ant/Maven build
+ - CommandLine
+ - PEAR packaging API
+ - Installing PEARs (environemnt variables, classpath, PEAR desc, not movable after installation)
+ - PearInstaller, PEAR intall API
+ - Integrating PEARs into an analysis chain
+ - Running PEARs in DocumentAnalyzer or CVD
+ - Running PEARs in an UIMA application
+
+ -->
+ <subsection name="What are UIMA PEAR files">
+ <p>
+ A PEAR (Processing Engine ARchive) file is the UIMA standard packaging format for UIMA components like
+ analysis engines (annotators) or CAS consumers. The PEAR package can be used to distribute
+ and reuse components within other components or applications. The UIMA framework also provides
+ APIs and methods to automatically deploy, verify and run PEAR packages. So when having a correct
+ packaged PEAR, the application doesn't need any additional information or any manual deployed settings to
+ run the PEAR package.
+ </p>
+ <p>
+ To guarantee these characteristics, each PEAR package has the same internal
+ structure as shown in the picture below.
+ <table cellpadding="5">
+ <tr>
+ <td>
+ <img src="./images/getting-started/pear-structure.jpg" alt="PEAR file structure" border="0" />
+ </td>
+ <td valign="top">
+ <ul>
+ <li>
+ <p>
+ <b>metadata</b> - The metadata folder contains the PEAR package installation descriptor
+ that contains all the necessary information about the PEAR package.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>desc</b> - The desc folder contains the component descriptor files e.g. analysis engine
+ descriptor files or aggregate analysis engine descriptor files.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>src</b> - The src folder contains the component source (if it is packaged).
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>bin</b> - The bin folder contains the compiled classes and script files.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>lib</b> - The lib folder contains dependent jar files and libraries.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>doc</b> - The doc folder contains the component documentation materials.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>data</b> - The data folder contains some test or example data files.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>conf</b> - The conf folder contains some component configuration files.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>resources</b> - The resources folder contains the component resources and dependencies.
+ </p>
+ </li>
+ </ul>
+ </td>
+ </tr>
+ </table>
+ </p>
+ <p>
+ The most important file in a PEAR package is the installation descriptor (metadata/install.xml) that contains
+ all the necessary information about the PEAR package. It it used to install and run the PEAR package
+ and defines all necessary dependencies and settings. These are for example the ID/name of the PEAR package,
+ Java classpath settings, UIMA datapath settings or the descriptor file that should be used to
+ run the PEAR package component. For more details about the installation descriptor,
+ please refer to the UIMA documentation at
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.2-incubating/docs/html/references/references.html#ugr.ref.pear.installation_descriptor">
+ Documented template for the installation descriptor</a>
+ </p>
+ </subsection>
+ <subsection name="Generating PEAR files">
+ <p>
+ In this section we will discuss how to generate a PEAR package. The UIMA framework distribution provides
+ different possibilities to create PEAR packages. The details are discussed below.
+ </p>
+ <p>
+ A more general thing that should be recognized independent of the PEAR packaging method are the
+ PEAR macros or PEAR variables. The PEAR structure defines different macros or variables, but the most
+ important one is the <code>$main_root</code> macro. When using this macro in the installation descriptor
+ or within a UIMA descriptor it will be substituted with the real PEAR package installation
+ path to the main component root directory after the PEAR package is installed on the target system.
+ For example, this macro should be used to specify the classpath settings for a PEAR component
+ as shown in some of the examples below. This guarantees that in each scenario the classpath settings
+ are interpreted correctly. For more details about PEAR macros or PEAR variables, please refer to the
+ UIMA documentation at
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.2-incubating/docs/html/references/references.html#ugr.ref.pear.installation_descriptor">
+ Documented template for the installation descriptor</a>.
+ </p>
+
+ <p>
+ <ul>
+ <li>
+ <h4>PearPackaging Eclipse plugin</h4>
+ <p>
+ The PearPackaging Eclipse plugin is automatically installed in your Eclipse environment if you have
+ installed the UIMA Eclipse plugins. The plugin allows you to package a PEAR based on the content of
+ an eclipse project having a UIMA nature. This plugin can for example be used in an analysis engine
+ development environment. I will not give more details here since it
+ is already explained in the <a href="http://incubator.apache.org/uima/doc-uima-annotator.html#Packaging the annotator">
+ Getting Started: Writing My First UIMA Annotator</a> guide.
+ </p>
+ </li>
+ <li>
+ <h4>PearPackaging Ant task</h4>
+ <p>
+ The PEAR packaging Ant task can be used in an Ant build environment to create PEAR packages for UIMA
+ components. The PEAR package content as well as the PEAR package settings can be specified.
+ An example how this can look like is shown below:
+ </p>
+ <p>
+ <table cellpadding="10"><tr><td bgcolor="lightgrey">
+ <pre><!-- PEAR packaging Ant task -->
+<packagePear
+ componentID="SampleAnnotator"
+ mainComponentDesc="desc/mainComponentDesc.xml"
+ classpath="$main_root/pearClasspahtEntry;$main_root/anotherPearClasspahtEntry"
+ datapath="$main_root/resources"
+ mainComponentDir="/home/user/workspace/SampeAnntotator"
+ targetDir="/home/user/pearArchive">
+
+ <envVar name="ENV_VAR_NO1" value="value1"/>
+ <envVar name="ENV_VAR_NO2" value="value2"/>
+
+</packagePear></pre>
+ </td></tr></table>
+ </p>
+ <p>
+ For additional information on how to integrate the PEAR packaging Ant taks, please refer to the
+ <a href="http://svn.apache.org/repos/asf/incubator/uima/sandbox/trunk/PearPackagingAntTask/doc/pdf/PearPackagingAntTaskUserGuide.pdf">
+ PEAR packaging Ant task documentation</a>.
+ </p>
+
+ </li>
+ <li>
+ <h4>PearPackaging Maven plugin</h4>
+ <p>
+ The PEAR packaging Maven plugin can be used in a Maven build environment to create PEAR
+ packages for UIMA component. The PEAR package content as well as the PEAR package settings
+ can be specified. An example how this can look like is shown below:
+ </p>
+ <p>
+ <table cellpadding="10"><tr><td bgcolor="lightgrey">
+ <pre><!-- PEAR packaging Maven plugin -->
+<build>
+ <plugins>
+ ...
+ <plugin>
+ <groupId>org.apache.uima</groupId>
+ <artifactId>PearPackagingMavenPlugin</artifactId>
+ <extensions>true</extensions>
+ <executions>
+ <execution>
+ <phase>package</phase>
+ <configuration>
+ <classpath>$main_root/lib/sample.jar</classpath>
+ <mainComponentDesc>desc/${artifactId}.xml</mainComponentDesc>
+ <componentId>${artifactId}</componentId>
+ <datapath>$main_root/resources</datapath>
+ </configuration>
+ <goals>
+ <goal>package</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ ...
+ </plugins>
+</build></pre>
+ </td></tr></table>
+ </p>
+ <p>
+ For additional information how to integrate the PEAR packaging Maven plugin, please refer to the
+ <a href="http://svn.apache.org/repos/asf/incubator/uima/sandbox/trunk/PearPackagingMavenPlugin/doc/pdf/PearPackagingMavenPluginUserGuide.pdf">
+ PEAR packaging Maven plugin documentation</a>.
+ </p>
+ </li>
+ <li>
+ <h4>PearPackaging command line</h4>
+ <p>
+ The PearPackaging command line can be used if script files should be used to create PEAR packages.
+ Details about how to use the PearPackaging command line is available in the UIMA documentation at
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.2-incubating/docs/html/tools/tools.html#ugr.tools.pear.packager.using_command_line">
+ Using the PEAR command line packager</a>.
+ </p>
+ </li>
+ <li>
+ <h4>PearPackaging API</h4>
+ <p>
+ If there is a need to create PEAR packages out of Java source code, the PEAR packaging
+ API can be used. With the API is either possible to create complete PEAR packages or to create the PEAR
+ packages step by step - first create the installation descriptor and later package the PEAR. Detailed
+ information about the PEAR packaging API is available in the UIMA documentation at
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.2-incubating/docs/html/references/references.html#ugr.ref.pear.packaging_into_1_file">
+ Packaging the PEAR structure into one file</a> and in the
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.2-incubating/docs/api/index.html?org/apache/uima/pear/tools/PackageCreator.html">
+ JavaDocs</a>.
+ </p>
+ </li>
+ </ul>
+ </p>
+ </subsection>
+ <subsection name="Installing PEAR files">
+ <p>
+ But before a component that is packaged as PEAR can be used in an application, the PEAR package
+ must be installed on the target system. During the installation, the package content is extracted
+ and the internal PEAR settings (PEAR macros) are updated with some target system information.
+ This also means that an installed PEAR package cannot be moved to
+ another directory without any internal changes. By default the PEAR packages are not installed directly
+ to the specified installation directory. For each PEAR a subdirectory with the name of the PEAR's ID
+ is created where the PEAR package is installed to. If the PEAR installation directory already exists,
+ the old content is automatically deleted before the new content is installed.
+ </p>
+ <p>
+ To check the most important PEAR settings (classpath, datapath, ...), or to read the settings with an
+ application a <code>setenv.txt</code> file containing all these information is generated in the
+ <code>metadata</code> directory during the installation.
+ </p>
+ <p>
+ After the PEAR file is installed, the installed package is automatically verified using a separate
+ verification step. The verification checks if the installed PEAR package is runnable inside UIMA.
+ </p>
+ <p>
+ Another imported point during the PEAR installation is the generation of the PEAR package descriptor. The
+ PEAR package descriptor is a special UIMA descriptor that can be used to run installed PEAR packages in every
+ UIMA application out of the box. For details about the PEAR descriptor, please refer to the
+ UIMA documentation at
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.2-incubating/docs/html/references/references.html#ugr.ref.pear.specifier">
+ PEAR package descriptor</a>
+ </p>
+ <p>
+ To install a PEAR package you have two possibilities.
+ </p>
+ <p>
+ <ul>
+ <li>
+ <h4>PearInstaller UI</h4>
+ <p>
+ The PearInstaller UI is a standalone Swing application to install PEAR packages.
+ AFter the PEAR package and the install directory is selected, the installaion is
+ performed and the installation and verification results are displayed. Out of the tool
+ it is also possible to test the installed PEAR package directly using the Cas Visual Debugger.
+ For more details about PearInstall, please refer to the UIMA documentation at
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.2-incubating/docs/html/tools/tools.html#ugr.tools.pear.installer">
+ PEAR Installer User's Guide</a>.
+ </p>
+ </li>
+ <li>
+ <h4>PEAR API</h4>
+ <p>
+ The PearInstaller API should be used if you want to integrate the PEAR installation
+ with a custom application. With the PEAR API it is possible to install PEAR packages
+ to a given installation directory and to optional verify the installed packages.
+ Details about the PearInstaller API are available in the UIMA documentation at
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.2-incubating/docs/html/references/references.html#ugr.ref.pear.installing_pear_using_API">
+ Installing a PEAR file using the PEAR APIs</a>.
+ </p>
+ </li>
+ </ul>
+ </p>
+ </subsection>
+ <subsection name="Running installed PEAR files">
+ <p>
+ The UIMA framework has an integrated PEAR runtime to run installed PEAR packages out of the box.
+ For this, the PEAR runtime makes use of the PEAR's installation descriptor settings.
+ To use the PEAR runtime, the generated
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.2-incubating/docs/html/references/references.html#ugr.ref.pear.specifier">
+ PEAR package descriptor</a> must be used to integrate or run PEAR components. The PEAR package descriptor
+ is generated in the main component root directory of the installed PEAR package during the PEAR installation.
+ As PEAR package descriptor name <code><componentID>_pear.xml</code> is used.
+ </p>
+ <p>
+ The PEAR package descriptor can be treated similar to an analysis engine descriptor. It can be added
+ at any place where an analysis engine descriptor or cas consumer descriptor can be used. So for example
+ to run an installed PEAR package in the CAS Visual Debugger or in the Document Analyzer just use
+ the PEAR package descriptor as analysis engine - and you don't have to take care about classpath
+ and datapath settings.
+ </p>
+ <p>
+ The PEAR package descriptor can also be added to an aggregate analysis engine descriptor as one of the
+ delegates. So given that, a PEAR can easily be integrated into an analysis chain. But note, the integrated PEAR
+ is treated as black box and the aggregate analysis engine cannot override any PEAR specific parameters or
+ settings since the PEAR is executed in an own environment with an own classloader. This also means that resources
+ cannot be shared easily between PEARs. An advantage of this concept is, that for example the PEAR specific
+ JCAS classes do not affect the application in case of minor feature differences.
+ </p>
+ </subsection>
+ </section>
+ </body>
+
+</document>
+