| <?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> |