You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by mb...@apache.org on 2008/04/24 17:43:21 UTC
svn commit: r651293 - in /incubator/uima/site/trunk/uima-website: docs/
docs/images/getting-started/ xdocs/ xdocs/images/getting-started/
Author: mbaessler
Date: Thu Apr 24 08:43:00 2008
New Revision: 651293
URL: http://svn.apache.org/viewvc?rev=651293&view=rev
Log:
UIMA-1013
adding first version of the UIMA Getting Started Guide: Writing My First UIMA Annotator
https://issues.apache.org/jira/browse/UIMA-1013
Added:
incubator/uima/site/trunk/uima-website/docs/doc-uima-annotator.html
incubator/uima/site/trunk/uima-website/docs/images/getting-started/call-cde.gif (with props)
incubator/uima/site/trunk/uima-website/docs/images/getting-started/cde-typedef-files.gif (with props)
incubator/uima/site/trunk/uima-website/docs/images/getting-started/cde-typedef.gif (with props)
incubator/uima/site/trunk/uima-website/docs/images/getting-started/cde.gif (with props)
incubator/uima/site/trunk/uima-website/docs/images/getting-started/classpath-settings.gif (with props)
incubator/uima/site/trunk/uima-website/docs/images/getting-started/create-class.gif (with props)
incubator/uima/site/trunk/uima-website/docs/images/getting-started/cvd-annotator.gif (with props)
incubator/uima/site/trunk/uima-website/docs/images/getting-started/eclipse-run-cvd.gif (with props)
incubator/uima/site/trunk/uima-website/docs/images/getting-started/eclipse-run-dialog.gif (with props)
incubator/uima/site/trunk/uima-website/docs/images/getting-started/pear-wizard-1.gif (with props)
incubator/uima/site/trunk/uima-website/docs/images/getting-started/pear-wizard-2.gif (with props)
incubator/uima/site/trunk/uima-website/docs/images/getting-started/pear-wizard-3.gif (with props)
incubator/uima/site/trunk/uima-website/docs/images/getting-started/project-selection.gif (with props)
incubator/uima/site/trunk/uima-website/docs/images/getting-started/uima_nature.gif (with props)
incubator/uima/site/trunk/uima-website/xdocs/doc-uima-annotator.xml
incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/cvd-annotator.gif (with props)
incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/eclipse-run-cvd.gif (with props)
incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/eclipse-run-dialog.gif (with props)
incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/pear-wizard-1.gif (with props)
incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/pear-wizard-2.gif (with props)
incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/pear-wizard-3.gif (with props)
incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/project-selection.gif (with props)
incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/uima_nature.gif (with props)
Modified:
incubator/uima/site/trunk/uima-website/docs/documentation.html
incubator/uima/site/trunk/uima-website/xdocs/documentation.xml
Added: incubator/uima/site/trunk/uima-website/docs/doc-uima-annotator.html
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/docs/doc-uima-annotator.html?rev=651293&view=auto
==============================================================================
--- incubator/uima/site/trunk/uima-website/docs/doc-uima-annotator.html (added)
+++ incubator/uima/site/trunk/uima-website/docs/doc-uima-annotator.html Thu Apr 24 08:43:00 2008
@@ -0,0 +1,799 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+
+<!--
+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.
+-->
+
+
+<!-- Content Stylesheet for Site -->
+
+
+<!-- start the processing -->
+ <!-- ====================================================================== -->
+ <!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->
+ <!-- Main Page Section -->
+ <!-- ====================================================================== -->
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
+
+ <meta name="author" value="
+ UIMA Team
+ ">
+ <meta name="email" value="uima-dev@incubator.apache.org">
+
+
+
+
+
+
+
+ <title>Apache UIMA - Getting Started: Writing My First UIMA Annotator</title>
+ </head>
+
+ <body bgcolor="#ffffff" text="#000000" link="#525D76">
+ <table border="0" width="100%" cellspacing="0">
+ <!-- TOP IMAGE -->
+ <tr>
+ <td align='LEFT'>
+ <td align="left">
+<a href="http://incubator.apache.org/"><img src="./images/apache-incubator-logo.png" alt="Apache UIMA" border="0"/></a>
+</td>
+ </td>
+ <td align='CENTER'>
+ <td width="80%" align="center" valign="bottom" bgcolor="#ffffff">
+ <font color="#625972" size="+3" face="arial,helvetica,sanserif">
+ <b>Getting Started: Writing My First UIMA Annotator</b>
+</font>
+</td>
+ </td>
+ <td align='RIGHT'>
+ <td align="left">
+<img src="./images/UIMA_banner.png" alt="UIMA project logo" border="0"/>
+</td>
+ </td>
+ </tr>
+ </table>
+ <table border="0" width="100%" cellspacing="4">
+ <tr><td colspan="2">
+ <hr noshade="" size="1"/>
+ </td></tr>
+
+ <tr>
+ <!-- LEFT SIDE NAVIGATION -->
+ <td width="20%" valign="top" nowrap="true">
+
+ <!-- special ACon Logo - leave here for next time
+ <a href="http://apachecon.com/2005/US/">
+ <img src="http://apache.org/images/ac2005us_blue_125x125.jpg" height="125"
+ width="125" border="0" alt="ApacheCon US 2005" />
+ </a> -->
+
+ <!-- regular menu -->
+
+
+ <!-- ============================================================ -->
+
+ <p><strong>General</strong></p>
+ <ul>
+ <li> <a href="./index.html">Home</a>
+</li>
+ <li> <a href="./news.html">News</a>
+</li>
+ <li> <a href="./documentation.html">Documentation</a>
+</li>
+ <li> <a href="./downloads.cgi">Downloads</a>
+</li>
+ <li> <a href="./license.html">License</a>
+</li>
+ <li> <a href="http://www.apache.org/">ASF</a>
+</li>
+ <li> <a href="http://apache.org/foundation/thanks.html">Thanks</a>
+</li>
+ <li> <a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
+</li>
+ </ul>
+ <p><strong>Community</strong></p>
+ <ul>
+ <li> <a href="./project-guidelines.html">Project Guidelines</a>
+</li>
+ <li> <a href="./contribution-policy.html">Contribution Policies</a>
+</li>
+ <li> <a href="./get-involved.html">Get Involved</a>
+</li>
+ <li> <a href="./team-list.html">Project Team</a>
+</li>
+ <li> <a href="./mail-lists.html">Mailing Lists</a>
+</li>
+ <li> <a href="./faq.html">FAQ</a>
+</li>
+ <li> <a href="http://cwiki.apache.org/UIMA/">Wiki</a>
+</li>
+ <li> <a href="./external-resources.html">External UIMA Resources</a>
+</li>
+ </ul>
+ <p><strong>Development</strong></p>
+ <ul>
+ <li> <a href="./svn.html">Source Code</a>
+</li>
+ <li> <a href="./distribution.html">Creating a Distribution</a>
+</li>
+ <li> <a href="./codeConventions.html">Code Conventions</a>
+</li>
+ <li> <a href="http://issues.apache.org/jira/browse/uima ">JIRA</a>
+</li>
+ <li> <a href="./uima-specification.html">UIMA Specification</a>
+</li>
+ <li> <a href="./sandbox.html">Sandbox</a>
+</li>
+ </ul>
+ <p><strong>Conferences</strong></p>
+ <ul>
+ <li> <a href="./gldv07.html">GLDV 2007</a>
+</li>
+ <li> <a href="./lrec08.html">LREC 2008</a>
+</li>
+ </ul>
+ </td>
+ <td width="80%" align="left" valign="top">
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+ <tr><td bgcolor="#726982">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Getting Started: Writing My First UIMA Annotator"><strong>Getting Started: Writing My First UIMA Annotator</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+ The "Getting Started: Writing My First UIMA Annotator"
+ guide should help you to write your first UIMA annotator component.
+ As you know, UIMA annotators are the analysis
+ components that can be plugged into the UIMA framework to do
+ the text analysis like for example entity detection.
+ </p>
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+
+
+ <tr><td bgcolor="#9289A2">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Prerequisites"><strong>Prerequisites</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+ To work with this guide you need a working eclipse installation with
+ installed UIMA eclipse plugins. I you haven't already installed eclipse with
+ the UIMA plugins, please refer to the UIMA documentation
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/overview_and_setup/overview_and_setup.html#ugr.ovv.eclipse_setup">
+ Setting up the Eclipse IDE to work with UIMA</a>
+ to install and set up your UIMA eclipse environment. Please also install the UIMA examples
+ to your eclipse workspace since we refer to some of these in this guide. How to install
+ the UIMA examples to your eclipse workspace is explained in the same chapter at section
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/overview_and_setup/overview_and_setup.html#ugr.ovv.eclipse_setup.example_code">
+ Setting up Eclipse to view Example Code</a>.
+
+ </p>
+ </blockquote>
+ </td></tr>
+ <tr><td><br/></td></tr>
+ </table>
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+
+
+ <tr><td bgcolor="#9289A2">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Introduction"><strong>Introduction</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+ The annotator we will create in this guide is very simple. It uses a simple
+ regular expression to detect room numbers in text documents (it is the
+ same example as used in the UIMA documentation in the
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/tutorials_and_users_guides/tutorials_and_users_guides.html#ugr.tug.aae">
+ Annotator and Analysis Engine Developer's Guide</a>).
+ Although the task is very simple, it is sufficient to demonstrate
+ how to write an UIMA annotator. For more detailed information about the annotator
+ development, refer to the <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/tutorials_and_users_guides/tutorials_and_users_guides.html#ugr.tug.aae">
+ Annotator and Analysis Engine Developer's Guide</a>
+ </p>
+ </blockquote>
+ </td></tr>
+ <tr><td><br/></td></tr>
+ </table>
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+
+
+ <tr><td bgcolor="#9289A2">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Creating and configuring an Eclipse project for UIMA annotator development"><strong>Creating and configuring an Eclipse project for UIMA annotator development</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+ We first start with setting up an eclipse project to develop our annotator.
+ At first we have to create an eclipse project as shown here:
+ <ol>
+ <li>
+ <p>
+ Create a new Java project in your eclipse workspace called RoomNumberAnnotator.
+ To do this call "File -> New -> Java Project" an use RoomNumberAnnotator as
+ project name.
+ </p>
+ </li>
+ <li>
+ <p>
+ Add the UIMA nature to the project by right-click to the
+ "RoomNumberAnnotator" project and choose "Add UIMA Nature". Confirm the upcoming dialogues
+ with "Yes" to add the UIMA nature and with "OK" to confirm the status message dialog.
+ The UIMA nature is the default directory layout we should use for annotator component
+ development.
+ </p>
+ <p>
+ <img src="./images/getting-started/uima_nature.gif" alt="Add UIMA nature" border="0" />
+ </p>
+ </li>
+ <li>
+ <p>
+ If your default eclipse settings did not already create a "src" folder in your RoomNumberAnnotator
+ project, you have to create one manually.
+ <ul>
+ <li>Right-click the project, and choose "Properties".</li>
+ <li>Select "Java Build Path" on the left side, and choose the "Source" tab on the right.</li>
+ <li>Click the "Add Folder..." button, and mark the "src" folder of your project in the upcoming window.</li>
+ <li>Close the window with the "OK" button.</li>
+ <li>Leave the properties window of your RoomNumberAnnotator project with "OK".</li>
+ </ul>
+ </p>
+ </li>
+ <li>
+ <p>
+ In the last step we have to add the UIMA core libraries that
+ we need to develop and run the annotator to your project.
+ <ul>
+ <li>Right-click to the RoomNumberAnnotator project and choose "Properties".</li>
+ <li>Select "Java Build Path" on the left side, and choose the "Libraries" tab on the right.</li>
+ <li>Click the "Add Variable..." button, and select the "UIMA_HOME" variable.</li>
+ <li>Click the "Extend..." button and chose the <code>uima-core.jar</code> in "lib" directory</li>
+ <li>Finalize all dialogues with the "OK" button.</li>
+ </ul>
+ </p>
+ <p>
+ <img src="./images/getting-started/classpath-settings.gif" alt="Project classpath settings" border="0" />
+ </p>
+
+ </li>
+ </ol>
+ </p>
+ </blockquote>
+ </td></tr>
+ <tr><td><br/></td></tr>
+ </table>
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+
+
+ <tr><td bgcolor="#9289A2">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Defining annotator types"><strong>Defining annotator types</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+ Before we can start implementing the annotator we have to create some meta data for the
+ annotator - the analysis engine descriptor. The analysis engine descriptor
+ contains information about the annotator that is accessible without
+ having access to the source code. It contains information like configuration parameters,
+ data structures, annotator input and output data types and the
+ resources that the annotator use. The descriptor is also used by the UIMA framework
+ to load the annotator. Details about creating XML descriptors can also be found in the
+ UIMA documentation at
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/tutorials_and_users_guides/tutorials_and_users_guides.html#ugr.tug.aae.creating_xml_descriptor">
+ Creating the XML Descriptor</a>.
+ </p>
+ <p>
+ To create a new analysis engine descriptor:
+ <ol>
+ <li>
+ <p>Right-click on the "desc" folder of your project and choose "New -> Other".</p>
+ </li>
+ <li>
+ <p>Select "Analysis Engine Descriptor" out of the "UIMA" folder and press "Next".</p>
+ </li>
+ <li>
+ <p>Enter "RoomNumberAnnotatorDescriptor.xml" as file name, and press "Finish".</p>
+ </li>
+ <li>
+ <p>A new descriptor file is created and opened in the UIMA Component Descriptor Editor plugin.
+ For now, we just have to add the Java class name we will use later to implement the
+ annotator. Use "org.apache.uima.tutorial.ex1.RoomNumberAnnotator" as Java class name.
+ </p>
+ <p>
+ <img src="./images/getting-started/cde.gif" alt="Component Descriptor Editor" border="0" />
+ </p>
+ </li>
+ </ol>
+ </p>
+ <p>
+ We have successfully created the annotator descriptor that we will use later to
+ start the annotator. In the next step will define the output types that
+ the annotator produce. We have to do this before we start implementing the
+ annotator code since we will use the definitions later in our implementation.
+ </p>
+ <p>
+ All the data that is produced by annotators or exchanged between annotator
+ components is defined in the UIMA type system. The UIMA type system is part of
+ the analysis engine descriptor file so that each user or application
+ knows the types the annotator deals with. This is one of the main advantages of UIMA
+ that the data structures are declaratively specified and are stored inside the
+ UIMA framework. This increase the interoperability between components and allows to include
+ components using different programming languages.
+ </p>
+ <p>
+ To make the definition of types easier, the UIMA framework has some pre-defined types. One of
+ them is call <code>uima.tcas.Annotation</code>. Annotations are spans of text with a defined begin
+ and end position. Most of the annotators inherit their own types from this base type. Another
+ pre-defined type is the <code>uima.tcas.DocumentAnnotation</code> that is used to store document
+ meta information like for example the document language. Some more details about the UIMA
+ type system and about the type system we will create for the RoomNumberAnnotator is available
+ in the UIMA documentation in the chapter
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/tutorials_and_users_guides/tutorials_and_users_guides.html#ugr.tug.aae.defining_types">
+ Defining Types</a>.
+ </p>
+ <p>
+ After this brief UIMA type system instruction, let's start and model the type system that we
+ will use for the RoomNumberAnnotator. The annotator will detect room numbers, so we will create
+ an annotation type called <code>org.apache.uima.tutorial.RoomNumber</code> that is inherited from
+ <code>uima.tcas.Annotation</code>. Additionally we want to store some meta information
+ about the room we detected, therefor we will add a feature to the annotation
+ called <code>building</code> that will contain some additional building information about the
+ detected room.
+ </p>
+ <p>
+ Let's go ahead and create the discussed type system in the recently created analysis engine
+ descriptor. To add a new type to the descriptor:
+ <ol>
+ <li>
+ <p>
+ Open the descriptor using the UIMA Component Descriptor Editor (CDE) by right-click to
+ the "RoomNumberAnnotatorDescriptor.xml" file and choose "Open With -> Component Descriptor Editor"
+ </p>
+ <p>
+ <img src="./images/getting-started/call-cde.gif" alt="Call Component Descriptor Editor" border="0" />
+ </p>
+ </li>
+ <li>
+ <p>Select the "TypeSystem" tab at the bottom to show the type system definition page.</p>
+ </li>
+ <li>
+ <p>Press the "Add Type" button to add the new type. Use "org.apache.uima.tutorial.RoomNumber"
+ as type name and finish with "OK". The supertype "uima.tcas.Annotation" is correct.</p>
+ </li>
+ </ol>
+ We just added the first type to our RoomNumberAnnotator type system. Now we want to add an additional
+ feature to the created type to store the annotation meta information
+ <ol>
+ <li>
+ <p>Select the "org.apache.uima.tutorial.RoomNumber" type by clicking it.</p>
+ </li>
+ <li>
+ <p>Click the "Add..." button to add a feature to the type and specify "building"
+ as feature name and "uima.cas.String" as range type.
+ This means that the "building" feature is a String based feature.
+ Finish the dialog by clicking "OK".</p>
+ </li>
+ <li>
+ <p>Save the descriptor file</p>
+ <p>
+ <img src="./images/getting-started/cde-typedef.gif" alt="Type System definition" border="0" />
+ </p>
+ </li>
+ </ol>
+ That's all - we defined the UIMA type system for the RoomNumberAnnotator that we use later when we
+ implement the annotator code. To use defined types easily the UIMA Component Descriptor Editor
+ can generate Java classes for the defined types. To generate these classes follow the steps below:
+ <ol>
+ <li>
+ <p>Open the descriptor file in the Component Descriptor Editor and select the "Type System" tab.</p>
+ </li>
+ <li>
+ <p>Press the "JCasGen" button that will trigger the Java class generation. The generated classes
+ will be added to the "src" folder of your project in a separate package.</p>
+ <p>
+ <img src="./images/getting-started/cde-typedef-files.gif" alt="Type System definition" border="0" />
+ </p>
+
+ </li>
+ </ol>
+ Now all pre-work is done and can start implementing the annotator source code.
+ </p>
+ </blockquote>
+ </td></tr>
+ <tr><td><br/></td></tr>
+ </table>
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+
+
+ <tr><td bgcolor="#9289A2">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Writing the annotator code"><strong>Writing the annotator code</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+ In this section we will create the RoomNumberAnnotator source code. For more detailed
+ information about this topic please refer to the UIMA documentation at chapter
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/tutorials_and_users_guides/tutorials_and_users_guides.html#ugr.tug.aae.developing_annotator_code">
+ Developing Your Annotator Code</a>
+ </p>
+ <p>
+ We start with creating a new Java class. Follow the steps below to create the RoomNumberAnnotator java class.
+ <ol>
+ <li>
+ <p>
+ Right-click on the "src" folder and select "New -> Class".
+ </p>
+ </li>
+ <li>
+ <p>
+ A wizard is upcoming where you can specify the Java class information shown below.
+ We will create a Java class called <code>RoomNumberAnnotator</code> that inherits
+ from the base class called <code>org.apache.uima.analysis_component.JCasAnnotator_ImplBase</code>.
+ This is the base for all UIMA annotator implementations.
+ </p>
+ <p>
+ Java class information:
+ <ul>
+ <li> Package: <code>org.apache.uima.tutorial.ex1</code> </li>
+ <li> Name: <code>RoomNumberAnnotator</code> </li>
+ <li> Superclass: <code>org.apache.uima.analysis_component.JCasAnnotator_ImplBase</code> </li>
+ </ul>
+ </p>
+ <p>
+ <img src="./images/getting-started/create-class.gif" alt="Class generation wizard" border="0" />
+ </p>
+ </li>
+ <li>
+ <p>
+ Press the "OK" button to create the class and to finish the wizard.
+ </p>
+ </li>
+ </ol>
+ The created Java class has a pre-defined method stub for the annotator <code>process()</code> method.
+ This method is used to implement the annotator logic. <code>process()</code> is called
+ by the UIMA framework for each document that should be processed by
+ this annotator.
+ </p>
+ <p>
+ The logic for the implementation of the RoomNumberAnnotator is shown below. Check the
+ source code comments for some additional information.
+ <table cellpadding="15"><tr><td bgcolor="lightgrey">
+ <pre>package org.apache.uima.tutorial.ex1;
+
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+import org.apache.uima.analysis_component.JCasAnnotator_ImplBase;
+import org.apache.uima.jcas.JCas;
+import org.apache.uima.tutorial.RoomNumber;
+
+public class RoomNumberAnnotator extends JCasAnnotator_ImplBase {
+ // create regular expression pattern for Yorktown room number
+ private Pattern mYorktownPattern =
+ Pattern.compile("\\b[0-4]\\d-[0-2]\\d\\d\\b");
+
+ // create regular expression pattern for Hawthorne room number
+ private Pattern mHawthornePattern =
+ Pattern.compile("\\b[G1-4][NS]-[A-Z]\\d\\d\\b");
+
+ public void process(JCas aJCas) {
+
+ // The JCas object is the data object inside UIMA where all the
+ // information is stored. It contains based on the defined
+ // types system all annotations created by previous annotators
+ // and also the document text that should be analyzed.
+
+ // get document text from JCas
+ String docText = aJCas.getDocumentText();
+
+ // search for Yorktown room numbers
+ Matcher matcher = mYorktownPattern.matcher(docText);
+ int pos = 0;
+ while (matcher.find(pos)) {
+ // match found - create the match as annotation in
+ // the JCas with some additional meta information
+ RoomNumber annotation = new RoomNumber(aJCas);
+ annotation.setBegin(matcher.start());
+ annotation.setEnd(matcher.end());
+ annotation.setBuilding("Yorktown");
+ annotation.addToIndexes();
+ pos = matcher.end();
+ }
+
+ // search for Hawthorne room numbers
+ matcher = mHawthornePattern.matcher(docText);
+ pos = 0;
+ while (matcher.find(pos)) {
+ // match found - create the match as annotation in
+ // the JCas with some additional meta information
+ RoomNumber annotation = new RoomNumber(aJCas);
+ annotation.setBegin(matcher.start());
+ annotation.setEnd(matcher.end());
+ annotation.setBuilding("Hawthorne");
+ annotation.addToIndexes();
+ pos = matcher.end();
+ }
+ }
+}</pre></td></tr></table>
+ </p>
+ <p>
+ In the current implementation we don't use the method <code>initialize()</code>. Typically
+ the <code>initialize()</code> method is used to get annotator configuration parameters that can be
+ configured by the user. In our case this could be for example the used regular expressions used
+ to detect the room numbers. For more details about configuration parameters, please refer to the
+ UIMA documentation at chapter
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/tutorials_and_users_guides/tutorials_and_users_guides.html#ugr.tug.aae.configuration_parameters">
+ Configuration Parameters</a>.
+ </p>
+ </blockquote>
+ </td></tr>
+ <tr><td><br/></td></tr>
+ </table>
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+
+
+ <tr><td bgcolor="#9289A2">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Testing the annotator"><strong>Testing the annotator</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+ After we have finished the annotator development we have to test if the annotator
+ code that we have written works as expected. To do this, we use one of the tools
+ provided by the UIMA SDK - the Cas Visual Debugger (CVD). The CVD is already available in
+ your eclipse installation since it was installed with the UIMA eclipse plugins and with
+ the UIMA example code.
+ </p>
+ <p>
+ To start the CVD and to configure the classpath do:
+ <ol>
+ <li>
+ <p>Open the eclipse "Run dialog"
+ <img src="./images/getting-started/eclipse-run-dialog.gif" alt="Eclipse run dialog" border="0" /> </p>
+ </li>
+ <li>
+ <p>Expand "Java Application" in the left window and choose "UIMA CAS Visual Debugger".
+ Now select the "Classpath" tab on the right.
+ <img src="./images/getting-started/eclipse-run-cvd.gif" alt="Eclipse CVD run dialog" border="0" />
+ </p>
+ </li>
+ <li>
+ <p>Select the "User Entries" in the classpath tab and press the "Add Projects..." button.</p>
+ </li>
+ <li>
+ <p>Mark the "RoomNumberAnnotator" project in the upcoming dialog and finish with "OK".
+ </p>
+ <p>
+ <img src="./images/getting-started/project-selection.gif" alt="RoomNumberAnnotator project selection" border="0" /></p>
+ <p>
+ Now we have added the RoomNumberAnnotator classes to the CVD classpath.
+ </p>
+ </li>
+ <li>
+ <p>Apply the classpath settings using the "Apply" button and run the CVD by selecting "Run".</p>
+ </li>
+ </ol>
+ </p>
+ <p>
+ Note: The classpath settings must only we configured once, after that you can start the CVD directly from
+ the eclipse "Run dialog".
+ </p>
+ <p>
+ To test the RoomNumberAnnotator in the CVD we have to load the created RoomNumberAnnotator
+ analysis engine descriptor.
+ <ol>
+ <li>
+ <p>
+ Choose "Run -> Load AE" and select the <code>RoomNumberAnnotatorDescriptor.xml</code> file
+ in the <code>desc</code> folder of your eclipse project.
+ </p>
+ </li>
+ <li>
+ <p>
+ Copy and past the text below for testing to the text section of the CVD.
+ This text content in passed to the annotator when running the component.
+ </p>
+ <p>
+ <table cellpadding="15"><tr><td bgcolor="lightgrey"><pre>
+Upcoming UIMA Seminars
+
+April 7, 2004 Distillery Lunch Seminar
+UIMA and its Metadata
+12:00PM-1:00PM in HAW GN-K35
+
+April 16, 2004 KM & I Department Tea
+Title: An Eclipse-based TAE Configurator Tool
+3:00PM-4:30PM in HAW GN-K35
+
+May 11, 2004 UIMA Tutorial
+9:00AM-5:00PM in HAW GN-K35
+ </pre></td></tr></table>
+ </p>
+ </li>
+ <li>
+ <p>
+ To run the annotator on the specified text, choose "Run -> RunRoomNumberAnnotatorDescriptor".
+ <img src="./images/getting-started/cvd-annotator.gif" alt="RoomNumberAnnotator in CVD" border="0" />
+ </p>
+ <p>
+ To view the analysis result produced by the annotator, click "Annotation Index" on the left and
+ choose on of the "org.apache.uima.tutorial.RoomNumber" annotations shown below. When
+ selecting one of the annotations you get the text highlighted on the right that is covered by
+ this annotation. If there are no annotations available - the annotator does not work correctly.
+ Check the log file for possible errors "Tools -> View Log File".
+ </p>
+ </li>
+ </ol>
+ </p>
+ <p>
+ For more details about the CAS Visual Debugger, please refer to the UIMA documentation
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/tools/tools.html#ugr.tools.cvd">
+ CAS Visual Debugger</a>.
+ </p>
+ </blockquote>
+ </td></tr>
+ <tr><td><br/></td></tr>
+ </table>
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+
+
+ <tr><td bgcolor="#9289A2">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Packaging the annotator"><strong>Packaging the annotator</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+ After we have successfully implemented and tested our annotator we are ready
+ to package the annotator to deploy it in another application where we
+ want to use it. The annotator packaging format in UIMA is called PEAR
+ (Processing Engine ARchive) and contains all necessary information to run
+ the wrapped annotator component. For details about the PEAR packaging
+ format please refer to the UIMA documentation chapter
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/references/references.html#ugr.ref.pear">
+ PEAR Reference</a>.
+ </p>
+ <p>
+ To package the annotator we use another UIMA tooling called
+ PEAR packager. To start the PEAR packager and to create
+ the RoomNumberAnnotator PEAR package do:
+ <ol>
+ <li>
+ <p>
+ Right-click on the RoomNumberAnnotator project and call "Generate PEAR file".
+ </p>
+ </li>
+ <li>
+ <p>
+ Once the wizard is started with the first page, you have to specify
+ an annotator component ID and the annotator descriptor file that is used to run the
+ annotator component. The componentID is pre-filled and can be used as is.
+ For the annotator descriptor file, use "Browse" and select the
+ <code>RoomNumberAnnotatorDescriptor.xml</code> file in the
+ <code>desc</code> folder of your project.
+ </p>
+ <p>
+ <img src="./images/getting-started/pear-wizard-1.gif" alt="PEAR wizard" border="0" />
+ </p>
+ </li>
+ <li>
+ <p>
+ After adding these values, go to the next wizard page with the "Next" button.
+ This page shows the classpath and environment configuration for the annotator. The
+ default settings are sufficient in our case.
+ </p>
+ <p>
+ <img src="./images/getting-started/pear-wizard-2.gif" alt="PEAR wizard" border="0" />
+ </p>
+ </li>
+ <li>
+ <p>
+ Choose "Next" to get to the last wizard page.
+ </p>
+ <p>
+ <img src="./images/getting-started/pear-wizard-3.gif" alt="PEAR wizard" border="0" />
+ </p>
+ <p>
+ This page specifies the content of the PEAR package. By default all the eclipse
+ project content is added to the PEAR. This is correct in our case and we just have to specify
+ the PEAR file name and location in the "To pear file" input field.
+ </p>
+ </li>
+ <li>
+ <p>
+ Starting the PEAR package generation process by pressing the "Finish" button.
+ Once the packaging is done, an message dialog comes up with a success message.
+ The created PEAR package is available at the specified location.
+ </p>
+ </li>
+ </ol>
+ </p>
+ <p>
+ At this point we are done with the annotator development. We created an annotator PEAR package
+ that allows us to use the annotator component easily in different applications.
+ How we handle and use PEAR packages and how we install it to other applications is not part
+ of this guide, please refer to the UIMA documentation at the
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/tools/tools.html#ugr.tools.pear.installer">
+ PEAR Installer User's Guide</a> for additional information about this topic.
+ </p>
+ </blockquote>
+ </td></tr>
+ <tr><td><br/></td></tr>
+ </table>
+ </blockquote>
+ </p>
+ </td></tr>
+ <tr><td><br/></td></tr>
+ </table>
+
+ </td>
+ </tr>
+
+ <!-- FOOTER -->
+ <tr><td colspan="2">
+ <hr noshade="" size="1"/>
+ </td></tr>
+ <tr><td colspan="2">
+ <div align="center"><font color="#525D76" size="-1"><em>
+ Copyright © 2006-2008, The Apache Software Foundation
+ </em></font></div>
+ </td></tr>
+ </table>
+ </body>
+ </html>
+<!-- end the processing -->
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Modified: incubator/uima/site/trunk/uima-website/docs/documentation.html
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/docs/documentation.html?rev=651293&r1=651292&r2=651293&view=diff
==============================================================================
--- incubator/uima/site/trunk/uima-website/docs/documentation.html (original)
+++ incubator/uima/site/trunk/uima-website/docs/documentation.html Thu Apr 24 08:43:00 2008
@@ -249,6 +249,11 @@
<li><a href="doc-uima-examples.html">Getting Started: Install UIMA And Run Examples</a><br />
For first time UIMA users who want to know how UIMA is installed and how they can run
the UIMA analysis examples that are provided with the release package.</li>
+ <br />
+ <li><a href="doc-uima-annotator.html">Getting Started: Writing My First UIMA Annotator</a><br />
+ For UIMA beginners that want to develop their first UIMA analysis component using eclipse.
+ </li>
+
</ul>
</p>
</blockquote>
Added: incubator/uima/site/trunk/uima-website/docs/images/getting-started/call-cde.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/docs/images/getting-started/call-cde.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/docs/images/getting-started/call-cde.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/docs/images/getting-started/cde-typedef-files.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/docs/images/getting-started/cde-typedef-files.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/docs/images/getting-started/cde-typedef-files.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/docs/images/getting-started/cde-typedef.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/docs/images/getting-started/cde-typedef.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/docs/images/getting-started/cde-typedef.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/docs/images/getting-started/cde.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/docs/images/getting-started/cde.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/docs/images/getting-started/cde.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/docs/images/getting-started/classpath-settings.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/docs/images/getting-started/classpath-settings.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/docs/images/getting-started/classpath-settings.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/docs/images/getting-started/create-class.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/docs/images/getting-started/create-class.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/docs/images/getting-started/create-class.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/docs/images/getting-started/cvd-annotator.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/docs/images/getting-started/cvd-annotator.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/docs/images/getting-started/cvd-annotator.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/docs/images/getting-started/eclipse-run-cvd.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/docs/images/getting-started/eclipse-run-cvd.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/docs/images/getting-started/eclipse-run-cvd.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/docs/images/getting-started/eclipse-run-dialog.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/docs/images/getting-started/eclipse-run-dialog.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/docs/images/getting-started/eclipse-run-dialog.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/docs/images/getting-started/pear-wizard-1.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/docs/images/getting-started/pear-wizard-1.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/docs/images/getting-started/pear-wizard-1.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/docs/images/getting-started/pear-wizard-2.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/docs/images/getting-started/pear-wizard-2.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/docs/images/getting-started/pear-wizard-2.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/docs/images/getting-started/pear-wizard-3.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/docs/images/getting-started/pear-wizard-3.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/docs/images/getting-started/pear-wizard-3.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/docs/images/getting-started/project-selection.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/docs/images/getting-started/project-selection.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/docs/images/getting-started/project-selection.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/docs/images/getting-started/uima_nature.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/docs/images/getting-started/uima_nature.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/docs/images/getting-started/uima_nature.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/xdocs/doc-uima-annotator.xml
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/xdocs/doc-uima-annotator.xml?rev=651293&view=auto
==============================================================================
--- incubator/uima/site/trunk/uima-website/xdocs/doc-uima-annotator.xml (added)
+++ incubator/uima/site/trunk/uima-website/xdocs/doc-uima-annotator.xml Thu Apr 24 08:43:00 2008
@@ -0,0 +1,549 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<!--
+ 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.
+-->
+
+<document>
+
+ <properties>
+ <title>Getting Started: Writing My First UIMA Annotator</title>
+ <author email="uima-dev@incubator.apache.org">
+ UIMA Team
+ </author>
+ </properties>
+
+ <body>
+ <section
+ name="Getting Started: Writing My First UIMA Annotator">
+ <p>
+ The "Getting Started: Writing My First UIMA Annotator"
+ guide should help you to write your first UIMA annotator component.
+ As you know, UIMA annotators are the analysis
+ components that can be plugged into the UIMA framework to do
+ the text analysis like for example entity detection.
+ </p>
+
+ <subsection name="Prerequisites">
+ <p>
+ To work with this guide you need a working eclipse installation with
+ installed UIMA eclipse plugins. I you haven't already installed eclipse with
+ the UIMA plugins, please refer to the UIMA documentation
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/overview_and_setup/overview_and_setup.html#ugr.ovv.eclipse_setup">
+ Setting up the Eclipse IDE to work with UIMA</a>
+ to install and set up your UIMA eclipse environment. Please also install the UIMA examples
+ to your eclipse workspace since we refer to some of these in this guide. How to install
+ the UIMA examples to your eclipse workspace is explained in the same chapter at section
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/overview_and_setup/overview_and_setup.html#ugr.ovv.eclipse_setup.example_code">
+ Setting up Eclipse to view Example Code</a>.
+
+ </p>
+ </subsection>
+
+ <subsection name="Introduction">
+ <p>
+ The annotator we will create in this guide is very simple. It uses a simple
+ regular expression to detect room numbers in text documents (it is the
+ same example as used in the UIMA documentation in the
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/tutorials_and_users_guides/tutorials_and_users_guides.html#ugr.tug.aae">
+ Annotator and Analysis Engine Developer's Guide</a>).
+ Although the task is very simple, it is sufficient to demonstrate
+ how to write an UIMA annotator. For more detailed information about the annotator
+ development, refer to the <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/tutorials_and_users_guides/tutorials_and_users_guides.html#ugr.tug.aae">
+ Annotator and Analysis Engine Developer's Guide</a>
+ </p>
+ </subsection>
+ <subsection name="Creating and configuring an Eclipse project for UIMA annotator development">
+ <p>
+ We first start with setting up an eclipse project to develop our annotator.
+ At first we have to create an eclipse project as shown here:
+ <ol>
+ <li>
+ <p>
+ Create a new Java project in your eclipse workspace called RoomNumberAnnotator.
+ To do this call "File -> New -> Java Project" an use RoomNumberAnnotator as
+ project name.
+ </p>
+ </li>
+ <li>
+ <p>
+ Add the UIMA nature to the project by right-click to the
+ "RoomNumberAnnotator" project and choose "Add UIMA Nature". Confirm the upcoming dialogues
+ with "Yes" to add the UIMA nature and with "OK" to confirm the status message dialog.
+ The UIMA nature is the default directory layout we should use for annotator component
+ development.
+ </p>
+ <p>
+ <img src="./images/getting-started/uima_nature.gif" alt="Add UIMA nature" border="0" />
+ </p>
+ </li>
+ <li>
+ <p>
+ If your default eclipse settings did not already create a "src" folder in your RoomNumberAnnotator
+ project, you have to create one manually.
+ <ul>
+ <li>Right-click the project, and choose "Properties".</li>
+ <li>Select "Java Build Path" on the left side, and choose the "Source" tab on the right.</li>
+ <li>Click the "Add Folder..." button, and mark the "src" folder of your project in the upcoming window.</li>
+ <li>Close the window with the "OK" button.</li>
+ <li>Leave the properties window of your RoomNumberAnnotator project with "OK".</li>
+ </ul>
+ </p>
+ </li>
+ <li>
+ <p>
+ In the last step we have to add the UIMA core libraries that
+ we need to develop and run the annotator to your project.
+ <ul>
+ <li>Right-click to the RoomNumberAnnotator project and choose "Properties".</li>
+ <li>Select "Java Build Path" on the left side, and choose the "Libraries" tab on the right.</li>
+ <li>Click the "Add Variable..." button, and select the "UIMA_HOME" variable.</li>
+ <li>Click the "Extend..." button and chose the <code>uima-core.jar</code> in "lib" directory</li>
+ <li>Finalize all dialogues with the "OK" button.</li>
+ </ul>
+ </p>
+ <p>
+ <img src="./images/getting-started/classpath-settings.gif" alt="Project classpath settings" border="0" />
+ </p>
+
+ </li>
+ </ol>
+ </p>
+ </subsection>
+ <subsection name="Defining annotator types">
+ <p>
+ Before we can start implementing the annotator we have to create some meta data for the
+ annotator - the analysis engine descriptor. The analysis engine descriptor
+ contains information about the annotator that is accessible without
+ having access to the source code. It contains information like configuration parameters,
+ data structures, annotator input and output data types and the
+ resources that the annotator use. The descriptor is also used by the UIMA framework
+ to load the annotator. Details about creating XML descriptors can also be found in the
+ UIMA documentation at
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/tutorials_and_users_guides/tutorials_and_users_guides.html#ugr.tug.aae.creating_xml_descriptor">
+ Creating the XML Descriptor</a>.
+ </p>
+ <p>
+ To create a new analysis engine descriptor:
+ <ol>
+ <li>
+ <p>Right-click on the "desc" folder of your project and choose "New -> Other".</p>
+ </li>
+ <li>
+ <p>Select "Analysis Engine Descriptor" out of the "UIMA" folder and press "Next".</p>
+ </li>
+ <li>
+ <p>Enter "RoomNumberAnnotatorDescriptor.xml" as file name, and press "Finish".</p>
+ </li>
+ <li>
+ <p>A new descriptor file is created and opened in the UIMA Component Descriptor Editor plugin.
+ For now, we just have to add the Java class name we will use later to implement the
+ annotator. Use "org.apache.uima.tutorial.ex1.RoomNumberAnnotator" as Java class name.
+ </p>
+ <p>
+ <img src="./images/getting-started/cde.gif" alt="Component Descriptor Editor" border="0" />
+ </p>
+ </li>
+ </ol>
+ </p>
+ <p>
+ We have successfully created the annotator descriptor that we will use later to
+ start the annotator. In the next step will define the output types that
+ the annotator produce. We have to do this before we start implementing the
+ annotator code since we will use the definitions later in our implementation.
+ </p>
+ <p>
+ All the data that is produced by annotators or exchanged between annotator
+ components is defined in the UIMA type system. The UIMA type system is part of
+ the analysis engine descriptor file so that each user or application
+ knows the types the annotator deals with. This is one of the main advantages of UIMA
+ that the data structures are declaratively specified and are stored inside the
+ UIMA framework. This increase the interoperability between components and allows to include
+ components using different programming languages.
+ </p>
+ <p>
+ To make the definition of types easier, the UIMA framework has some pre-defined types. One of
+ them is call <code>uima.tcas.Annotation</code>. Annotations are spans of text with a defined begin
+ and end position. Most of the annotators inherit their own types from this base type. Another
+ pre-defined type is the <code>uima.tcas.DocumentAnnotation</code> that is used to store document
+ meta information like for example the document language. Some more details about the UIMA
+ type system and about the type system we will create for the RoomNumberAnnotator is available
+ in the UIMA documentation in the chapter
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/tutorials_and_users_guides/tutorials_and_users_guides.html#ugr.tug.aae.defining_types">
+ Defining Types</a>.
+ </p>
+ <p>
+ After this brief UIMA type system instruction, let's start and model the type system that we
+ will use for the RoomNumberAnnotator. The annotator will detect room numbers, so we will create
+ an annotation type called <code>org.apache.uima.tutorial.RoomNumber</code> that is inherited from
+ <code>uima.tcas.Annotation</code>. Additionally we want to store some meta information
+ about the room we detected, therefor we will add a feature to the annotation
+ called <code>building</code> that will contain some additional building information about the
+ detected room.
+ </p>
+ <p>
+ Let's go ahead and create the discussed type system in the recently created analysis engine
+ descriptor. To add a new type to the descriptor:
+ <ol>
+ <li>
+ <p>
+ Open the descriptor using the UIMA Component Descriptor Editor (CDE) by right-click to
+ the "RoomNumberAnnotatorDescriptor.xml" file and choose "Open With -> Component Descriptor Editor"
+ </p>
+ <p>
+ <img src="./images/getting-started/call-cde.gif" alt="Call Component Descriptor Editor" border="0" />
+ </p>
+ </li>
+ <li>
+ <p>Select the "TypeSystem" tab at the bottom to show the type system definition page.</p>
+ </li>
+ <li>
+ <p>Press the "Add Type" button to add the new type. Use "org.apache.uima.tutorial.RoomNumber"
+ as type name and finish with "OK". The supertype "uima.tcas.Annotation" is correct.</p>
+ </li>
+ </ol>
+ We just added the first type to our RoomNumberAnnotator type system. Now we want to add an additional
+ feature to the created type to store the annotation meta information
+ <ol>
+ <li>
+ <p>Select the "org.apache.uima.tutorial.RoomNumber" type by clicking it.</p>
+ </li>
+ <li>
+ <p>Click the "Add..." button to add a feature to the type and specify "building"
+ as feature name and "uima.cas.String" as range type.
+ This means that the "building" feature is a String based feature.
+ Finish the dialog by clicking "OK".</p>
+ </li>
+ <li>
+ <p>Save the descriptor file</p>
+ <p>
+ <img src="./images/getting-started/cde-typedef.gif" alt="Type System definition" border="0" />
+ </p>
+ </li>
+ </ol>
+ That's all - we defined the UIMA type system for the RoomNumberAnnotator that we use later when we
+ implement the annotator code. To use defined types easily the UIMA Component Descriptor Editor
+ can generate Java classes for the defined types. To generate these classes follow the steps below:
+ <ol>
+ <li>
+ <p>Open the descriptor file in the Component Descriptor Editor and select the "Type System" tab.</p>
+ </li>
+ <li>
+ <p>Press the "JCasGen" button that will trigger the Java class generation. The generated classes
+ will be added to the "src" folder of your project in a separate package.</p>
+ <p>
+ <img src="./images/getting-started/cde-typedef-files.gif" alt="Type System definition" border="0" />
+ </p>
+
+ </li>
+ </ol>
+ Now all pre-work is done and can start implementing the annotator source code.
+ </p>
+ </subsection>
+ <subsection name="Writing the annotator code">
+ <p>
+ In this section we will create the RoomNumberAnnotator source code. For more detailed
+ information about this topic please refer to the UIMA documentation at chapter
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/tutorials_and_users_guides/tutorials_and_users_guides.html#ugr.tug.aae.developing_annotator_code">
+ Developing Your Annotator Code</a>
+ </p>
+ <p>
+ We start with creating a new Java class. Follow the steps below to create the RoomNumberAnnotator java class.
+ <ol>
+ <li>
+ <p>
+ Right-click on the "src" folder and select "New -> Class".
+ </p>
+ </li>
+ <li>
+ <p>
+ A wizard is upcoming where you can specify the Java class information shown below.
+ We will create a Java class called <code>RoomNumberAnnotator</code> that inherits
+ from the base class called <code>org.apache.uima.analysis_component.JCasAnnotator_ImplBase</code>.
+ This is the base for all UIMA annotator implementations.
+ </p>
+ <p>
+ Java class information:
+ <ul>
+ <li> Package: <code>org.apache.uima.tutorial.ex1</code> </li>
+ <li> Name: <code>RoomNumberAnnotator</code> </li>
+ <li> Superclass: <code>org.apache.uima.analysis_component.JCasAnnotator_ImplBase</code> </li>
+ </ul>
+ </p>
+ <p>
+ <img src="./images/getting-started/create-class.gif" alt="Class generation wizard" border="0" />
+ </p>
+ </li>
+ <li>
+ <p>
+ Press the "OK" button to create the class and to finish the wizard.
+ </p>
+ </li>
+ </ol>
+ The created Java class has a pre-defined method stub for the annotator <code>process()</code> method.
+ This method is used to implement the annotator logic. <code>process()</code> is called
+ by the UIMA framework for each document that should be processed by
+ this annotator.
+ </p>
+ <p>
+ The logic for the implementation of the RoomNumberAnnotator is shown below. Check the
+ source code comments for some additional information.
+ <table cellpadding="15"><tr><td bgcolor="lightgrey">
+ <pre >package org.apache.uima.tutorial.ex1;
+
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+import org.apache.uima.analysis_component.JCasAnnotator_ImplBase;
+import org.apache.uima.jcas.JCas;
+import org.apache.uima.tutorial.RoomNumber;
+
+public class RoomNumberAnnotator extends JCasAnnotator_ImplBase {
+ // create regular expression pattern for Yorktown room number
+ private Pattern mYorktownPattern =
+ Pattern.compile("\\b[0-4]\\d-[0-2]\\d\\d\\b");
+
+ // create regular expression pattern for Hawthorne room number
+ private Pattern mHawthornePattern =
+ Pattern.compile("\\b[G1-4][NS]-[A-Z]\\d\\d\\b");
+
+ public void process(JCas aJCas) {
+
+ // The JCas object is the data object inside UIMA where all the
+ // information is stored. It contains based on the defined
+ // types system all annotations created by previous annotators
+ // and also the document text that should be analyzed.
+
+ // get document text from JCas
+ String docText = aJCas.getDocumentText();
+
+ // search for Yorktown room numbers
+ Matcher matcher = mYorktownPattern.matcher(docText);
+ int pos = 0;
+ while (matcher.find(pos)) {
+ // match found - create the match as annotation in
+ // the JCas with some additional meta information
+ RoomNumber annotation = new RoomNumber(aJCas);
+ annotation.setBegin(matcher.start());
+ annotation.setEnd(matcher.end());
+ annotation.setBuilding("Yorktown");
+ annotation.addToIndexes();
+ pos = matcher.end();
+ }
+
+ // search for Hawthorne room numbers
+ matcher = mHawthornePattern.matcher(docText);
+ pos = 0;
+ while (matcher.find(pos)) {
+ // match found - create the match as annotation in
+ // the JCas with some additional meta information
+ RoomNumber annotation = new RoomNumber(aJCas);
+ annotation.setBegin(matcher.start());
+ annotation.setEnd(matcher.end());
+ annotation.setBuilding("Hawthorne");
+ annotation.addToIndexes();
+ pos = matcher.end();
+ }
+ }
+}</pre></td></tr></table>
+ </p>
+ <p>
+ In the current implementation we don't use the method <code>initialize()</code>. Typically
+ the <code>initialize()</code> method is used to get annotator configuration parameters that can be
+ configured by the user. In our case this could be for example the used regular expressions used
+ to detect the room numbers. For more details about configuration parameters, please refer to the
+ UIMA documentation at chapter
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/tutorials_and_users_guides/tutorials_and_users_guides.html#ugr.tug.aae.configuration_parameters">
+ Configuration Parameters</a>.
+ </p>
+ </subsection>
+ <subsection name="Testing the annotator">
+ <p>
+ After we have finished the annotator development we have to test if the annotator
+ code that we have written works as expected. To do this, we use one of the tools
+ provided by the UIMA SDK - the Cas Visual Debugger (CVD). The CVD is already available in
+ your eclipse installation since it was installed with the UIMA eclipse plugins and with
+ the UIMA example code.
+ </p>
+ <p>
+ To start the CVD and to configure the classpath do:
+ <ol>
+ <li>
+ <p>Open the eclipse "Run dialog"
+ <img src="./images/getting-started/eclipse-run-dialog.gif" alt="Eclipse run dialog" border="0" /> </p>
+ </li>
+ <li>
+ <p>Expand "Java Application" in the left window and choose "UIMA CAS Visual Debugger".
+ Now select the "Classpath" tab on the right.
+ <img src="./images/getting-started/eclipse-run-cvd.gif" alt="Eclipse CVD run dialog" border="0" />
+ </p>
+ </li>
+ <li>
+ <p>Select the "User Entries" in the classpath tab and press the "Add Projects..." button.</p>
+ </li>
+ <li>
+ <p>Mark the "RoomNumberAnnotator" project in the upcoming dialog and finish with "OK".
+ </p>
+ <p>
+ <img src="./images/getting-started/project-selection.gif" alt="RoomNumberAnnotator project selection" border="0" /></p>
+ <p>
+ Now we have added the RoomNumberAnnotator classes to the CVD classpath.
+ </p>
+ </li>
+ <li>
+ <p>Apply the classpath settings using the "Apply" button and run the CVD by selecting "Run".</p>
+ </li>
+ </ol>
+ </p>
+ <p>
+ Note: The classpath settings must only we configured once, after that you can start the CVD directly from
+ the eclipse "Run dialog".
+ </p>
+ <p>
+ To test the RoomNumberAnnotator in the CVD we have to load the created RoomNumberAnnotator
+ analysis engine descriptor.
+ <ol>
+ <li>
+ <p>
+ Choose "Run -> Load AE" and select the <code>RoomNumberAnnotatorDescriptor.xml</code> file
+ in the <code>desc</code> folder of your eclipse project.
+ </p>
+ </li>
+ <li>
+ <p>
+ Copy and past the text below for testing to the text section of the CVD.
+ This text content in passed to the annotator when running the component.
+ </p>
+ <p>
+ <table cellpadding="15"><tr><td bgcolor="lightgrey"><pre>
+Upcoming UIMA Seminars
+
+April 7, 2004 Distillery Lunch Seminar
+UIMA and its Metadata
+12:00PM-1:00PM in HAW GN-K35
+
+April 16, 2004 KM & I Department Tea
+Title: An Eclipse-based TAE Configurator Tool
+3:00PM-4:30PM in HAW GN-K35
+
+May 11, 2004 UIMA Tutorial
+9:00AM-5:00PM in HAW GN-K35
+ </pre></td></tr></table>
+ </p>
+ </li>
+ <li >
+ <p>
+ To run the annotator on the specified text, choose "Run -> RunRoomNumberAnnotatorDescriptor".
+ <img src="./images/getting-started/cvd-annotator.gif" alt="RoomNumberAnnotator in CVD" border="0" />
+ </p>
+ <p>
+ To view the analysis result produced by the annotator, click "Annotation Index" on the left and
+ choose on of the "org.apache.uima.tutorial.RoomNumber" annotations shown below. When
+ selecting one of the annotations you get the text highlighted on the right that is covered by
+ this annotation. If there are no annotations available - the annotator does not work correctly.
+ Check the log file for possible errors "Tools -> View Log File".
+ </p>
+ </li>
+ </ol>
+ </p>
+ <p>
+ For more details about the CAS Visual Debugger, please refer to the UIMA documentation
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/tools/tools.html#ugr.tools.cvd">
+ CAS Visual Debugger</a>.
+ </p>
+ </subsection>
+ <subsection name="Packaging the annotator">
+ <p>
+ After we have successfully implemented and tested our annotator we are ready
+ to package the annotator to deploy it in another application where we
+ want to use it. The annotator packaging format in UIMA is called PEAR
+ (Processing Engine ARchive) and contains all necessary information to run
+ the wrapped annotator component. For details about the PEAR packaging
+ format please refer to the UIMA documentation chapter
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/references/references.html#ugr.ref.pear">
+ PEAR Reference</a>.
+ </p>
+ <p>
+ To package the annotator we use another UIMA tooling called
+ PEAR packager. To start the PEAR packager and to create
+ the RoomNumberAnnotator PEAR package do:
+ <ol>
+ <li>
+ <p>
+ Right-click on the RoomNumberAnnotator project and call "Generate PEAR file".
+ </p>
+ </li>
+ <li>
+ <p>
+ Once the wizard is started with the first page, you have to specify
+ an annotator component ID and the annotator descriptor file that is used to run the
+ annotator component. The componentID is pre-filled and can be used as is.
+ For the annotator descriptor file, use "Browse" and select the
+ <code>RoomNumberAnnotatorDescriptor.xml</code> file in the
+ <code>desc</code> folder of your project.
+ </p>
+ <p>
+ <img src="./images/getting-started/pear-wizard-1.gif" alt="PEAR wizard" border="0" />
+ </p>
+ </li>
+ <li>
+ <p>
+ After adding these values, go to the next wizard page with the "Next" button.
+ This page shows the classpath and environment configuration for the annotator. The
+ default settings are sufficient in our case.
+ </p>
+ <p>
+ <img src="./images/getting-started/pear-wizard-2.gif" alt="PEAR wizard" border="0" />
+ </p>
+ </li>
+ <li>
+ <p>
+ Choose "Next" to get to the last wizard page.
+ </p>
+ <p>
+ <img src="./images/getting-started/pear-wizard-3.gif" alt="PEAR wizard" border="0"/>
+ </p>
+ <p>
+ This page specifies the content of the PEAR package. By default all the eclipse
+ project content is added to the PEAR. This is correct in our case and we just have to specify
+ the PEAR file name and location in the "To pear file" input field.
+ </p>
+ </li>
+ <li>
+ <p>
+ Starting the PEAR package generation process by pressing the "Finish" button.
+ Once the packaging is done, an message dialog comes up with a success message.
+ The created PEAR package is available at the specified location.
+ </p>
+ </li>
+ </ol>
+ </p>
+ <p>
+ At this point we are done with the annotator development. We created an annotator PEAR package
+ that allows us to use the annotator component easily in different applications.
+ How we handle and use PEAR packages and how we install it to other applications is not part
+ of this guide, please refer to the UIMA documentation at the
+ <a href="http://incubator.apache.org/uima/downloads/releaseDocs/2.2.1-incubating/docs/html/tools/tools.html#ugr.tools.pear.installer">
+ PEAR Installer User's Guide</a> for additional information about this topic.
+ </p>
+ </subsection>
+ </section>
+ </body>
+
+</document>
+
Modified: incubator/uima/site/trunk/uima-website/xdocs/documentation.xml
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/xdocs/documentation.xml?rev=651293&r1=651292&r2=651293&view=diff
==============================================================================
--- incubator/uima/site/trunk/uima-website/xdocs/documentation.xml (original)
+++ incubator/uima/site/trunk/uima-website/xdocs/documentation.xml Thu Apr 24 08:43:00 2008
@@ -96,6 +96,11 @@
<li><a href="doc-uima-examples.html">Getting Started: Install UIMA And Run Examples</a><br></br>
For first time UIMA users who want to know how UIMA is installed and how they can run
the UIMA analysis examples that are provided with the release package.</li>
+ <br></br>
+ <li><a href="doc-uima-annotator.html">Getting Started: Writing My First UIMA Annotator</a><br></br>
+ For UIMA beginners that want to develop their first UIMA analysis component using eclipse.
+ </li>
+
</ul>
</p>
</subsection>
Added: incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/cvd-annotator.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/cvd-annotator.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/cvd-annotator.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/eclipse-run-cvd.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/eclipse-run-cvd.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/eclipse-run-cvd.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/eclipse-run-dialog.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/eclipse-run-dialog.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/eclipse-run-dialog.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/pear-wizard-1.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/pear-wizard-1.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/pear-wizard-1.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/pear-wizard-2.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/pear-wizard-2.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/pear-wizard-2.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/pear-wizard-3.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/pear-wizard-3.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/pear-wizard-3.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/project-selection.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/project-selection.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/project-selection.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/uima_nature.gif
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/uima_nature.gif?rev=651293&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/xdocs/images/getting-started/uima_nature.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream