<?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.cpe/" > | |
<!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.cpe"> | |
<title>Collection Processing Engine Configurator User's Guide</title> | |
<titleabbrev>CPE Configurator User's Guide</titleabbrev> | |
<para>A <emphasis>Collection Processing Engine (CPE)</emphasis> processes | |
collections of artifacts (documents) through the combination of the following | |
components: a Collection Reader, Analysis Engines, and CAS Consumers. | |
<footnote><para>Earlier versions of UIMA supported another component, the CAS | |
Initializer, but this component is now deprecated in UIMA Version 2.</para></footnote> | |
</para> | |
<para>The <emphasis>Collection Processing Engine Configurator(CPE | |
Configurator)</emphasis> is a graphical tool that allows you to assemble and run | |
CPEs.</para> | |
<para>For an introduction to Collection Processing Engine concepts, including | |
developing the components that make up a CPE, read <olink targetdoc="&uima_docs_tutorial_guides;"/> | |
<olink targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.cpe"/>. This | |
chapter is a user's guide for using the CPE Configurator tool, and does not describe | |
UIMA's Collection Processing Architecture itself.</para> | |
<section id="ugr.tools.cpe.limitations"> | |
<title>Limitations of the CPE Configurator</title> | |
<para>The CPE Configurator only supports basic CPE configurations.</para> | |
<para>It only supports <quote>Integrated</quote> deployments (although it will | |
connect to remotes if particular CAS Processors are specified with remote service | |
descriptors). It doesn't support configuration of the error handling. It | |
doesn't support Sofa Mappings; it assumes all Single-View components are | |
operating with the _InitialView Sofa. Multi-View components will not have their names | |
mapped. It sets up a fixed-sized CAS Pool.</para> | |
<para>To set these additional options, you must edit the CPE Descriptor XML file | |
directly. See <olink targetdoc="&uima_docs_ref;"/> | |
<olink targetdoc="&uima_docs_ref;" targetptr="ugr.ref.xml.cpe_descriptor"/> for the syntax. | |
You may then open the CPE Descriptor in the CPE Configurator and run it. The changes | |
you applied to the CPE Descriptor <emphasis>will</emphasis> be respected, although you | |
will not be able to see them or edit them from the GUI. | |
</para> | |
</section> | |
<section id="ugr.tools.cpe.starting"> | |
<title>Starting the CPE Configurator</title> | |
<para>The CPE Configurator tool can be run using the <literal>cpeGui</literal> shell | |
script, which is located in the <literal>bin</literal> directory of the UIMA SDK. If | |
you've installed the example Eclipse project (see <olink targetdoc="&uima_docs_overview;"/> | |
<olink targetdoc="&uima_docs_overview;" | |
targetptr="ugr.ovv.eclipse_setup.example_code"/>, you can also run it using the | |
<quote>UIMA CPE GUI</quote> run configuration provided in that project.</para> | |
<note><para>If you are planning to build a CPE using components other than the examples | |
included in the UIMA SDK, you will first need to update your CLASSPATH environment | |
variable to include the classes needed by these components.</para></note> | |
<para>When you first start the CPE Configurator, you will see the main window shown here: | |
<screenshot> | |
<mediaobject> | |
<imageobject> | |
<imagedata width="5.8in" format="JPG" fileref="&imgroot;image002.jpg"/> | |
</imageobject> | |
<textobject><phrase>CPE Configurator main GUI window</phrase> | |
</textobject> | |
</mediaobject> | |
</screenshot></para> | |
</section> | |
<section id="ugr.tools.cpe.selecting_component_descriptors"> | |
<title>Selecting Component Descriptors</title> | |
<para>The CPE Configurator's main window is divided into three sections, one each for the Collection | |
Reader, Analysis Engines, and CAS Consumers.<footnote> | |
<para>There is also a fourth pane, for the CAS Initializer, but it is hidden by default. To enable it click the | |
<literal>View → CAS Initializer Panel</literal> menu item.</para></footnote></para> | |
<para>In each section of the CPE Configurator, you can select the component(s) you want to use by browsing to (or | |
typing the location of) their XML descriptors. You must select a Collection Reader, and at least one Analysis | |
Engine or CAS Consumer.</para> | |
<para>When you select a descriptor, the configuration parameters that are defined in that descriptor will then | |
be displayed in the GUI; these can be modified to override the values present in the descriptor.</para> | |
<para>For example, the screen shot below shows the CPE Configurator after the following components have been | |
chosen: | |
<programlisting>examples/descriptors/collectionReader/FileSystemCollectionReader.xml | |
examples/descriptors/analysis_engine/NamesAndPersonTitles_TAE.xml | |
examples/descriptors/cas_consumer/XmiWriterCasConsumer.xml</programlisting></para> | |
<screenshot> | |
<mediaobject> | |
<imageobject> | |
<imagedata width="5.8in" format="JPG" fileref="&imgroot;image004.jpg"/> | |
</imageobject> | |
<textobject><phrase>CPE Configurator after components chosen</phrase> | |
</textobject> | |
</mediaobject> | |
</screenshot> | |
</section> | |
<section id="ugr.tools.cpe.running"> | |
<title>Running a Collection Processing Engine</title> | |
<para>After selecting each of the components and providing configuration settings, | |
click the play (forward arrow) button at the bottom of the screen to begin processing. A | |
progress bar should be displayed in the lower left corner. (Note that the progress bar | |
will not begin to move until all components have completed their initialization, which | |
may take several seconds.) Once processing has begun, the pause and stop buttons become | |
enabled.</para> | |
<para>If an error occurs, you will be informed by an error dialog. If processing completes | |
successfully, you will be presented with a performance report.</para> | |
</section> | |
<section id="ugr.tools.cpe.file_menu"> | |
<title>The File Menu</title> | |
<para>The CPE Configurator's File Menu has the following options:</para> | |
<itemizedlist><listitem><para>Open CPE Descriptor</para></listitem> | |
<listitem><para>Save CPE Descriptor</para></listitem> | |
<listitem><para>Save Options (submenu)</para></listitem> | |
<listitem><para>Refresh Descriptors from File System</para></listitem> | |
<listitem><para>Clear All</para></listitem> | |
<listitem><para>Exit </para></listitem></itemizedlist> | |
<para><emphasis role="bold">Open CPE Descriptor</emphasis> will allow you to select a | |
CPE Descriptor file from disk, and will read in that CPE Descriptor and configure the GUI | |
appropriately.</para> | |
<para><emphasis role="bold">Save CPE Descriptor</emphasis> will create a CPE | |
Descriptor file that defines the CPE you have constructed. This CPE Descriptor will | |
identify the components that constitute the CPE, as well as the configuration settings | |
you have specified for each of these components. Later, you can use <quote>Open CPE | |
Descriptor</quote> to restore the CPE Configurator to the state. Also, CPE | |
Descriptors can be used to easily run a CPE from a Java program – see | |
<olink targetdoc="&uima_docs_tutorial_guides;"/> <olink | |
targetdoc="&uima_docs_tutorial_guides;" | |
targetptr="ugr.tug.application.running_a_cpe_from_a_descriptor"/> | |
.</para> | |
<para>CPE Descriptors also allow specifying operational parameters, such as error | |
handling options that are not currently available for configuration through the CPE | |
Configurator. For more information on manually creating a CPE Descriptor, see | |
<olink targetdoc="&uima_docs_ref;"/> | |
<olink targetdoc="&uima_docs_ref;" targetptr="ugr.ref.xml.cpe_descriptor"/>. | |
</para> | |
<para>The <emphasis role="bold">Save Options</emphasis> submenu has one item, | |
"Use <import>". If this item is checked (the default), saved CPE descriptors | |
will use the <literal><import></literal> syntax to refer to their component | |
descriptors. If unchecked, the older <literal><include></literal> syntax will | |
be used for new components that you add to your CPE using the GUI. (However, if you | |
open a CPE descriptor that used <import>, these imports will not be replaced.) | |
</para> | |
<para><emphasis role="bold">Refresh Descriptors from File System</emphasis> will | |
reload all descriptors from disk. This is useful if you have made a change to the | |
descriptor outside of the CPE Configurator, and want to refresh the display.</para> | |
<para><emphasis role="bold">Clear All</emphasis> will reset the CPE Configurator to | |
its initial state, with no components selected.</para> | |
<para><emphasis role="bold">Exit</emphasis> will close the CPE Configurator. If you | |
have unsaved changes, you will be prompted as to whether you would like to save them to a | |
CPE Descriptor file. If you do not save them, they will be lost.</para> | |
<para>When you restart the CPE Configurator, it will automatically reload the last CPE | |
descriptor file that you were working with.</para> | |
</section> | |
<section id="ugr.tools.cpe.help_menu"> | |
<title>The Help Menu</title> | |
<para>The CPE Configurator's Help menu provides <quote>About</quote> | |
information and some very simple instructions on how to use the tool.</para> | |
</section> | |
</chapter> |