You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by re...@apache.org on 2013/08/31 20:46:34 UTC
svn commit: r1519203 [39/39] - in
/uima/site/trunk/uima-website/docs/d/uimafit-2.0.0: ./ api/ api/org/
api/org/apache/ api/org/apache/uima/ api/org/apache/uima/fit/
api/org/apache/uima/fit/component/
api/org/apache/uima/fit/component/class-use/ api/org...
Added: uima/site/trunk/uima-website/docs/d/uimafit-2.0.0/tools.uimafit.book.html
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/d/uimafit-2.0.0/tools.uimafit.book.html?rev=1519203&view=auto
==============================================================================
--- uima/site/trunk/uima-website/docs/d/uimafit-2.0.0/tools.uimafit.book.html (added)
+++ uima/site/trunk/uima-website/docs/d/uimafit-2.0.0/tools.uimafit.book.html Sat Aug 31 18:46:30 2013
@@ -0,0 +1,1242 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>Apache uimaFIT™ Guide and Reference</title><link rel="stylesheet" type="text/css" href="css/stylesheet-html.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book" title="Apache uimaFIT™ Guide and Reference" id="d5e1"><div xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div><h1 class="title">Apache uimaFIT™ Guide and Reference</h1></div><div><div class="authorgroup">
+ <h3 class="corpauthor">Written and maintained by the Apache UIMA™ Development Community</h3>
+ </div></div><div><p class="releaseinfo">Version 2.0.0</p></div><div><p class="copyright">Copyright © 2012, 2013 The Apache Software Foundation</p></div><div><div class="legalnotice" title="Legal Notice"><a name="d5e8"></a>
+ <p> </p>
+ <p title="License and Disclaimer">
+ <b>License and Disclaimer. </b>
+
+ The ASF licenses this documentation
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this documentation except in compliance
+ with the License. You may obtain a copy of the License at
+
+ </p><div class="blockquote"><blockquote class="blockquote">
+ <p><a class="ulink" href="http://www.apache.org/licenses/LICENSE-2.0" target="_top">http://www.apache.org/licenses/LICENSE-2.0</a></p>
+ </blockquote></div><p title="License and Disclaimer">
+
+ Unless required by applicable law or agreed to in writing,
+ this documentation and its contents are distributed under the License
+ 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.
+
+ </p>
+ <p> </p>
+ <p> </p>
+ <p title="Trademarks">
+ <b>Trademarks. </b>
+ All terms mentioned in the text that are known to be trademarks or
+ service marks have been appropriately capitalized. Use of such terms
+ in this book should not be regarded as affecting the validity of the
+ the trademark or service mark.
+
+ </p>
+ </div></div><div><p class="pubdate">August, 2013</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#ugr.tools.uimafit.introduction">1. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#d5e30">1.1. Simplify Component Implementation</a></span></dt><dt><span class="section"><a href="#d5e44">1.2. Simplify Component Instantiation</a></span></dt><dd><dl><dt><span class="section"><a href="#d5e65">1.2.1. From a class</a></span></dt><dt><span class="section"><a href="#d5e73">1.2.2. From an XML descriptor</a></span></dt></dl></dd><dt><span class="section"><a href="#d5e82">1.3. Is this cheating?</a></span></dt><dt><span class="section"><a href="#d5e102">1.4. Conclusion</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ugr.tools.uimafit.gettingstarted">2. Getting Started</a></span></dt><dd><dl><dt><span class="section"><a href="#d5e109">2.1. Adding uimaFIT to your project</a></span></dt><dd><dl><d
t><span class="section"><a href="#d5e112">2.1.1. Maven users</a></span></dt><dt><span class="section"><a href="#d5e117">2.1.2. Non-Maven users</a></span></dt></dl></dd><dt><span class="section"><a href="#d5e122">2.2. A simple analysis engine implementation</a></span></dt><dt><span class="section"><a href="#d5e137">2.3. Running the analysis engine</a></span></dt><dt><span class="section"><a href="#d5e150">2.4. Generate a descriptor file</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ugr.tools.uimafit.pipelines">3. Pipelines</a></span></dt><dt><span class="chapter"><a href="#ugr.tools.uimafit.experiments">4. Running Experiments</a></span></dt><dt><span class="chapter"><a href="#ugr.tools.uimafit.casutil">5. CAS Utilities</a></span></dt><dd><dl><dt><span class="section"><a href="#d5e218">5.1. Access methods</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ugr.tools.uimafit.configurationparameters">6. Configuration Parameters</a></span></dt><dt><span class="cha
pter"><a href="#ugr.tools.uimafit.externalresources">7. External Resources</a></span></dt><dd><dl><dt><span class="section"><a href="#d5e387">7.1. Resource injection</a></span></dt><dd><dl><dt><span class="section"><a href="#d5e389">7.1.1. Regular UIMA components</a></span></dt><dt><span class="section"><a href="#d5e396">7.1.2. uimaFIT-aware components</a></span></dt><dt><span class="section"><a href="#d5e472">7.1.3. Resources extending Resource_ImplBase</a></span></dt><dt><span class="section"><a href="#d5e482">7.1.4. Resources implementing SharedResourceObject</a></span></dt><dt><span class="section"><a href="#d5e501">7.1.5. Note on injecting resources into resources</a></span></dt></dl></dd><dt><span class="section"><a href="#d5e506">7.2. Resource locators</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ugr.tools.uimafit.typesystem">8. Type System Detection</a></span></dt><dd><dl><dt><span class="section"><a href="#d5e518">8.1. Making types auto-detectable</a></span>
</dt><dt><span class="section"><a href="#d5e536">8.2. Using type auto-detection </a></span></dt><dt><span class="section"><a href="#d5e543">8.3. Multiple META-INF/org.apache.uima.fit/types.txt files</a></span></dt><dt><span class="section"><a href="#d5e565">8.4. Performance note and caching</a></span></dt><dt><span class="section"><a href="#d5e569">8.5. Potential problems</a></span></dt><dd><dl><dt><span class="section"><a href="#d5e572">8.5.1. m2eclipse fails to copy descriptors to target/classes</a></span></dt><dt><span class="section"><a href="#d5e577">8.5.2. Class version conflicts</a></span></dt><dt><span class="section"><a href="#d5e581">8.5.3. Classes and resources in the default package</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#tools.uimafit.maven">9. uimaFIT Maven Plugin</a></span></dt><dd><dl><dt><span class="section"><a href="#d5e593">9.1. enhance goal</a></span></dt><dt><span class="section"><a href="#d5e605">9.2. generate goal</a></span></dt
></dl></dd><dt><span class="chapter"><a href="#ugr.tools.uimafit.migration">10. Migration Guide</a></span></dt><dd><dl><dt><span class="section"><a href="#d5e617">10.1. Version 1.4.0 to 2.0.0</a></span></dt><dd><dl><dt><span class="section"><a href="#d5e619">10.1.1. Changes</a></span></dt><dt><span class="section"><a href="#d5e701">10.1.2. Legacy support module</a></span></dt></dl></dd></dl></dd></dl></div>
+
+
+
+
+
+ <div class="chapter" title="Chapter 1. Introduction" id="ugr.tools.uimafit.introduction"><div class="titlepage"><div><div><h2 class="title">Chapter 1. Introduction</h2></div></div></div>
+
+ <p>While uimaFIT provides many features for a UIMA developer, there are two overarching themes
+ that most features fall under. These two sides of uimaFIT are,while complementary, largely
+ independent of each other. One of the beauties of uimaFIT is that a developer that uses one side
+ of uimaFIT extensively is not required to use the other side at all. </p>
+ <div class="section" title="1.1. Simplify Component Implementation"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="d5e30">1.1. Simplify Component Implementation</h2></div></div></div>
+
+ <p>The first broad theme of uimaFIT provides features that <span class="emphasis"><em>simplify component
+ implementation</em></span>. Our favorite example of this is the
+ <code class="classname">@ConfigurationParameter</code> annotation which allows you to annotate a
+ member variable as a configuration parameter. This annotation in combination with the method
+ <code class="methodname">ConfigurationParameterInitializer.initialize()</code> completely automates
+ the process of initializing member variables with values from the
+ <code class="interfacename">UimaContext</code> passed into your analysis engine's initialize
+ method. Similarly, the annotation <code class="classname">@ExternalResource</code> annotation in
+ combination with the method <code class="methodname">ExternalResourceInitializer.initialize()</code>
+ completely automates the binding of an external resource as defined in the
+ <code class="interfacename">UimaContext</code> to a member variable. Dispensing with manually
+ writing the code that performs these two tasks reduces effort, eliminates verbose and
+ potentially buggy boiler-plate code, and makes implementing a UIMA component more enjoyable.
+ Consider, for example, a member variable that is of type <code class="classname">Locale</code>. With
+ uimaFIT you can simply annotate the member variable with
+ <code class="classname">@ConfigurationParameter</code> and have your initialize method automatically
+ initialize the variable correctly with a string value in the
+ <code class="interfacename">UimaContext</code> such as <code class="literal">en_US</code>. </p>
+ </div>
+ <div class="section" title="1.2. Simplify Component Instantiation"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="d5e44">1.2. Simplify Component Instantiation</h2></div></div></div>
+
+ <p>The second broad theme of uimaFIT provides features that <span class="emphasis"><em>simplify component
+ instantiation</em></span>. Working with UIMA, have you ever said to yourself <span class="quote">“<span class="quote">but I
+ just want to tag some text!?</span>”</span> What does it take to <span class="quote">“<span class="quote">just tag some text?</span>”</span>
+ Here's a list of things you must do with the traditional approach:</p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>wrap your tagger as a UIMA analysis engine</p>
+ </li><li class="listitem">
+ <p>write a descriptor file for your analysis engine</p>
+ </li><li class="listitem">
+ <p>write a CAS consumer that produces the desired output</p>
+ </li><li class="listitem">
+ <p>write another descriptor file for the CAS consumer</p>
+ </li><li class="listitem">
+ <p>write a descriptor file for a collection reader</p>
+ </li><li class="listitem">
+ <p>write a descriptor file that describes a pipeline</p>
+ </li><li class="listitem">
+ <p>invoke the Collection Processing Manager with your pipeline descriptor file</p>
+ </li></ul></div>
+ <div class="section" title="1.2.1. From a class"><div class="titlepage"><div><div><h3 class="title" id="d5e65">1.2.1. From a class</h3></div></div></div>
+
+ <p>Each of these steps has its own pitfalls and can be rather time consuming. This is a
+ rather unsatisfying answer to our simple desire to just tag some text. With uimaFIT you can
+ literally eliminate all of these steps. </p>
+ <p>Here's a simple snippet of Java code that illustrates <span class="quote">“<span class="quote">tagging some text</span>”</span>
+ with uimaFIT:</p>
+ <pre class="programlisting">JCas jCas = JCasFactory.createJCas();
+
+jCas.setDocumentText("some text");
+
+AnalysisEngine tokenizer = createEngine(MyTokenizer.class);
+
+AnalysisEngine tagger = createEngine(MyTagger.class);
+
+runPipeline(jCas, tokenizer, tagger);
+
+for(Token token : iterate(jCas, Token.class)){
+ System.out.println(token.getTag());
+}</pre>
+ <p>This code assumes several static method imports (e.g.
+ <code class="methodname">createEngine()</code>) provided by uimaFIT for brevity. And while the
+ terseness of this code won't make a Python programmer blush - it is certainly much easier
+ than the seven steps outlined above! </p>
+ </div>
+ <div class="section" title="1.2.2. From an XML descriptor"><div class="titlepage"><div><div><h3 class="title" id="d5e73">1.2.2. From an XML descriptor</h3></div></div></div>
+
+ <p>uimaFIT provides mechanisms to instantiate and run UIMA components programmatically with
+ or without descriptor files. For example, if you have a descriptor file for your analysis
+ engine defined by <code class="classname">MyTagger</code> (as shown above), then you can instead
+ instantiate the analysis engine with:</p>
+ <pre class="programlisting">AnalysisEngine tagger = createEngine("mypackage.MyTagger");</pre>
+ <p>This will find the descriptor file <code class="filename">mypackage/!MyTagger.xml</code> by name.
+ Similarly, you can find a descriptor file by location with
+ <code class="methodname">createEngineFromPath()</code>. However, if you want to dispense
+ with XML descriptor files altogether (and you probably do), you can use the method
+ <code class="methodname">createEngine()</code> as shown above. One of the driving motivations
+ for creating the second side of uimaFIT is our frustration with descriptor files and our
+ desire to eliminate them. Descriptor files are difficult to maintain because they are
+ generally tightly coupled with java code, they decay without warning, they are wearisome to
+ test, and they proliferate, among other reasons.</p>
+ </div>
+ </div>
+ <div class="section" title="1.3. Is this cheating?"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="d5e82">1.3. Is this cheating?</h2></div></div></div>
+
+ <p>One question that is often raised by new uimaFIT users is whether or not it breaks the
+ <span class="emphasis"><em>UIMA way</em></span>. That is, does adopting uimaFIT lead me down a path of
+ creating UIMA components and systems that are incompatible with the traditional UIMA approach?
+ The answer to this question is <span class="emphasis"><em>no</em></span>. For starters, uimaFIT does not skirt
+ the UIMA mechanism of describing components - it only skips the XML part of it. For example,
+ when the method <code class="methodname">createEngine()</code> is called (as shown above) an
+ <code class="interfacename">AnalysisEngineDescription</code> is created for the analysis engine.
+ This is the same object type that is instantiated when a descriptor file is used. So, instead
+ of parsing XML to instantiate an analysis engine description from XML, uimaFIT uses a factory
+ method to instantiate it from method parameters. One of the happy benefits of this approach is
+ that for a given <code class="interfacename">AnalysisEnginedDescription</code> (which can be
+ obtained directly with <code class="methodname">createEngineDescription()</code>) you can generate
+ an XML descriptor file using <code class="methodname">AnalysisEngineDescription.toXML()</code>. So,
+ uimaFIT actually provides a very simple and direct path for <span class="emphasis"><em>generating</em></span>
+ XML descriptor files rather than manually creating and maintaining them! </p>
+ <p>It is also useful to clarify that if you only want to use one side or the other of
+ uimaFIT, then you are free to do so. This is possible precisely because uimaFIT does not
+ workaround UIMA's mechanisms for describing components but rather uses them directly. For
+ example, if the only thing you want to use in uimaFIT is the
+ <code class="classname">@ConfigurationParameter</code>, then you can do so without worrying about
+ what effect this will have on your descriptor files. This is because your analysis engine will
+ be initialized with exactly the same <code class="interfacename">UimaContext</code> regardless of
+ whether you instantiate your analysis engine in the <span class="emphasis"><em>UIMA way</em></span> or use one
+ of uimaFIT's factory methods. Similarly, a UIMA component does not need to be annotated with
+ <code class="classname">@ConfiguratioParameter</code> for you to make use of the
+ <code class="methodname">createEngine()</code> method. This is because when you pass
+ configuration parameter values in to the <code class="methodname">createEngine()</code> method,
+ they are added to an <code class="interfacename">AnalysisEngineDescription</code> which is used by
+ UIMA to populate a <code class="interfacename">UimaContext</code> - just as it would if you used a
+ descriptor file. </p>
+ </div>
+ <div class="section" title="1.4. Conclusion"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="d5e102">1.4. Conclusion</h2></div></div></div>
+
+ <p>Because uimaFIT can be used to simplify component implementation and instantiation it is
+ easy to assume that you can't do one without the other. This page has demonstrated that while
+ these two sides of uimaFIT complement each other, they are not coupled together and each can
+ be effectively used without the other. Similarly, by understanding how uimaFIT uses the UIMA
+ component description mechanisms directly, one can be assured that uimaFIT enables UIMA
+ development that is compatible and consistent with the UIMA standard and APIs. </p>
+ </div>
+</div>
+
+ <div class="chapter" title="Chapter 2. Getting Started" id="ugr.tools.uimafit.gettingstarted"><div class="titlepage"><div><div><h2 class="title">Chapter 2. Getting Started</h2></div></div></div>
+
+
+ <p>This quick start tutorial demonstrates how to use uimaFIT to define and set a configuration
+ parameter in an analysis engine, run it, and generate a descriptor file for it. The complete
+ code for this example can be found in the <span class="emphasis"><em>uimaFIT-examples</em></span> module.</p>
+ <div class="section" title="2.1. Adding uimaFIT to your project"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="d5e109">2.1. Adding uimaFIT to your project</h2></div></div></div>
+
+ <p>The following instructions describe how to add uimaFIT to your project's classpath.</p>
+ <div class="section" title="2.1.1. Maven users"><div class="titlepage"><div><div><h3 class="title" id="d5e112">2.1.1. Maven users</h3></div></div></div>
+
+ <p>If you use Maven, then uimaFIT can be added to your project by simply adding uimaFIT as
+ a project dependency by adding the following snippet of XML to your pom.xml file:</p>
+ <pre class="programlisting"><dependency>
+ <groupId>org.apache.uima</groupId>
+ <artifactId>uimafit-core</artifactId>
+ <version>2.0.0</version>
+</dependency></pre>
+ <p>uimaFIT distributions are hosted by Maven Central and so no repository needs to be added
+ to your pom.xml file. </p>
+ </div>
+ <div class="section" title="2.1.2. Non-Maven users"><div class="titlepage"><div><div><h3 class="title" id="d5e117">2.1.2. Non-Maven users</h3></div></div></div>
+
+ <p>If you do not build with Maven, then download uimaFIT from the <a class="ulink" href="http://uima.apache.org/downloads.cgi" target="_top">Apache UIMA downloads page</a>. The file
+ name should be uimafit-2.0.0-bin.zip. Download and unpack this file.
+ The contents of the resulting upacked directory will contain a directory called
+ <code class="filename">lib</code>. Add all of the files in this directory to your classpath.</p>
+ </div>
+ </div>
+
+ <div class="section" title="2.2. A simple analysis engine implementation"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="d5e122">2.2. A simple analysis engine implementation</h2></div></div></div>
+
+ <p> Here is the complete analysis engine implementation for this example.</p>
+
+ <pre class="programlisting">public class GetStartedQuickAE
+ extends org.apache.uima.fit.component.JCasAnnotator_ImplBase {
+
+ public static final String PARAM_STRING = "stringParam";
+ @ConfigurationParameter(name = PARAM_STRING)
+ private String stringParam;
+
+ @Override
+ public void process(JCas jCas) throws AnalysisEngineProcessException {
+ System.out.println("Hello world! Say 'hi' to " + stringParam);
+ }
+}</pre>
+ <p>The first thing to note is that the member variable <code class="varname">stringParam</code> is
+ annotated with <code class="classname">@ConfigurationParameter</code> which tells uimaFIT that this is
+ an analysis engine configuration parameter. It is best practice to create a public constant
+ for the parameter name, here <code class="code">PARAM_STRING</code> The second thing to note is that we
+ extend uimaFIT's version of the <code class="classname">JCasAnnotator_ImplBase</code>. The initialize
+ method of this super class calls:</p>
+ <pre class="programlisting">ConfigurationParameterInitializer.initializeConfigurationParameters(
+ Object, UimaContext) </pre>
+ <p>which populates the configuration parameters with the appropriate contents of the
+ <code class="interfacename">UimaContext</code>. If you do not want to extend uimaFIT's
+ <code class="classname">JCasAnnotator_ImplBase</code>, then you can call this method directly in the
+ <code class="methodname">initialize</code> method of your analysis engine or any class that
+ implements <code class="interfacename">Initializable</code>. You can call this method for an
+ instance of any class that has configuration parameters.</p>
+ </div>
+
+ <div class="section" title="2.3. Running the analysis engine"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="d5e137">2.3. Running the analysis engine</h2></div></div></div>
+
+ <p>The following lines of code demonstrate how to instantiate and run the analysis engine
+ from a main method:</p>
+ <pre class="programlisting">JCas jCas = JCasFactory.createJCas();
+
+AnalysisEngine analysisEngine = AnalysisEngineFactory.createEngine(
+ GetStartedQuickAE.class,
+ GetStartedQuickAE.PARAM_STRING, "uimaFIT");
+
+analysisEngine.process(jCas); </pre>
+
+ <p>In a more involved example, we would probably instantiate a collection reader and run this
+ analysis engine over a collection of documents. Here, it suffices to simply create a
+ <code class="interfacename">JCas</code>. Line 3 instantiates the analysis engine using
+ <code class="classname">AnalysisEngineFactory</code> and sets the string parameter named
+ <em class="parameter"><code>stringParam</code></em> to the value <code class="literal">uimaFIT</code>. Running this
+ simple program sends the following output to the console: </p>
+
+ <pre class="programlisting">Hello world! Say 'hi' to uimaFIT </pre>
+
+ <p>Normally you would be using a type system with your analysis components. When using
+ uimaFIT, it is easiest to keep your type system descriptors in your source folders and make
+ them known to uimaFIT. To do so, create a file
+ <code class="filename">META-INF/org.apache.uima.fit/types.txt</code> in a source folder and add references to
+ all your type descriptors to the file, one per line. You can also use wildcards. For example: </p>
+
+ <pre class="programlisting">classpath*:org/apache/uima/fit/examples/type/Token.xml
+classpath*:org/apache/uima/fit/examples/type/Sentence.xml
+classpath*:org/apache/uima/fit/examples/tutorial/type/*.xml </pre>
+ </div>
+
+ <div class="section" title="2.4. Generate a descriptor file"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="d5e150">2.4. Generate a descriptor file</h2></div></div></div>
+
+
+ <p>The following lines of code demonstrate how a descriptor file can be generated using the
+ class definition:</p>
+
+ <pre class="programlisting">AnalysisEngine analysisEngine = AnalysisEngineFactory.createEngine(
+ GetStartedQuickAE.class,
+ GetStartedQuickAE.PARAM_STRING, "uimaFIT");
+
+analysisEngineDescription.toXML(
+ new FileOutputStream("GetStartedQuickAE.xml"));</pre>
+
+ <p>If you open the resulting descriptor file you will see that the configuration parameter
+ <em class="parameter"><code>stringParam</code></em> is defined with the value set to
+ <code class="literal">uimaFIT</code>. We could now instantiate an analysis engine using this
+ descriptor file with a line of code like this:</p>
+
+ <pre class="programlisting">AnalysisEngineFactory.createEngine("GetStartedQuickAE");</pre>
+
+ <p>But, of course, we really wouldn't want to do that now that we can instantiate analysis
+ engines using the class definition as was done above!</p>
+
+ <p>This chapter, of course, did not demonstrate every feature of uimaFIT which provides
+ support for annotating external resources, creating aggregate engines, running pipelines,
+ testing components, among others.</p>
+ </div>
+</div>
+
+ <div class="chapter" title="Chapter 3. Pipelines" id="ugr.tools.uimafit.pipelines"><div class="titlepage"><div><div><h2 class="title">Chapter 3. Pipelines</h2></div></div></div>
+
+ <p>UIMA is a component-based architecture that allows composing various processing components
+ into a complex processing pipeline. A pipeline typically involves a <span class="emphasis"><em>collection
+ reader</em></span> which ingests documents and <span class="emphasis"><em>analysis engines</em></span> that do
+ the actual processing.</p>
+ <p>Normally, you would run a pipeline using a UIMA Collection Processing Engine or using UIMA
+ AS. uimaFIT offers a third alternative that is much simpler to use and well suited for embedding
+ UIMA pipelines into applications or for writing tests.</p>
+ <p>As uimaFIT does not supply any readers or processing components, we just assume that we have
+ written three components:</p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p><code class="classname">TextReader</code> - reads text files from a directory</p>
+ </li><li class="listitem">
+ <p><code class="classname">Tokenizer</code> - annotates tokens</p>
+ </li><li class="listitem">
+ <p><code class="classname">TokenFrequencyWriter</code> - writes a list of tokens and their
+ frequency to a file</p>
+ </li></ul></div>
+ <p>We create descriptors for all components and run them as a pipeline:</p>
+ <pre class="programlisting">CollectionReaderDescription reader =
+ CollectionReaderFactory.createReaderDescription(
+ TextReader.class,
+ TextReader.PARAM_INPUT, "/home/uimafit/documents");
+
+AnalysisEngineDescription tokenizer =
+ AnalysisEngineFactory.createEngineDescription(
+ Tokenizer.class);
+
+AnalysisEngineDescription tokenFrequencyWriter =
+ AnalysisEngineFactory.createEngineDescription(
+ TokenFrequencyWriter.class,
+ TokenFrequencyWriter.PARAM_OUTPUT, "counts.txt");
+
+SimplePipeline.runPipeline(reader, tokenizer, writer);</pre>
+ <p>Instead of running the full pipeline end-to-end, we can also process one document at a time
+ and inspect the analysis results:</p>
+ <pre class="programlisting">CollectionReaderDescription reader =
+ CollectionReaderFactory.createReaderDescription(
+ TextReader.class,
+ TextReader.PARAM_INPUT, "/home/uimafit/documents");
+
+AnalysisEngineDescription tokenizer =
+ AnalysisEngineFactory.createEngineDescription(
+ Tokenizer.class);
+
+for (JCas jcas : SimplePipeline.iteratePipeline(reader, tokenizer)) {
+ System.out.printf("Found %d tokens%n",
+ JCasUtil.select(jcas, Token.class).size());
+}</pre>
+</div>
+
+ <div class="chapter" title="Chapter 4. Running Experiments" id="ugr.tools.uimafit.experiments"><div class="titlepage"><div><div><h2 class="title">Chapter 4. Running Experiments</h2></div></div></div>
+
+ <p>The <span class="emphasis"><em>uimafit-examples</em></span> module contains a package
+ <span class="package">org.apache.uima.fit.examples.experiment.pos</span> which demonstrates a very simple
+ experimental setup for testing a part-of-speech tagger. You may find this example more
+ accessible if you check out the code from subversion and build it in your own
+ environment.</p>
+ <p>The documentation for this example can be found in the code itself. Please refer to
+ <code class="classname">RunExperiment</code> as a starting point. The following is copied from the
+ javadoc comments of that file:</p>
+ <div class="blockquote"><blockquote class="blockquote">
+ <p><code class="classname">RunExperiment</code> demonstrates a very common (though simplified)
+ experimental setup in which gold standard data is available for some task and you want to
+ evaluate how well your analysis engine works against that data. Here we are evaluating
+ <code class="classname">BaselineTagger</code> which is a (ridiculously) simple part-of-speech tagger
+ against the part-of-speech tags found in
+ <code class="filename">src/main/resources/org/apache/uima/fit/examples/pos/sample-gold.txt</code></p>
+ </blockquote></div>
+ <p>The basic strategy is as follows:</p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>post the data <span class="emphasis"><em>as is</em></span> into the default view,</p>
+ </li><li class="listitem">
+ <p>parse the gold-standard tokens and part-of-speech tags and put the results into another
+ view we will call <span class="emphasis"><em>GOLD_VIEW</em></span>,</p>
+ </li><li class="listitem">
+ <p>create another view called <span class="emphasis"><em>SYSTEM_VIEW</em></span> and copy the text and
+ <code class="classname">Token</code> annotations from the <span class="emphasis"><em>GOLD_VIEW</em></span> into this
+ view,</p>
+ </li><li class="listitem">
+ <p>run the <code class="classname">BaselineTagger</code> on the <span class="emphasis"><em>SYSTEM_VIEW</em></span>
+ over the copied <code class="classname">Token</code> annoations,</p>
+ </li><li class="listitem">
+ <p>evaluate the part-of-speech tags found in the <span class="emphasis"><em>SYSTEM_VIEW</em></span> with
+ those in the <span class="emphasis"><em>GOLD_VIEW.</em></span></p>
+ </li></ul></div>
+</div>
+
+ <div class="chapter" title="Chapter 5. CAS Utilities" id="ugr.tools.uimafit.casutil"><div class="titlepage"><div><div><h2 class="title">Chapter 5. CAS Utilities</h2></div></div></div>
+
+ <p>uimaFIT facilitates working with the CAS and JCas by offering various convenient methods for
+ accessing and navigating annotations and feature structures. Additionally, the the convenience
+ methods for JCas access are fully type-safe and return the JCas type or a collection of the JCas
+ type which you wanted to access.</p>
+ <div class="section" title="5.1. Access methods"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="d5e218">5.1. Access methods</h2></div></div></div>
+
+ <p>uimaFIT supports the following convenience methods for accessing CAS and JCas structures.
+ All methods respect the UIMA index definitions and return annotations or feature structures in
+ the order defined by the indexes. Unless the default UIMA index for annotations has been
+ overwritten, annotations are returned sorted by begin (increasing) and end
+ (decreasing).</p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p><code class="code">select(cas, type)</code> - fetch all annotations of the given type from the
+ CAS/JCas. Variants of this method also exist to fetch annotations from a
+ <span class="type">FSList</span> or <span class="type">FSArray</span>.</p>
+ </li><li class="listitem">
+ <p><code class="code">selectAll(cas)</code> - fetch all annotations from the CAS or fetch all feature
+ structures from the JCas.</p>
+ </li><li class="listitem">
+ <p><code class="code">selectBetween(type, annotation1, annotation2)</code>* - fetch all annotations
+ between the given two annotations.</p>
+ </li><li class="listitem">
+ <p><code class="code">selectCovered(type, annotation)</code>* - fetch all annotations covered by the
+ given annotation. If this operation is used intensively, <code class="code">indexCovered(...)</code>
+ should be used to pre-calculate annotation covering information.</p>
+ </li><li class="listitem">
+ <p><code class="code">selectCovering(type, annotation)*</code> - fetch all annotations covering the
+ given annotation. If this operation is used intensively, <code class="code">indexCovering(...)</code>
+ should be used to pre-calculate annotation covering information.</p>
+ </li><li class="listitem">
+ <p><code class="code">selectByIndex(cas, type, n)</code> - fetch the n-th feature structure of the
+ given type.</p>
+ </li><li class="listitem">
+ <p><code class="code">selectSingle(cas, type)</code> - fetch the single feature structure of the given
+ type. An exception is thrown if there is not exactly one feature structure of the type.
+ </p>
+ </li><li class="listitem">
+ <p><code class="code">selectSingleRelative(type, annotation, n)</code>* - fetch a single annotation
+ relative to the given annotation. A positive <em class="parameter"><code>n</code></em> fetches the n-th
+ annotation right of the specified annotation, while the a negative
+ <em class="parameter"><code>n</code></em> fetches to the left.</p>
+ </li><li class="listitem">
+ <p><code class="code">selectPreceding(type, annotation, n)</code>* - fetch the n annotations preceding
+ the given annotation. If there are less then n preceding annotations, all preceding
+ annotations are returned.</p>
+ </li><li class="listitem">
+ <p><code class="code">selectFollowing(type, annotation, n)</code>* - fetch the n annotations following
+ the given annotation. If there are less then n following annotations, all following
+ annotations are returned.</p>
+ </li></ul></div>
+ <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+ <p>For historical reasons, the method marked with * also exist in a version that accepts a
+ CAS/JCas as the first argument. These may not work as expected when the annoation arguments
+ provided to the method are from a different CAS/JCas/view. Also, for any method accepting
+ two annotations, these should come from the same CAS/JCas/view. In future, the potentially
+ problematic signatures may be deprecated, removed, or throw exeptions if these conditions
+ are not met.</p>
+ </div>
+ <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+ <p>You should expect the structures returned by these methods to be backed by the CAS/JCas
+ contents. In particular, if you remove any feature structures from the CAS while iterating
+ over these structures may cause failures. For this reason, you should also not hold on to
+ these structures longer than necessary, as is the case for UIMA <code class="code">FSIterator</code>s as
+ well.</p>
+ </div>
+ <p>Depending on whether one works with a CAS or JCas, the respective methods are available
+ from the JCasUtil or CasUtil classes. </p>
+ <p>JCasUtil expect a JCas wrapper class for the <em class="parameter"><code>type</code></em> argument, e.g.
+ <code class="code">select(jcas, Token.class)</code> and return this type or a collection using this
+ generic type. Any subtypes of the specified type are returned as well. CasUtil expects a UIMA
+ <span class="type">Type</span> instance. For conveniently getting these, CasUtil offers the methods
+ <code class="code">getType(CAS, Class<?>)</code> or <code class="code">getType(CAS, String)</code> which fetch a
+ type either by its JCas wrapper class or by its name.</p>
+ <p>Unless annotations are specifically required, e.g. because begin/end offsets are required,
+ the JCasUtil methods can be used to access any feature structure inheriting from
+ <span class="type">TOP</span>, not only annotations. The CasUtil methods generally work only on
+ annotations. Alternative methods ending in "FS" are provided for accessing arbitrary feature
+ structures, e.g. <code class="code">selectFS</code>.</p>
+ <p>Examples:</p>
+ <pre class="programlisting">// CAS version
+Type tokenType = CasUtil.getType(cas, "my.Token");
+for (AnnotationFS token : CasUtil.select(cas, tokenType)) {
+ ...
+}
+
+// JCas version
+for (Token token : JCasUtil.select(jcas, Token.class)) {
+ ...
+}</pre>
+ </div>
+</div>
+
+ <div class="chapter" title="Chapter 6. Configuration Parameters" id="ugr.tools.uimafit.configurationparameters"><div class="titlepage"><div><div><h2 class="title">Chapter 6. Configuration Parameters</h2></div></div></div>
+
+ <p>uimaFIT defines the <code class="classname">@ConfigurationParameter</code> annotation which can be
+ used to annotate the fields of an analysis engine or collection reader. The purpose of this
+ annotation is twofold:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>injection of parameters from the UIMA context into fields</p>
+ </li><li class="listitem">
+ <p>declaration of parameter metadata (mandatory, default value, description) which can be
+ used to generate XML descriptors</p>
+ </li></ul></div><p>In a regular UIMA component, parameters need to be manually extracted from the
+ UIMA context, typically requiring a type cast. </p>
+ <pre class="programlisting">class MyAnalysisEngine extends CasAnnotator_ImplBase {
+ public static final String PARAM_SOURCE_DIRECTORY = "sourceDirectory";
+ private File sourceDirectory;
+
+ public void initialize(UimaContext context)
+ throws ResourceInitializationException {
+
+ sourceDirectory = new File((String) context.getConfigParameterValue(
+ PARAM_SOURCE_DIRECTORY));
+ }
+}</pre>
+ <p>The component has no way to declare a default value or to declare if a parameter is optional
+ or mandatory. In addition, any documentation needs to be maintained in !JavaDoc and in the XML
+ descriptor for the component.</p>
+ <p>With uimaFIT, all this information can be declared in the component using the
+ <code class="classname">@ConfigurationParameter</code> annotation.</p><div class="table"><a name="d5e288"></a><p class="title"><b>Table 6.1. <code class="classname">@ConfigurationParameter</code> annotation</b></p><div class="table-contents">
+
+ <table summary="@ConfigurationParameter annotation" style="border-collapse: collapse;border-top: 0.5pt solid black; border-bottom: 0.5pt solid black; border-left: 0.5pt solid black; border-right: 0.5pt solid black; "><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><thead><tr><th style="border-right: 0.5pt solid black; border-bottom: 0.5pt solid black; ">Parameter</th><th style="border-right: 0.5pt solid black; border-bottom: 0.5pt solid black; ">Description</th><th style="border-bottom: 0.5pt solid black; ">Default</th></tr></thead><tbody><tr><td style="border-right: 0.5pt solid black; border-bottom: 0.5pt solid black; ">name</td><td style="border-right: 0.5pt solid black; border-bottom: 0.5pt solid black; ">parameter name</td><td style="border-bottom: 0.5pt solid black; ">name of annotated field</td></tr><tr><td style="border-right: 0.5pt solid black; border-bottom: 0.5pt solid black; ">description</td><td style="border-right: 0.5pt solid black; border-bo
ttom: 0.5pt solid black; ">description of the parameter</td><td style="border-bottom: 0.5pt solid black; "> </td></tr><tr><td style="border-right: 0.5pt solid black; border-bottom: 0.5pt solid black; ">mandatory</td><td style="border-right: 0.5pt solid black; border-bottom: 0.5pt solid black; ">whether a non-null value must be specified </td><td style="border-bottom: 0.5pt solid black; ">true</td></tr><tr><td style="border-right: 0.5pt solid black; ">defaultValue</td><td style="border-right: 0.5pt solid black; ">the default value if no value is specified</td><td style=""> </td></tr></tbody></table>
+ </div></div><p><br class="table-break"></p>
+ <pre class="programlisting">class MyAnalysisEngine
+ extends org.apache.uima.fit.component.CasAnnotator_ImplBase {
+
+ /**
+ * Directory to read the data from.
+ */
+ public static final String PARAM_SOURCE_DIRECTORY = "sourceDirectory";
+ @ConfigurationParameter(name=PARAM_SOURCE_DIRECTORY, defaultValue=".")
+ private File sourceDirectory;
+}</pre>
+ <p>Note, that it is no longer necessary to implement the <code class="methodname">initialize()</code>
+ method. uimaFIT takes care of locating the parameter <em class="parameter"><code>sourceDirectory</code></em> in
+ the UIMA context. It recognizes that the <code class="classname">File</code> class has a
+ <code class="classname">String</code> constructor and uses that to instantiate a new
+ <code class="classname">File</code> object from the parameter. A parameter is mandatory unless
+ specified otherwise. If a mandatory parameter is not specified in the context, an exception is
+ thrown.</p>
+ <p>The <em class="parameter"><code>defaultValue</code></em> is used when generating an UIMA component
+ description from the class. It should be pointed out in particular, that uimaFIT does not make
+ use of the default value when injecting parameters into fields. For this reason, it is possible
+ to have a parameter that is mandatory but does have a default value. The default value is used
+ as a parameter value when a component description is generated via the uimaFIT factories unless
+ a parameter is specified in the factory call. If a component description in created manually
+ without specifying a value for a mandatory parameter, uimaFIT will generate an exception.</p>
+ <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+ <p>You can use the <span class="emphasis"><em>enhance</em></span> goal of the uimaFIT Maven plugin to pick up
+ the parameter description from the JavaDoc and post it to the
+ <em class="parameter"><code>description</code></em> field of the
+ <code class="classname">@ConfigurationParameter</code> annotation. This should be preferred to
+ specifying the description explicitly as part of the annotation.</p>
+ </div>
+ <p>The parameter injection mechanism is implemented in the
+ <code class="classname">ConfigurationParameterInitializer</code> class. uimaFIT provides several base
+ classes that already come with an <code class="methodname">initialize()</code> method using the
+ initializer:</p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p><code class="classname">CasAnnotator_ImplBase</code>`</p>
+ </li><li class="listitem">
+ <p><code class="classname">CasCollectionReader_ImplBase</code></p>
+ </li><li class="listitem">
+ <p><code class="classname">CasConsumer_ImplBase</code></p>
+ </li><li class="listitem">
+ <p><code class="classname">CasFlowController_ImplBase</code></p>
+ </li><li class="listitem">
+ <p><code class="classname">CasMultiplier_ImplBase</code></p>
+ </li><li class="listitem">
+ <p><code class="classname">JCasAnnotator_ImplBase</code></p>
+ </li><li class="listitem">
+ <p><code class="classname">JCasCollectionReader_ImplBase</code></p>
+ </li><li class="listitem">
+ <p><code class="classname">JCasConsumer_ImplBase</code></p>
+ </li><li class="listitem">
+ <p><code class="classname">JCasFlowController_ImplBase</code></p>
+ </li><li class="listitem">
+ <p><code class="classname">JCasMultiplier_ImplBase</code></p>
+ </li><li class="listitem">
+ <p><code class="classname">Resource_ImplBase</code></p>
+ </li></ul></div>
+ <p>The <code class="classname">ConfigurationParameterInitializer</code> can also be used with shared
+ resources:</p>
+ <pre class="programlisting">class MySharedResourceObject implements SharedResourceObject {
+ public static final String PARAM_VALUE = "Value";
+ @ConfigurationParameter(name = PARAM_VALUE, mandatory = true)
+ private String value;
+
+ public void load(DataResource aData)
+ throws ResourceInitializationException {
+
+ ConfigurationParameterInitializer.initialize(this, aData);
+ }
+}</pre>
+ <p>Fields that can be annotated with the <code class="classname">@ConfigurationParameter</code>
+ annotation are any array or collection types of primitive types (<span class="type">int</span>,
+ <span class="type">boolean</span>, <span class="type">float</span>, <span class="type">double</span>), any enum types, any types that
+ define a constructor accepting a single <code class="classname">String</code> (e.g.
+ <code class="classname">File</code>), as well as, fields of the types <code class="classname">Pattern</code>
+ and <code class="classname">Locale</code>.</p>
+</div>
+
+ <div class="chapter" title="Chapter 7. External Resources" id="ugr.tools.uimafit.externalresources"><div class="titlepage"><div><div><h2 class="title">Chapter 7. External Resources</h2></div></div></div>
+
+ <p>An analysis engine often uses some data model. This may be as simple as word frequency
+ counts or as complex as the model of a parser. Often these models can become quite large. If an
+ analysis engine is deployed multiple times in the same pipeline or runs on multiple CPU cores,
+ memory can be saved by using a shared instance of the data model. UIMA supports such a scenario
+ by so-called external resources. The following sections illustrates how external resources can
+ be used with uimaFIT.</p>
+ <p>First create a class for the shared data model. Usually this class would load its data from
+ some URI and then expose it via its methods. An example would be to load word frequency counts
+ and to provide a <code class="methodname">getFrequency()</code> method. In our simple example we do not
+ load anything from the provided URI - we just offer a method to get the URI from which data be
+ loaded.</p>
+ <pre class="programlisting">// Simple model that only stores the URI it was loaded from. Normally data
+// would be loaded from the URI instead and made accessible through methods
+// in this class. This simple example only allows accessing the URI.
+public static final class SharedModel implements SharedResourceObject {
+ private String uri;
+
+ public void load(DataResource aData)
+ throws ResourceInitializationException {
+
+ uri = aData.getUri().toString();
+ }
+
+ public String getUri() { return uri; }
+}</pre>
+ <div class="section" title="7.1. Resource injection"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="d5e387">7.1. Resource injection</h2></div></div></div>
+
+ <div class="section" title="7.1.1. Regular UIMA components"><div class="titlepage"><div><div><h3 class="title" id="d5e389">7.1.1. Regular UIMA components</h3></div></div></div>
+
+ <p>When an external resource is used in a regular UIMA component, it is usually fetched
+ from the context, cast and copied to a class member variable.</p>
+ <pre class="programlisting">class MyAnalysisEngine extends CasAnnotator_ImplBase {
+ final static String MODEL_KEY = "Model";
+ private SharedModel model;
+
+ public void initialize(UimaContext context)
+ throws ResourceInitializationException {
+
+ configuredResource = (SharedModel)
+ getContext().getResourceObject(MODEL_KEY);
+ }
+}</pre>
+ <p>uimaFIT can be used to inject external resources into such traditional components using
+ the <code class="methodname">createDependencyAndBind()</code> method. To show that this works with
+ any off-the-shelf UIMA component, the following example uses uimaFIT to configure the
+ OpenNLP Tokenizer:</p>
+ <pre class="programlisting">// Create descriptor
+AnalysisEngineDescription tokenizer = createEngineDescription(
+ Tokenizer.class,
+ UimaUtil.TOKEN_TYPE_PARAMETER, Token.class.getName(),
+ UimaUtil.SENTENCE_TYPE_PARAMETER, Sentence.class.getName());
+
+// Create the external resource dependency for the model and bind it
+createDependencyAndBind(tokenizer, UimaUtil.MODEL_PARAMETER,
+ TokenizerModelResourceImpl.class,
+ "http://opennlp.sourceforge.net/models-1.5/en-token.bin");</pre>
+ </div>
+ <div class="section" title="7.1.2. uimaFIT-aware components"><div class="titlepage"><div><div><h3 class="title" id="d5e396">7.1.2. uimaFIT-aware components</h3></div></div></div>
+
+ <p>uimaFIT provides the <code class="classname">@ExternalResource</code> annotation to inject
+ external resources directly into class member variables.</p>
+ <div class="table"><a name="d5e400"></a><p class="title"><b>Table 7.1. <code class="classname">@ExternalResource</code> annotation</b></p><div class="table-contents">
+
+ <table summary="@ExternalResource annotation" style="border-collapse: collapse;border-top: 0.5pt solid black; border-bottom: 0.5pt solid black; border-left: 0.5pt solid black; border-right: 0.5pt solid black; "><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><thead><tr><th style="border-right: 0.5pt solid black; border-bottom: 0.5pt solid black; ">Parameter</th><th style="border-right: 0.5pt solid black; border-bottom: 0.5pt solid black; ">Description</th><th style="border-bottom: 0.5pt solid black; ">Default</th></tr></thead><tbody><tr><td style="border-right: 0.5pt solid black; border-bottom: 0.5pt solid black; ">key</td><td style="border-right: 0.5pt solid black; border-bottom: 0.5pt solid black; ">Resource key</td><td style="border-bottom: 0.5pt solid black; ">field name</td></tr><tr><td style="border-right: 0.5pt solid black; border-bottom: 0.5pt solid black; ">api</td><td style="border-right: 0.5pt solid black; border-bottom: 0.5pt solid black; ">U
sed when the external resource type is different from the field type, e.g.
+ when using an ExternalResourceLocator</td><td style="border-bottom: 0.5pt solid black; ">field type</td></tr><tr><td style="border-right: 0.5pt solid black; ">mandatory</td><td style="border-right: 0.5pt solid black; ">Whether a value must be specified</td><td style="">true</td></tr></tbody></table>
+ </div></div><br class="table-break">
+ <pre class="programlisting">// Example annotator that uses the SharedModel. In the process() we only
+// test if the model was properly initialized by uimaFIT
+public static class Annotator
+ extends org.apache.uima.fit.component.JCasAnnotator_ImplBase {
+
+ final static String MODEL_KEY = "Model";
+ @ExternalResource(key = MODEL_KEY)
+ private SharedModel model;
+
+ public void process(JCas aJCas) throws AnalysisEngineProcessException {
+ assertTrue(model.getUri().endsWith("gene_model_v02.bin"));
+ // Prints the instance ID to the console - this proves the same
+ // instance of the SharedModel is used in both Annotator instances.
+ System.out.println(model);
+ }
+}</pre>
+ <p>Note, that it is no longer necessary to implement the
+ <code class="methodname">initialize()</code> method. uimaFIT takes care of locating the external
+ resource <em class="parameter"><code>Model</code></em> in the UIMA context and assigns it to the field
+ <code class="varname">model</code>. If a mandatory resource is not present in the context, an
+ exception is thrown.</p>
+ <p>The resource injection mechanism is implemented in the
+ <code class="classname">ExternalResourceInitializer</code> class. uimaFIT provides several base
+ classes that already come with an <code class="methodname">initialize()</code> method using the
+ initializer:</p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p><code class="classname">CasAnnotator_ImplBase</code></p>
+ </li><li class="listitem">
+ <p><code class="classname">CasCollectionReader_ImplBase</code></p>
+ </li><li class="listitem">
+ <p><code class="classname">CasConsumer_ImplBase</code></p>
+ </li><li class="listitem">
+ <p><code class="classname">CasFlowController_ImplBase</code></p>
+ </li><li class="listitem">
+ <p><code class="classname">CasMultiplier_ImplBase</code></p>
+ </li><li class="listitem">
+ <p><code class="classname">JCasAnnotator_ImplBase</code></p>
+ </li><li class="listitem">
+ <p><code class="classname">JCasCollectionReader_ImplBase</code></p>
+ </li><li class="listitem">
+ <p><code class="classname">JCasConsumer_ImplBase</code></p>
+ </li><li class="listitem">
+ <p><code class="classname">JCasFlowController_ImplBase</code></p>
+ </li><li class="listitem">
+ <p><code class="classname">JCasMultiplier_ImplBase</code></p>
+ </li><li class="listitem">
+ <p><code class="classname">Resource_ImplBase</code></p>
+ </li></ul></div>
+ <p>When building a pipeline, external resources can be set of a component just like
+ configuration parameters. External resources and configuration parameters can be mixed and
+ appear in any order when creating a component description.</p>
+ <p>Note that in the following example, we create only one external resource description and
+ use it to configure two different analysis engines. Because we only use a single
+ description, also only a single instance of the external resource is created and shared
+ between the two engines.
+ </p><pre class="programlisting">ExternalResourceDescription extDesc = createExternalResourceDescription(
+ SharedModel.class, new File("somemodel.bin"));
+
+// Binding external resource to each Annotator individually
+AnalysisEngineDescription aed1 = createEngineDescription(
+ Annotator.class,
+ Annotator.MODEL_KEY, extDesc);
+
+AnalysisEngineDescription aed2 = createEngineDescription(
+ Annotator.class,
+ Annotator.MODEL_KEY, extDesc);
+
+// Check the external resource was injected
+AnalysisEngineDescription aaed = createEngineDescription(aed1, aed2);
+AnalysisEngine ae = createEngine(aaed);
+ae.process(ae.newJCas());</pre>
+ <p>This example is given as a full JUnit-based example in the the
+ <span class="emphasis"><em>uimaFIT-examples</em></span> project.</p>
+ </div>
+ <div class="section" title="7.1.3. Resources extending Resource_ImplBase"><div class="titlepage"><div><div><h3 class="title" id="d5e472">7.1.3. Resources extending Resource_ImplBase</h3></div></div></div>
+
+ <p>One kind of resources extend <code class="classname">Resource_ImplBase</code>. These are the
+ easiest to handle, because uimaFIT's version of <code class="classname">Resource_ImplBase</code>
+ already implements the necessary logic. Just be sure to call
+ <code class="methodname">super.initialize()</code> when overriding
+ <code class="methodname">initialize()</code>. Also mind that external resources are not available
+ yet when <code class="methodname">initialize()</code> is called. For any initialization logic that
+ requires resources, override and implement
+ <code class="methodname">afterResourcesInitialized()</code>. Other than that, injection of
+ external resources works as usual.</p>
+ <pre class="programlisting">public static class ChainableResource extends Resource_ImplBase {
+ public final static String PARAM_CHAINED_RESOURCE = "chainedResource";
+ @ExternalResource(key = PARAM_CHAINED_RESOURCE)
+ private ChainableResource chainedResource;
+
+ public void afterResourcesInitialized() {
+ // init logic that requires external resources
+ }
+}</pre>
+ </div>
+ <div class="section" title="7.1.4. Resources implementing SharedResourceObject"><div class="titlepage"><div><div><h3 class="title" id="d5e482">7.1.4. Resources implementing SharedResourceObject</h3></div></div></div>
+
+ <p>The other kind of resources implement
+ <code class="interfacename">SharedResourceObject</code>. Since this is an interface, uimaFIT
+ cannot provide the initialization logic, so you have to implement a couple of things in the
+ resource:</p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>implement <code class="interfacename">ExternalResourceAware</code></p>
+ </li><li class="listitem">
+ <p>declare a configuration parameter
+ <code class="constant">ExternalResourceFactory.PARAM_RESOURCE_NAME</code> and return its value
+ in <code class="methodname">getResourceName()</code></p>
+ </li><li class="listitem">
+ <p>invoke <code class="methodname">ConfigurationParameterInitializer.initialize()</code> in
+ the <code class="methodname">load()</code> method.</p>
+ </li></ul></div>
+ <p>Again, mind that external resource not properly initialized until uimaFIT invokes
+ <code class="methodname">afterResourcesInitialized()</code>.</p>
+ <pre class="programlisting">public class TestSharedResourceObject implements
+ SharedResourceObject, ExternalResourceAware {
+
+ @ConfigurationParameter(name=ExternalResourceFactory.PARAM_RESOURCE_NAME)
+ private String resourceName;
+
+ public final static String PARAM_CHAINED_RESOURCE = "chainedResource";
+ @ExternalResource(key = PARAM_CHAINED_RESOURCE)
+ private ChainableResource chainedResource;
+
+ public String getResourceName() {
+ return resourceName;
+ }
+
+ public void load(DataResource aData)
+ throws ResourceInitializationException {
+
+ ConfigurationParameterInitializer.initialize(this, aData);
+ // rest of the init logic that does not require external resources
+ }
+
+ public void afterResourcesInitialized() {
+ // init logic that requires external resources
+ }
+}</pre>
+ </div>
+ <div class="section" title="7.1.5. Note on injecting resources into resources"><div class="titlepage"><div><div><h3 class="title" id="d5e501">7.1.5. Note on injecting resources into resources</h3></div></div></div>
+
+ <p>Nested resources are only initialized if they are used in a pipeline which contains at
+ least one component that calls
+ <code class="methodname">ConfigurationParameterInitializer.initialize()</code>. Any component
+ extending uimaFIT's component base classes qualifies. If you use nested resources in a
+ pipeline without any uimaFIT-aware components, you can just add uimaFIT's
+ <code class="classname">NoopAnnotator</code> to the pipeline.</p>
+ </div>
+ </div>
+ <div class="section" title="7.2. Resource locators"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="d5e506">7.2. Resource locators</h2></div></div></div>
+
+ <p>Normally, in UIMA an external resource needs to implement either
+ <code class="interfacename">SharedResourceObject</code> or
+ <code class="interfacename">Resource</code>. In order to inject arbitrary objects, uimaFIT has
+ the concept of <code class="interfacename">ExternalResourceLocator</code>. When a resource
+ implements this interface, not the resource itself is injected, but the method
+ <code class="methodname">getResource()</code> is called on the resource and the result is injected.
+ The following example illustrates how to inject an object from JNDI into a UIMA
+ component:</p>
+ <pre class="programlisting">class MyAnalysisEngine2 extends JCasAnnotator_ImplBase {
+ static final String RES_DICTIONARY = "dictionary";
+ @ExternalResource(key = RES_DICTIONARY)
+ Dictionary dictionary;
+}
+
+AnalysisEngineDescription desc = createEngineDescription(
+ MyAnalysisEngine2.class);
+
+bindResource(desc, MyAnalysisEngine2.RES_DICTIONARY,
+ JndiResourceLocator.class,
+ JndiResourceLocator.PARAM_NAME, "dictionaries/german");</pre>
+ </div>
+</div>
+
+ <div class="chapter" title="Chapter 8. Type System Detection" id="ugr.tools.uimafit.typesystem"><div class="titlepage"><div><div><h2 class="title">Chapter 8. Type System Detection</h2></div></div></div>
+
+ <p>UIMA requires that types that are used in the CAS are defined in XML files - so-called
+ <span class="emphasis"><em>type system descriptions</em></span> (TSD). Whenever a UIMA component is created, it
+ must be associated with such a type system. While it is possible to manually load the type
+ system descriptors and pass them to each UIMA component and to each created CAS, it is quite
+ inconvenient to do so. For this reason, uimaFIT supports the automatic detection of such files
+ in the classpath. Thus is becomes possible for a UIMA component provider to have component's
+ type automatically detected and thus the components becomes immediately usable by adding it to
+ the classpath.</p>
+ <div class="section" title="8.1. Making types auto-detectable"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="d5e518">8.1. Making types auto-detectable</h2></div></div></div>
+
+ <p>The provider of a type system should create a file
+ <code class="filename">META-INF/org.apache.uima.fit/types.txt</code> in the classpath. This file
+ should define the locations of the type system descriptions. Assume that a type
+ <code class="classname">org.apache.uima.fit.type.Token</code> is specified in the TSD
+ <code class="filename">org/apache/uima/fit/type/Token.xml</code>, then the file should have the
+ following contents:</p>
+ <pre class="programlisting">classpath*:org/apache/uima/fit/type/Token.xml</pre>
+ <p>To specify multiple TSDs, add additonal lines to the file. If you have a large number of
+ TSDs, you may prefer to add a pattern. Assume that we have a large number of TSDs under
+ <code class="filename">org/apache/uima/fit/type</code>, we can use the following pattern which
+ recursively scans the package <span class="package">org.apache.uima.fit.type</span> and all sub-packages
+ for XML files and tries to load them as TSDs.</p>
+ <pre class="programlisting">classpath*:org/apache/uima/fit/type/**/*.xml</pre>
+ <p>Try to design your packages structure in a way that TSDs and JCas wrapper classes
+ generated from them are separate from the rest of your code.</p>
+ <p>If it is not possible or inconvenient to add the `types.txt` file, patterns can also be
+ specified using the system property
+ <em class="parameter"><code>org.apache.uima.fit.type.import_pattern</code></em>. Multiple patterns may be
+ specified separated by semicolon<sup>[<a name="d5e532" href="#ftn.d5e532" class="footnote">1</a>]</sup>:</p>
+ <pre class="programlisting">-Dorg.apache.uima.fit.type.import_pattern=\
+ classpath*:org/apache/uima/fit/type/**/*.xml</pre>
+ </div>
+ <div class="section" title="8.2. Using type auto-detection"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="d5e536">8.2. Using type auto-detection </h2></div></div></div>
+
+ <p>The auto-detected type system can be obtained from the
+ <code class="classname">TypeSystemDescriptionFactory</code>:</p>
+ <pre class="programlisting">TypeSystemDescription tsd =
+ TypeSystemDescriptionFactory.createTypeSystemDescription()</pre>
+ <p>Popular factory methods also support auto-detection:</p>
+ <pre class="programlisting">AnalysisEngine ae = createEngine(MyEngine.class);</pre>
+ </div>
+ <div class="section" title="8.3. Multiple META-INF/org.apache.uima.fit/types.txt files"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="d5e543">8.3. Multiple META-INF/org.apache.uima.fit/types.txt files</h2></div></div></div>
+
+ <p>uimaFIT supports multiple `types.txt` files in the classpath (e.g. in differnt JARs). The
+ <code class="filename">types.txt</code> files are located via Spring using the classpath search
+ pattern: </p>
+ <pre class="programlisting">TYPE_MANIFEST_PATTERN = "classpath*:META-INF/org.apache.uima.fit/types.txt" </pre>
+ <p>This resolves to a list URLs pointing to ALL <code class="filename">types.txt</code> files. The
+ resolved URLs are unique and will point either to a specific point in the file system or into
+ a specific JAR. These URLs can be handled by the standard Java URL loading mechanism.
+ Example:</p>
+ <pre class="programlisting">jar:/path/to/syntax-types.jar!/META-INF/org.apache.uima.fit/types.txt
+jar:/path/to/token-types.jar!/META-INF/org.apache.uima.fit/types.txt</pre>
+ <p>uimaFIT then reads all patters from all of these URLs and uses these to search the
+ classpath again. The patterns now resolve to a list of URLs pointing to the individual type
+ system XML descriptors. All of these URLs are collected in a set to avoid duplicate loading
+ (for performance optimization - not strictly necessary because the UIMA type system merger can
+ handle compatible duplicates). Then the descriptors are loaded into memory and merged using
+ the standard UIMA type system merger
+ (<code class="methodname">CasCreationUtils.mergeTypeSystems()</code>). Example:</p>
+ <pre class="programlisting">jar:/path/to/syntax-types.jar!/desc/types/Syntax.xml
+jar:/path/to/token-types.jar!/org/foobar/typesystems/Tokens.xml </pre>
+ <p>Voilá, the result is a type system covering all types could be found in the
+ classpath.</p>
+ <p>It is recommended </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
+ <p>to put type system descriptors into packages resembling a namespace you "own" and to
+ use a package-scoped wildcard
+ search</p><pre class="programlisting">classpath*:org/apache/uima/fit/type/**/*.xml`</pre>
+ </li><li class="listitem">
+ <p>or when putting descriptors into a "well-known" package like
+ <span class="package">desc.type</span>, that <code class="filename">types.txt</code> file should
+ explicitly list all type system descriptors instead of using a wildcard
+ search</p><pre class="programlisting">classpath*:desc/type/Token.xml
+classpath*:desc/type/Syntax.xml </pre>
+ </li></ol></div><p>Method 1 should be preferred. Both methods can be mixed. </p>
+ </div>
+ <div class="section" title="8.4. Performance note and caching"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="d5e565">8.4. Performance note and caching</h2></div></div></div>
+
+ <p>Currently uimaFIT evaluates the patterns for TSDs once and caches the locations, but not
+ the actual merged type system description. A rescan can be forced using
+ <code class="methodname">TypeSystemDescriptionFactory.forceTypeDescriptorsScan()</code>. This may
+ change in future.</p>
+ </div>
+ <div class="section" title="8.5. Potential problems"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="d5e569">8.5. Potential problems</h2></div></div></div>
+
+ <p>The mechanism works fine. However, there are specific issues with Java in general that one
+ should be aware of.</p>
+ <div class="section" title="8.5.1. m2eclipse fails to copy descriptors to target/classes"><div class="titlepage"><div><div><h3 class="title" id="d5e572">8.5.1. m2eclipse fails to copy descriptors to target/classes</h3></div></div></div>
+
+ <p>There seems to be a bug in some older versions of m2eclipse that causes resources not
+ always to be copied to <code class="filename">target/classes</code>. If UIMA complains about type
+ definitions missing at runtime, try to <span class="emphasis"><em>clean/rebuild</em></span> your project and
+ carefully check the m2eclipse console in the console view for error messages that might
+ cause m2eclipse to abort.</p>
+ </div>
+ <div class="section" title="8.5.2. Class version conflicts"><div class="titlepage"><div><div><h3 class="title" id="d5e577">8.5.2. Class version conflicts</h3></div></div></div>
+
+ <p>A problem can occur if you end up having multiple incompatible versions of the same type
+ system in the classpath. This is a general problem and not related to the auto-detection
+ feature. It is the same as when you have incompatible version of a particular class (e.g.
+ <code class="interfacename">JCas</code> wrapper or some third-party-library) in the classpath.
+ The behavior of the Java Classloader is undefined in that case. The detection will do its
+ best to try and load everything it can find, but the UIMA type system merger may barf or you
+ may end up with undefined behavior at runtime because one of the class versions is used at
+ random. </p>
+ </div>
+ <div class="section" title="8.5.3. Classes and resources in the default package"><div class="titlepage"><div><div><h3 class="title" id="d5e581">8.5.3. Classes and resources in the default package</h3></div></div></div>
+
+ <p>It is bad practice to place classes into the default (unnamed) package. In fact it is
+ not possible to import classes from the default package in another class. Similarly it is a
+ bad idea to put resources at the root of the classpath. The Spring documentation on
+ resources <a class="ulink" href="http://static.springsource.org/spring/docs/3.0.x/reference/resources.html#resources-app-ctx-wildcards-in-resource-paths" target="_top">explains this in detail</a>.</p>
+ <p>For this reason the <code class="filename">types.txt</code> resides in
+ <code class="filename">/META-INF/org.apache.uima.fit</code> and it is suggest that type system
+ descriptors reside either in a proper package like
+ <code class="filename">/org/foobar/typesystems/XXX.xml</code> or in
+ <code class="filename">/desc/types/XXX.xml</code>. </p>
+ </div>
+ </div>
+<div class="footnotes"><br><hr width="100" align="left"><div class="footnote">
+ <p><sup>[<a id="ftn.d5e532" href="#d5e532" class="para">1</a>] </sup>The <code class="literal">\</code> in the example is used as a line-continuation indicator. It
+ and all spaces following it should be ommitted.</p>
+ </div></div></div>
+
+ <div class="chapter" title="Chapter 9. uimaFIT Maven Plugin" id="tools.uimafit.maven"><div class="titlepage"><div><div><h2 class="title">Chapter 9. uimaFIT Maven Plugin</h2></div></div></div>
+
+
+ <p>uimaFIT dynamically generates UIMA component descriptions from annotations in the Java
+ source code. The uimaFIT Maven plugin provides the ability to automatically create such
+ annotations in already compiled classes and to automatically generate XML descriptors from the
+ annotated classes.</p>
+ <div class="section" title="9.1. enhance goal"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="d5e593">9.1. enhance goal</h2></div></div></div>
+
+ <p>The goal enhance allows automatically augmenting compiled classes with uimaFIT
+ annotations. Information like vendor, copyright, or version can be obtained from the Maven
+ POM. Additionally, descriptions for parameters and components can be generated from Javadoc
+ comments. Existing annotations are not overwritten unless forced. </p>
+ <pre class="programlisting"><plugin>
+ <groupId>org.apache.uima</groupId>
+ <artifactId>uimafit-maven-plugin</artifactId>
+ <version>2.0.0</version> <!-- change to latest version -->
+ <configuration>
+ <!-- OPTIONAL -->
+ <!-- Override component description in generated descriptors. -->
+ <overrideComponentDescription>false</overrideComponentDescription>
+
+ <!-- OPTIONAL -->
+ <!-- Override version in generated descriptors. -->
+ <overrideComponentVersion>false</overrideComponentVersion>
+
+ <!-- OPTIONAL -->
+ <!-- Override vendor in generated descriptors. -->
+ <overrideComponentVendor>false</overrideComponentVendor>
+
+ <!-- OPTIONAL -->
+ <!-- Override copyright in generated descriptors. -->
+ <overrideComponentCopyright>false</overrideComponentCopyright>
+
+ <!-- OPTIONAL -->
+ <!-- Version to use in generated descriptors. -->
+ <componentVersion>${project.version}</componentVersion>
+
+ <!-- OPTIONAL -->
+ <!-- Vendor to use in generated descriptors. -->
+ <componentVendor>Apache Foundation</componentVendor>
+
+ <!-- OPTIONAL -->
+ <!-- Copyright to use in generated descriptors. -->
+ <componentCopyright>Apache Foundation 2013</componentCopyright>
+
+ <!-- OPTIONAL -->
+ <!-- Source file encoding. -->
+ <encoding>${project.build.sourceEncoding}</encoding>
+
+ <!-- OPTIONAL -->
+ <!-- Generate a report of missing meta data in
+ $project.build.directory/uimafit-missing-meta-data-report.txt -->
+ <generateMissingMetaDataReport>true</generateMissingMetaDataReport>
+
+ <!-- OPTIONAL -->
+ <!-- Fail on missing meta data. This setting has no effect unless
+ generateMissingMetaDataReport is enabled. -->
+ <failOnMissingMetaData>false</failOnMissingMetaData>
+
+ <!-- OPTIONAL -->
+ <!-- Constant name prefixes used for parameters and external resources,
+ e.g. "PARAM_". -->
+ <parameterNameConstantPrefixes>
+ <prefix>PARAM_<prefix/>
+ </parameterNameConstantPrefixes>
+
+ <!-- OPTIONAL -->
+ <!-- Fail on missing meta data. This setting has no effect unless
+ generateMissingMetaDataReport is enabled. -->
+ <externalResourceNameConstantPrefixes>
+ <prefix>KEY_<prefix/>
+ <prefix>RES_<prefix/>
+ </externalResourceNameConstantPrefixes>
+ </configuration>
+ <executions>
+ <execution>
+ <id>default</id>
+ <phase>process-classes</phase>
+ <goals>
+ <goal>enhance</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin></pre>
+ <p>When generating descriptions for configuration parameters or external resources, the
+ plugin supports a common practice of placing the Javadoc on a constant field instead of the
+ parameter or external resource field. Per default, parameter name constants must be prefixed
+ with <code class="code">PARAM_</code> and external resource key constants must be prefixed with <code class="code">RES_
+ </code>or <code class="code">KEY_</code>.</p>
+ <pre class="programlisting">/**
+ * Enable or disable my feature.
+ */
+public static final String PARAM_ENABLE_FEATURE = "enableFeature";
+@ConfigurationParameter(name=PARAM_ENABLE_FEATURE)
+private boolean enableFeature;
+
+/**
+ * My external resource.
+ */
+public static final String RES_MY_RESOURCE = "resource";
+@ExternalResource(key=RES_MY_RESOURCE)
+private MyResource resource;</pre>
+ <p>By enabling <code class="code">generateMissingMetaDataReport</code>, the build can be made to fail if
+ meta data such as parameter descriptions are missing. A report about the missing data is
+ generated in <code class="filename">uimafit-missing-meta-data-report.txt</code> in the project build
+ directory.</p>
+ </div>
+ <div class="section" title="9.2. generate goal"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="d5e605">9.2. generate goal</h2></div></div></div>
+
+ <p>The generate goal generates XML component descriptors for UIMA components. </p>
+ <pre class="programlisting"><plugin>
+ <groupId>org.apache.uima</groupId>
+ <artifactId>uimafit-maven-plugin</artifactId>
+ <version>2.0.0</version> <!-- change to latest version -->
+ <configuration>
+ <!-- OPTIONAL -->
+ <!-- Path where the generated resources are written. -->
+ <outputDirectory>
+ ${project.build.directory}/generated-sources/uimafit
+ </outputDirectory>
+
+ <!-- OPTIONAL -->
+ <!-- Skip generation of META-INF/org.apache.uima.fit/components.txt -->
+ <skipComponentsManifest>false</skipComponentsManifest>
+
+ <!-- OPTIONAL -->
+ <!-- Source file encoding. -->
+ <encoding>${project.build.sourceEncoding}</encoding>
+ </configuration>
+ <executions>
+ <execution>
+ <id>default</id>
+ <phase>process-classes</phase>
+ <goals>
+ <goal>generate</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin></pre>
+ <p>In addition to the XML descriptors, a manifest file is written to
+ <code class="filename">META-INF/org.apache.uima.fit/components.txt</code>. This file can be used to
+ conveniently locate the XML descriptors, which are written in the packages next to the classes
+ they
+ describe.</p><pre class="programlisting">classpath*:org/apache/uima/fit/examples/ExampleComponent.xml</pre>
+ <p>It is recommended to use both, the enhance and the generate goal. Both goals should be
+ specified in the same execution, first enhance, then generate:</p>
+ <pre class="programlisting"><execution>
+ <id>default</id>
+ <phase>process-classes</phase>
+ <goals>
+ <goal>enhance</goal>
+ <goal>generate</goal>
+ </goals>
+</execution></pre>
+ </div>
+
+</div>
+
+ <div class="chapter" title="Chapter 10. Migration Guide" id="ugr.tools.uimafit.migration"><div class="titlepage"><div><div><h2 class="title">Chapter 10. Migration Guide</h2></div></div></div>
+
+ <p>This section provides helpful information on incompatible chanes between versions.</p>
+ <div class="section" title="10.1. Version 1.4.0 to 2.0.0"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="d5e617">10.1. Version 1.4.0 to 2.0.0</h2></div></div></div>
+
+ <div class="section" title="10.1.1. Changes"><div class="titlepage"><div><div><h3 class="title" id="d5e619">10.1.1. Changes</h3></div></div></div>
+
+ <p title="Backwards compatibility">
+ <b>Backwards compatibility. </b>
+ Compatibility with legacy annotation is provided by the Legacy
+ support module.
+ </p>
+ <p title="Change of Maven groupId and artifactId">
+ <b>Change of Maven groupId and artifactId. </b>
+ The Maven group ID has changed from <code class="literal">org.uimafit</code> to
+ <code class="literal">org.apache.uima</code>.
+ </p>
+ <p>The artifact ID of the main uimaFIT artifact has been changed from
+ <code class="literal">uimafit</code> to <code class="literal">uimafit-core</code>.</p>
+ <p title="Change of package names">
+ <b>Change of package names. </b>
+ The base package has been renamed from <code class="literal">org.uimafit</code> to
+ <code class="literal">org.apache.uima.fit</code>. A global search/replace on Java files with for
+ lines starting with <code class="literal">import org.uimafit</code> and replacing that with
+ <code class="literal">import org.apache.uima.fit</code> should work.
+ </p>
+ <p title="Version requirements">
+ <b>Version requirements. </b>
+ Depends on UIMA 2.4.2.
+ </p>
+ <p title="@ConfigurationParameter">
+ <b>@ConfigurationParameter. </b>
+ The default value for the mandatory attribute now is <code class="literal">true</code>. The
+ default name of configuration parameters is now the name of the annotated field only. The
+ classname is no longer prefixed. The method
+ <code class="code">ConfigurationParameterFactory.createConfigurationParameterName()</code> that was
+ used to generate the prefixed name has been removed.
+ </p>
+ <p title="Type detection: META-INF/org.uimafit folder">
+ <b>Type detection: META-INF/org.uimafit folder. </b>
+ The <code class="literal">META-INF/org.uimafit</code> was renamed to
+ <code class="literal">META-INF/org.apache.uima.fit</code>.
+ </p>
+ <p title="JCasUtil">
+ <b>JCasUtil. </b>
+ The deprecated <code class="code">JCasUtil.iterate()</code> methods have been removed.
+ <code class="code">JCasUtil.select()</code> should be used instead.
+ </p>
+ <p title="AnalysisEngineFactory">
+ <b>AnalysisEngineFactory. </b>
+ All <code class="literal">createAggregateXXX</code> and <code class="literal">createPrimitiveXXX</code>
+ methods have been renamed to <code class="literal">createEngineXXX</code>. The old names are
+ deprecated and will be removed in future versions.
+ </p>
+ <p>All <code class="literal">createAnalysisEngineXXX</code> methods have been renamed to
+ <code class="literal">createEngineXXX</code>. The old names are deprecated and will be removed in
+ future versions.</p>
+ <p title="CollectionReaderFactory">
+ <b>CollectionReaderFactory. </b>
+ All <code class="literal">createDescriptionXXX</code> methods have been renamed to
+ <code class="literal">createReaderDescriptionXXX</code>. The old names are deprecated and will be
+ removed in future versions.
+ </p>
+ <p>All <code class="literal">createCollectionReaderXXX</code> methods have been renamed to
+ <code class="literal">createReaderXXX</code>. The old names are deprecated and will be removed in
+ future versions.</p>
+ <p title="JCasIterable">
+ <b>JCasIterable. </b>
+ <code class="code">JCasIterable</code> now only accepts reader and engine descriptions (no
+ instances) and no longer implements the <code class="code">Iterator</code> interface. Instead, new
+ <code class="code">JCasIterator</code> has been added, which replaces <code class="code">JCasIterable</code> in
+ that respect.
+ </p>
+ <p title="CasDumpWriter">
+ <b>CasDumpWriter. </b>
+ <code class="literal">org.uimafit.component.xwriter.CASDumpWriter</code> has been renamed to
+ <code class="literal">org.apache.uima.fit.component.CasDumpWriter</code>.
+ </p>
+ <p title="CpePipeline">
+ <b>CpePipeline. </b>
+ <code class="literal">CpePipeline</code> has been moved to a separate module with the artifact
+ ID <code class="literal">uimafit-cpe</code> to reduce the dependencies incurred by the main uimaFIT
+ artifact.
+ </p>
+ <p title="XWriter removed">
+ <b>XWriter removed. </b>
+ The <code class="literal">XWriter</code> and associated file namers have been removed as they
+ were much more complex then acutally needed. As an alternative,
+ <code class="literal">CasIOUtil</code> has been introduced providing several convenience methods
+ to read/write JCas/CAS data.
+ </p>
+ <p title="JCasFactory">
+ <b>JCasFactory. </b>
+ Methods only loading JCas data have been removed from <code class="literal">JCasFactory</code>.
+ The new methods in <code class="literal">CasIOUtil</code> can be used instead.
+ </p>
+ </div>
+ <div class="section" title="10.1.2. Legacy support module"><div class="titlepage"><div><div><h3 class="title" id="d5e701">10.1.2. Legacy support module</h3></div></div></div>
+
+ <p>The compatibility layer should allow you to migrate to uimaFIT 2.0.0 without breaking
+ anything. You should then be able to gradually change the codebase to be compatible with
+ uimaFIT 2.0.0. As far as my tests go, uimaFIT 1.x and 2.0.0 can coexist peacefully on the
+ classpath (and indeed both need to be on the classpath in order to use the legacy support
+ module).</p>
+ <p>To enable the legacy support, make sure that you have a dependency on uimaFIT 1.x and
+ then just add a dependency on the legacy module:</p>
+ <pre class="programlisting"><dependency>
+ <groupId>org.uimafit</groupId>
+ <artifactId>uimafit</artifactId>
+ <version>1.4.0</version>
+</dependency>
+<dependency>
+ <groupId>org.apache.uima</groupId>
+ <artifactId>uimafit-legacy-support</artifactId>
+ <version>2.0.0</version>
+</dependency></pre>
+ <p>uimaFIT 2.x automatically detects the presence of the legacy module and uses it - no
+ additional configuration is necessary.</p>
+ </div>
+ </div>
+</div>
+</div></body></html>
\ No newline at end of file
Propchange: uima/site/trunk/uima-website/docs/d/uimafit-2.0.0/tools.uimafit.book.html
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: uima/site/trunk/uima-website/docs/d/uimafit-2.0.0/tools.uimafit.book.html
------------------------------------------------------------------------------
svn:mime-type = text/html
Added: uima/site/trunk/uima-website/docs/d/uimafit-2.0.0/tools.uimafit.book.pdf
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/d/uimafit-2.0.0/tools.uimafit.book.pdf?rev=1519203&view=auto
==============================================================================
Binary file - no diff available.
Propchange: uima/site/trunk/uima-website/docs/d/uimafit-2.0.0/tools.uimafit.book.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf