| <?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 imgroot "../images/tools/tools.cpe/" > | |
| <!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.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;" 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;" 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;" | |
| 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;" | |
| 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;" 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> |