<?xml version="1.0" encoding="UTF-8"?> | |
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" | |
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[ | |
<!ENTITY imgroot "images/tools/tools.pear.packager/" > | |
<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/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"> | |
<title>PEAR Packager User's Guide</title> | |
<para>A PEAR (Processing Engine ARchive) file is a standard package for UIMA (Unstructured | |
Information Management Architecture) components. The PEAR package can be used for | |
distribution and reuse by other components or applications. It also allows applications | |
and tools to manage UIMA components automatically for verification, deployment, | |
invocation, testing, etc. Please refer to <olink targetdoc="&uima_docs_ref;"/> | |
<olink targetdoc="&uima_docs_ref;" targetptr="ugr.ref.pear"/> | |
for more information about the internal structure of a PEAR file.</para> | |
<para>This chapter describes how to use the PEAR Eclipse plugin or the PEAR command line packager | |
to create PEAR files for standard UIMA components.</para> | |
<section id="ugr.tools.pear.packager.using_eclipse_plugin"> | |
<title>Using the PEAR Eclipse Plugin</title> | |
<para>The PEAR Eclipse plugin is automatically installed if you followed the directions in | |
<olink targetdoc="&uima_docs_overview;"/> | |
<olink targetdoc="&uima_docs_overview;" targetptr="ugr.ovv.eclipse_setup"/>. The use of the | |
plugin involves the following two steps:</para> | |
<itemizedlist spacing="compact"><listitem><para>Add the UIMA nature to your project | |
</para></listitem> | |
<listitem><para>Create a PEAR file using the PEAR generation wizard </para> | |
</listitem></itemizedlist> | |
<section id="ugr.tools.pear.packager.add_uima_nature"> | |
<title>Add UIMA Nature to your project</title> | |
<para>First, create a project for your UIMA component:</para> | |
<itemizedlist spacing="compact"><listitem><para>Create a Java project, which | |
would contain all the files and folders needed for your UIMA component.</para> | |
</listitem> | |
<listitem><para>Create a source folder called <quote>src</quote> in your | |
project, and make it the only source folder, by clicking on | |
<quote>Properties</quote> in your project's context menu (right-click), | |
then select <quote>Java Build Path</quote>, then add the <quote>src</quote> | |
folder to the source folders list, and remove any other folder from the | |
list.</para></listitem> | |
<listitem><para>Specify an output folder for your project called bin, by clicking | |
on <quote>Properties</quote> in your project's context menu | |
(right-click), then select <quote>Java Build Path</quote>, and specify | |
<quote><emphasis>your_project_name</emphasis>/bin</quote> as the default | |
output folder. </para></listitem></itemizedlist> | |
<para>Then, add the UIMA nature to your project by clicking on <quote>Add UIMA | |
Nature</quote> in the context menu (right-click) of your project. Click | |
<quote>Yes</quote> on the <quote>Adding UIMA custom Nature</quote> dialog box. | |
Click <quote>OK</quote> on the confirmation dialog box. | |
<screenshot> | |
<mediaobject> | |
<imageobject> | |
<imagedata width="5.8in" format="JPG" fileref="&imgroot;image002.jpg"/> | |
</imageobject> | |
<textobject><phrase>Screenshot of Adding the UIMA Nature to your project</phrase> | |
</textobject> | |
</mediaobject> | |
</screenshot></para> | |
<para>Adding the UIMA nature to your project creates the PEAR structure in your | |
project. The PEAR structure is a structured tree of folders and files, including the | |
following elements: | |
<itemizedlist><listitem><para><emphasis role="bold">Required | |
Elements:</emphasis> | |
<itemizedlist><listitem><para>The <emphasis role="bold"> | |
metadata</emphasis> folder which contains the PEAR installation descriptor | |
and properties files.</para></listitem> | |
<listitem><para>The installation descriptor (<emphasis role="bold"> | |
metadata/install.xml</emphasis>) | |
</para></listitem></itemizedlist></para></listitem> | |
<listitem><para><emphasis role="bold">Optional Elements:</emphasis> | |
<itemizedlist><listitem><para>The <emphasis role="bold"> | |
desc</emphasis> folder to contain descriptor files of analysis engines, | |
component analysis engines (all levels), and other component (Collection | |
Readers, CAS Consumers, etc).</para></listitem> | |
<listitem><para>The <emphasis role="bold">src </emphasis>folder to | |
contain the source code</para></listitem> | |
<listitem><para>The <emphasis role="bold">bin</emphasis> folder to | |
contain executables, scripts, class files, dlls, shared libraries, | |
etc.</para></listitem> | |
<listitem><para>The <emphasis role="bold">lib</emphasis> folder to | |
contain jar files. </para></listitem> | |
<listitem><para>The <emphasis role="bold">doc </emphasis>folder | |
containing documentation materials, preferably accessible through an | |
index.html.</para></listitem> | |
<listitem><para>The <emphasis role="bold">data</emphasis> folder to | |
contain data files (e.g. for testing).</para></listitem> | |
<listitem><para>The <emphasis role="bold">conf</emphasis> folder to | |
contain configuration files.</para></listitem> | |
<listitem><para>The <emphasis role="bold">resources</emphasis> folder | |
to contain other resources and dependencies.</para></listitem> | |
<listitem><para>Other user-defined folders or files are allowed, but | |
<emphasis>should be avoided</emphasis>. </para></listitem> | |
</itemizedlist> </para></listitem></itemizedlist></para> | |
<para>For more information about the PEAR structure, please refer to the | |
<quote>Processing Engine Archive</quote> section. | |
<figure id="ugr.tools.pear.packager.fig.pear_structure"> | |
<title>The Pear Structure</title> | |
<mediaobject> | |
<imageobject> | |
<imagedata width="3in" format="JPG" | |
fileref="&imgroot;image004.jpg"/> | |
</imageobject> | |
<textobject><phrase>Pear structure</phrase> | |
</textobject> | |
</mediaobject> | |
</figure></para> | |
</section> | |
<section id="ugr.tools.pear.packager.using_pear_generation_wizard"> | |
<title>Using the PEAR Generation Wizard</title> | |
<para>Before using the PEAR Generation Wizard, add all the files needed to | |
run your component including descriptors, jars, external libraries, resources, | |
and component analysis engines (in the case of an aggregate analysis engine), etc. | |
<emphasis>Do not</emphasis> add Jars for the UIMA framework, however. Doing so will | |
cause class loading problems at run time.</para> | |
<para> | |
If you're using a Java IDE like Eclipse, instead of using the output folder (usually | |
<literal>bin</literal> as the source of your classes, it's recommended that | |
you generate a Jar file containing these classes.</para> | |
<para>Then, click on <quote>Generate PEAR file</quote> from the context menu | |
(right-click) of your project, to open the PEAR Generation wizard, and follow the | |
instructions on the wizard to generate the PEAR file.</para> | |
<section id="ugr.tools.pear.packager.wizard.component_information"> | |
<title>The Component Information page</title> | |
<para>The first page of the PEAR generation wizard is the component information | |
page. Specify in this page a component ID for your PEAR and select the main Analysis | |
Engine descriptor. The descriptor must be specified using a pathname relative to | |
the project's root (e.g. <quote>desc/MyAE.xml</quote>). The component id | |
is a string that uniquely identifies the component. It should use the JAVA naming | |
convention (e.g. org.apache.uima.mycomponent).</para> | |
<para>Optionally, you can include specific Collection Iterator, CAS Initializer (deprecated | |
as of Version 2.1), | |
or CAS Consumers. In this case, specify the corresponding descriptors in this | |
page. | |
<figure id="ugr.tools.pear.packager.fig.wizard.component_information"> | |
<title>The Component Information Page</title> | |
<mediaobject> | |
<imageobject> | |
<imagedata width="5.8in" format="JPG" | |
fileref="&imgroot;image006.jpg"/> | |
</imageobject> | |
<textobject><phrase>Pear Wizard - component information page</phrase> | |
</textobject> | |
</mediaobject> | |
</figure></para> | |
</section> | |
<section id="ugr.tools.pear.packager.wizard.install_environment"> | |
<title>The Installation Environment page</title> | |
<para>The installation environment page is used to specify the following: | |
<itemizedlist spacing="compact"><listitem><para>Preferred operating | |
system</para></listitem> | |
<listitem><para>Required JDK version, if applicable.</para></listitem> | |
<listitem><para>Required Environment variable settings. This is where | |
you specify special CLASSPATH paths. You do not need to specify this for | |
any Jar that is listed in the your eclipse project classpath settings; those are automatically | |
put into the generated CLASSPATH. Nor should you include paths to the | |
UIMA Framework itself, here. Doing so may cause class loading problems. | |
</para> | |
<para>CLASSPATH segments are written here using a semicolon ";" as the separator; | |
during PEAR installation, these will be adjusted to be the correct character for the | |
target Operating System.</para> | |
<para>In order to specify the UIMA datapath for your component you have to create an environment | |
variable with the property name <literal>uima.datapath</literal>. The value of this property | |
must contain the UIMA datapath settings.</para> | |
</listitem></itemizedlist></para> | |
<para>Path names should be specified using macros (see below), instead of | |
hard-coded absolute paths that might work locally, but probably won't if the | |
PEAR is deployed in a different machine and environment.</para> | |
<para>Macros are variables such as $main_root, used to represent a string such as the | |
full path of a certain directory.</para> | |
<para>These macros should be defined in the PEAR.properties file using the local | |
values. The tools and applications that use and deploy PEAR files should replace | |
these macros (in the files included in the conf and desc folders) with the | |
corresponding values in the local environment as part of the deployment | |
process.</para> | |
<para>Currently, there are two types of macros:</para> | |
<itemizedlist><listitem><para>$main_root, which represents the local absolute | |
path of the main component root directory after deployment.</para></listitem> | |
<listitem><para><emphasis>$component_id$root</emphasis>, which | |
represents the local absolute path to the root directory of the component which | |
has <emphasis>component_id</emphasis> as component ID. This component could | |
be, for instance, a delegate component. </para></listitem></itemizedlist> | |
<figure id="ugr.tools.pear.packager.fig.wizard.install_environment"> | |
<title>The Installation Environment Page</title> | |
<mediaobject> | |
<imageobject> | |
<imagedata width="5.8in" format="JPG" | |
fileref="&imgroot;image008.jpg"/> | |
</imageobject> | |
<textobject><phrase>Pear Wizard - install environment page</phrase> | |
</textobject> | |
</mediaobject> | |
</figure> | |
</section> | |
<section id="ugr.tools.pear.packager.wizard.file_content"> | |
<title>The PEAR file content page</title> | |
<para>The last page of the wizard is the <quote>PEAR file Export</quote> page, which | |
allows the user to select the files to include in the PEAR file. The metadata folder | |
and all its content is mandatory. Make sure you include all the files needed to run | |
your component including descriptors, jars, external libraries, resources, and | |
component analysis engines (in the case of an aggregate analysis engine), etc. | |
It's recommended to generate a jar file from your code as an alternative to | |
building the project and making sure the output folder (bin) contains the required | |
class files.</para> | |
<para>Eclipse compiles your class files into some output directory, often named | |
"bin" when you take the usual defaults in Eclipse. The recommended practice is to | |
take all these files and put them into a Jar file, perhaps using the Eclipse Export | |
wizard. You would place that Jar file into the PEAR <literal>lib</literal> directory.</para> | |
<note><para>If you are relying on the class files generated in the output folder | |
(usually called bin) to run your code, then make sure the project is built properly, | |
and all the required class files are generated without errors, and then put the | |
output folder (e.g. $main_root/bin) in the classpath using the option to set | |
environment variables, by setting the CLASSPATH variable to include this folder (see the | |
<quote>Installation Environment</quote> page. | |
Beware that using a Java output folder named "bin" in this case is a poor practice, | |
because the PEAR installation | |
tools will presume this folder contains binary executable files, and will adds this folder to | |
the PATH environment variable. | |
</para> </note> | |
<figure id="ugr.tools.pear.packager.fig.wizard.export"> | |
<title>The PEAR File Export Page</title> | |
<mediaobject> | |
<imageobject> | |
<imagedata width="5.7in" format="JPG" | |
fileref="&imgroot;image010.jpg"/> | |
</imageobject> | |
<textobject><phrase>Pear Wizard - File Export Page</phrase> | |
</textobject> | |
</mediaobject> | |
</figure> | |
</section> | |
</section> | |
</section> | |
<section id="ugr.tools.pear.packager.using_command_line"> | |
<title>Using the PEAR command line packager</title> | |
<para>The PEAR command line packager takes some PEAR package parameter settings on the command line to create an | |
UIMA PEAR file.</para> | |
<para>To run the PEAR command line packager you can use the provided runPearPackager (.bat for Windows, and .sh for Unix) | |
scripts. The packager can be used in three different modes.</para> | |
<para><itemizedlist> | |
<listitem> | |
<para>Mode 1: creates a complete PEAR package with the provided information (default mode)</para> | |
<para><programlisting>runPearPackager -compID <componentID> | |
-mainCompDesc <mainComponentDesc> [-classpath <classpath>] | |
[-datapath <datapath>] -mainCompDir <mainComponentDir> | |
-targetDir <targetDir> [-envVars <propertiesFilePath>]</programlisting></para> | |
<para> The created PEAR file has the file name <componentID>.pear and is located in the <targetDir>.</para> | |
</listitem> | |
<listitem> | |
<para>Mode 2: creates a PEAR installation descriptor without packaging the PEAR file</para> | |
<para><programlisting>runPearPackager -create -compID <componentID> | |
-mainCompDesc <mainComponentDesc> [-classpath <classpath>] | |
[-datapath <datapath>] -mainCompDir <mainComponentDir> | |
[-envVars <propertiesFilePath>]</programlisting></para> | |
<para> The PEAR installation descriptor is created in the <mainComponentDir>/metadata directory.</para> | |
</listitem> | |
<listitem> | |
<para>Mode 3: creates a PEAR package with an existing PEAR installation descriptor</para> | |
<para><programlisting>runPearPackager -package -compID <componentID> | |
-mainCompDir <mainComponentDir> -targetDir <targetDir></programlisting></para> | |
<para> The created PEAR file has the file name <componentID>.pear and is located in the <targetDir>.</para> | |
</listitem> | |
</itemizedlist> | |
</para> | |
<para>The modes 2 and 3 should be used when you want to manipulate the PEAR installation descriptor before packaging | |
the PEAR file. </para> | |
<para>Some more details about the PearPackager parameters is provided in the list below:</para> | |
<para><itemizedlist> | |
<listitem> | |
<simpara><literal><componentID></literal>: PEAR package component ID.</simpara> | |
</listitem> | |
<listitem> | |
<simpara><literal><mainComponentDesc></literal>: Main component descriptor of the PEAR package.</simpara> | |
</listitem> | |
<listitem> | |
<simpara><literal><classpath></literal>: PEAR classpath settings. Use $main_root macros to specify | |
path entries. Use <literal>;</literal> to separate the entries.</simpara> | |
</listitem> | |
<listitem> | |
<simpara><literal><datapath></literal>: PEAR datapath settings. Use $main_root macros to specify | |
path entries. Use <literal>;</literal> to separate the path entries.</simpara> | |
</listitem> | |
<listitem> | |
<simpara><literal><mainComponentDir></literal>: Main component directory that contains the PEAR package content.</simpara> | |
</listitem> | |
<listitem> | |
<simpara><literal><targetDir></literal>: Target directory where the created PEAR file is written to.</simpara> | |
</listitem> | |
<listitem> | |
<simpara><literal><propertiesFilePath></literal>: Path name to a properties file that contains environment variables that must be | |
set to run the PEAR content.</simpara> | |
</listitem> | |
</itemizedlist> | |
</para> | |
</section> | |
</chapter> |