<?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 % 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.merger"> | |
<title>PEAR Merger User's Guide</title> | |
<para>The PEAR Merger utility takes two or more PEAR files and merges their contents, | |
creating a new PEAR which has, in turn, a new Aggregate analysis engine whose delegates are | |
the components from the original files being merged. It does this by (1) copying the | |
contents of the input components into the output component, placing each component into a | |
separate subdirectory, (2) generating a UIMA descriptor for the output Aggregate | |
analysis engine and (3) creating an output PEAR file that encapsulates the output | |
Aggregate.</para> | |
<para>The merge logic is quite simple, and is intended to work for simple cases. More complex | |
merging needs to be done by hand. Please see the Restrictions and Limitations section, | |
below.</para> | |
<para>To run the PearMerger command line utility you can use the runPearMerger scripts (.bat for Windows, and .sh for | |
Unix). The usage of the tooling is shown below:</para> | |
<para><programlisting>runPearMerger 1st_input_pear_file ... nth_input_pear_file | |
-n output_analysis_engine_name [-f output_pear_file ]</programlisting></para> | |
<para>The first group of parameters are the input PEAR files. No duplicates are allowed | |
here. The <literal>-n</literal> parameter is the name of the generated Aggregate | |
Analysis Engine. The optional <literal>-f</literal> parameter specifies the name of | |
the output file. If it is omitted, the output is written to | |
<literal>output_analysis_engine_name.pear</literal> in the current working directory.</para> | |
<para>During the running of this tool, work files are written to a temporary directory | |
created in the user's home directory.</para> | |
<section id="ugr.tools.pear.merger.merge_details"> | |
<title>Details of the merging process</title> | |
<para>The PEARs are merged using the following steps:</para> | |
<orderedlist><listitem><para>A temporary working directory, is created for the | |
output aggregate component.</para></listitem> | |
<listitem><para>Each input PEAR file is extracted into a separate | |
'input_component_name' folder under the working directory.</para> | |
</listitem> | |
<listitem><para>The extracted files are processed to adjust the | |
'$main_root' macros. This operation differs from the PEAR installation | |
operation, because it does not replace the macros with absolute paths.</para> | |
</listitem> | |
<listitem><para>The output PEAR directory structure, 'metadata' and | |
'desc' folders under the working directory, are created.</para> | |
</listitem> | |
<listitem><para>The UIMA AE descriptor for the output aggregate component is built | |
in the 'desc' folder. This aggregate descriptor refers to the input | |
delegate components, specifying 'fixed flow' based on the original | |
order of the input components in the command line. The aggregate descriptor's | |
'capabilities' and | |
'operational properties' sections are built based on the input | |
components' specifications.</para></listitem> | |
<listitem><para>A new PEAR installation descriptor is created in the | |
'metadata' folder, referencing the new output aggregate descriptor | |
built in the previous step. </para></listitem> | |
<listitem><para>The content of the temporary output working directory is zipped to | |
created the output PEAR, and then the temporary working directory is deleted. | |
</para></listitem></orderedlist> | |
<para>The PEAR merger utility logs all the operations both to standard console output and | |
to a log file, pm.log, which is created in the current working directory.</para> | |
</section> | |
<section id="ugr.tools.pear.merger.testing_modifying_resulting_pear"> | |
<title>Testing and Modifying the resulting PEAR</title> | |
<para>The output PEAR file can be installed and tested using the PEAR Installer. The | |
output aggregate component can also be tested by using the CVD or DocAnalyzer | |
tools.</para> | |
<para>The PEAR Installer creates Eclipse project files (.classpath and .project) in the | |
root directory of the installer PEAR, so the installed component can be imported into | |
the Eclipse IDE as an external project. Once the component is in the Eclipse IDE, | |
developers may use the Component Descriptor Editor and the PEAR Packager to modify the | |
output aggregate descriptor and re-package the component.</para> | |
</section> | |
<section id="ugr.tools.pear.merger.restrictions_limitations"> | |
<title>Restrictions and Limitations</title> | |
<para>The PEAR Merger utility only does basic merging operations, and is limited as | |
follows. You can overcome these by editing the resulting PEAR file or the resulting | |
Aggregate Descriptor.</para> | |
<orderedlist><listitem><para>The Merge operation specifies Fixed Flow sequencing | |
for the Aggregate.</para></listitem> | |
<listitem><para>The merged aggregate does not define any parameters, so the delegate | |
parameters cannot be overridden.</para></listitem> | |
<listitem><para>No External Resource definitions are generated for the | |
aggregate.</para></listitem> | |
<listitem><para>No Sofa Mappings are generated for the aggregate.</para> | |
</listitem> | |
<listitem><para>Name collisions are not checked for. Possible name collisions could | |
occur in the fully-qualified class names of the implementing Java classes, the names | |
of JAR files, the names of descriptor files, and the names of resource bindings or | |
resource file paths.</para></listitem> | |
<listitem><para>The input and output capabilities are generated based on merging the | |
capabilities from the components (removing duplicates). Capability sets are | |
ignored - only the first of the set is used in this process, and only one set is created | |
for the generated Aggregate. There is no support for merging Sofa | |
specifications.</para></listitem> | |
<listitem><para>No Indexes or Type Priorities are created for the generated | |
Aggregate. No checking is done to see if the Indexes or Type Priorities of the | |
components conflict or are inconsistent.</para></listitem> | |
<listitem><para>You can only merge Analysis Engines and CAS Consumers. </para> | |
</listitem> | |
<listitem><para>Although PEAR file installation descriptors that are being merged | |
can have specific XML elements describing Collection Reader and CAS Consumer | |
descriptors, these elements are ignored during the merge, in the sense that the | |
installation descriptor that is created by the merge does not set these elements. The | |
merge process does not use these elements; the output PEAR's new aggregate only | |
references the merged components' main PEAR descriptor element, as | |
identified by the PEAR element: | |
<programlisting><![CDATA[<SUBMITTED_COMPONENT> | |
<DESC>the_component.xml</DESC>... | |
</SUBMITTED_COMPONENT> | |
]]></programlisting></para> | |
</listitem></orderedlist> | |
</section> | |
</chapter> |