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 2021/05/07 10:04:01 UTC
svn commit: r1889617 [34/36] - in /uima/site/trunk/uima-website: docs/
docs/d/uimafit-current/ docs/d/uimafit-current/api/
docs/d/uimafit-current/api/org/apache/uima/fit/component/
docs/d/uimafit-current/api/org/apache/uima/fit/component/class-use/ doc...
Modified: uima/site/trunk/uima-website/docs/d/uimafit-current/tools.uimafit.book.html
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/d/uimafit-current/tools.uimafit.book.html?rev=1889617&r1=1889616&r2=1889617&view=diff
==============================================================================
--- uima/site/trunk/uima-website/docs/d/uimafit-current/tools.uimafit.book.html (original)
+++ uima/site/trunk/uima-website/docs/d/uimafit-current/tools.uimafit.book.html Fri May 7 10:03:59 2021
@@ -1,477 +1,1260 @@
-<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 3.1.0</p></div><div><p class="copyright">Copyright © 2012, 2020 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">April, 2020</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="#d5e72">1.2.2. From an XML descriptor</a></span></dt></dl></dd><dt><span class="section"><a href="#d5e81">1.3. Is this cheating?</a></span></dt><dt><span class="section"><a href="#d5e100">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="#d5e107">2.1. Adding uimaFIT to your project</a></span></dt><dd><dl><dt
><span class="section"><a href="#d5e110">2.1.1. Maven users</a></span></dt><dt><span class="section"><a href="#d5e115">2.1.2. Non-Maven users</a></span></dt></dl></dd><dt><span class="section"><a href="#d5e120">2.2. A simple analysis engine implementation</a></span></dt><dt><span class="section"><a href="#d5e135">2.3. Running the analysis engine</a></span></dt><dt><span class="section"><a href="#d5e148">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="#d5e216">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="chap
ter"><a href="#ugr.tools.uimafit.externalresources">7. External Resources</a></span></dt><dd><dl><dt><span class="section"><a href="#d5e393">7.1. Resource injection</a></span></dt><dd><dl><dt><span class="section"><a href="#d5e395">7.1.1. Regular UIMA components</a></span></dt><dt><span class="section"><a href="#d5e415">7.1.2. uimaFIT-aware components</a></span></dt><dt><span class="section"><a href="#d5e491">7.1.3. Resources extending Resource_ImplBase</a></span></dt><dt><span class="section"><a href="#d5e501">7.1.4. Resources implementing SharedResourceObject</a></span></dt><dt><span class="section"><a href="#d5e520">7.1.5. Note on injecting resources into resources</a></span></dt></dl></dd><dt><span class="section"><a href="#d5e525">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="#d5e537">8.1. Making types auto-detectable</a></span><
/dt><dt><span class="section"><a href="#d5e562">8.2. Making index definitions and type priorities auto-detectable</a></span></dt><dt><span class="section"><a href="#d5e567">8.3. Using type auto-detection </a></span></dt><dt><span class="section"><a href="#d5e574">8.4. Multiple META-INF/org.apache.uima.fit/types.txt files</a></span></dt><dt><span class="section"><a href="#d5e597">8.5. Performance note and caching</a></span></dt><dt><span class="section"><a href="#d5e601">8.6. Potential problems</a></span></dt><dd><dl><dt><span class="section"><a href="#d5e604">8.6.1. m2eclipse fails to copy descriptors to target/classes</a></span></dt><dt><span class="section"><a href="#d5e609">8.6.2. Class version conflicts</a></span></dt><dt><span class="section"><a href="#d5e613">8.6.3. Classes and resources in the default package</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#ugr.tools.uimafit.packaging">9. Building an executable JAR</a></span></dt><dt><span class="chapter
"><a href="#tools.uimafit.maven">10. uimaFIT Maven Plugin</a></span></dt><dd><dl><dt><span class="section"><a href="#d5e641">10.1. enhance goal</a></span></dt><dt><span class="section"><a href="#d5e653">10.2. generate goal</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ugr.tools.uimafit.migration">11. Migration Guide</a></span></dt><dd><dl><dt><span class="section"><a href="#d5e665">11.1. Version 3.0.x to 3.1.x</a></span></dt><dt><span class="section"><a href="#d5e700">11.2. Version 2.x to 3.x</a></span></dt><dt><span class="section"><a href="#d5e749">11.3. Version 2.3.0 to 2.4.0</a></span></dt><dt><span class="section"><a href="#d5e756">11.4. Version 2.2.0 to 2.3.0</a></span></dt><dt><span class="section"><a href="#d5e766">11.5. Version 2.1.0 to 2.2.0</a></span></dt><dt><span class="section"><a href="#d5e773">11.6. Version 2.0.0 to 2.1.0</a></span></dt><dt><span class="section"><a href="#d5e782">11.7. Version 1.4.0 to 2.0.0</a></span></dt></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">import static org.apache.uima.fit.factory.JCasFactory.createJCas;
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta name="generator" content="Asciidoctor 1.5.8">
+<meta name="author" content="Apache UIMA⢠Development Community">
+<title>Apache uimaFITâ¢</title>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
+<style>
+/* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */
+/* Uncomment @import statement below to use as custom stylesheet */
+/*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/
+article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section,summary{display:block}
+audio,canvas,video{display:inline-block}
+audio:not([controls]){display:none;height:0}
+script{display:none!important}
+html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}
+a{background:transparent}
+a:focus{outline:thin dotted}
+a:active,a:hover{outline:0}
+h1{font-size:2em;margin:.67em 0}
+abbr[title]{border-bottom:1px dotted}
+b,strong{font-weight:bold}
+dfn{font-style:italic}
+hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0}
+mark{background:#ff0;color:#000}
+code,kbd,pre,samp{font-family:monospace;font-size:1em}
+pre{white-space:pre-wrap}
+q{quotes:"\201C" "\201D" "\2018" "\2019"}
+small{font-size:80%}
+sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
+sup{top:-.5em}
+sub{bottom:-.25em}
+img{border:0}
+svg:not(:root){overflow:hidden}
+figure{margin:0}
+fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
+legend{border:0;padding:0}
+button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
+button,input{line-height:normal}
+button,select{text-transform:none}
+button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer}
+button[disabled],html input[disabled]{cursor:default}
+input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0}
+button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
+textarea{overflow:auto;vertical-align:top}
+table{border-collapse:collapse;border-spacing:0}
+*,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}
+html,body{font-size:100%}
+body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
+a:hover{cursor:pointer}
+img,object,embed{max-width:100%;height:auto}
+object,embed{height:100%}
+img{-ms-interpolation-mode:bicubic}
+.left{float:left!important}
+.right{float:right!important}
+.text-left{text-align:left!important}
+.text-right{text-align:right!important}
+.text-center{text-align:center!important}
+.text-justify{text-align:justify!important}
+.hide{display:none}
+img,object,svg{display:inline-block;vertical-align:middle}
+textarea{height:auto;min-height:50px}
+select{width:100%}
+.center{margin-left:auto;margin-right:auto}
+.stretch{width:100%}
+.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
+div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr}
+a{color:#2156a5;text-decoration:underline;line-height:inherit}
+a:hover,a:focus{color:#1d4b8f}
+a img{border:none}
+p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
+p aside{font-size:.875em;line-height:1.35;font-style:italic}
+h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
+h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
+h1{font-size:2.125em}
+h2{font-size:1.6875em}
+h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
+h4,h5{font-size:1.125em}
+h6{font-size:1em}
+hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0}
+em,i{font-style:italic;line-height:inherit}
+strong,b{font-weight:bold;line-height:inherit}
+small{font-size:60%;line-height:inherit}
+code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
+ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
+ul,ol{margin-left:1.5em}
+ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}
+ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}
+ul.square{list-style-type:square}
+ul.circle{list-style-type:circle}
+ul.disc{list-style-type:disc}
+ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
+dl dt{margin-bottom:.3125em;font-weight:bold}
+dl dd{margin-bottom:1.25em}
+abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help}
+abbr{text-transform:none}
+blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
+blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)}
+blockquote cite::before{content:"\2014 \0020"}
+blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)}
+blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
+@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
+h1{font-size:2.75em}
+h2{font-size:2.3125em}
+h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
+h4{font-size:1.4375em}}
+table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede}
+table thead,table tfoot{background:#f7f8f7}
+table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
+table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
+table tr.even,table tr.alt,table tr:nth-of-type(even){background:#f8f8f7}
+table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6}
+h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
+h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
+.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
+.clearfix::after,.float-group::after{clear:both}
+*:not(pre)>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background-color:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word}
+*:not(pre)>code.nobreak{word-wrap:normal}
+*:not(pre)>code.nowrap{white-space:nowrap}
+pre,pre>code{line-height:1.45;color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;text-rendering:optimizeSpeed}
+em em{font-style:normal}
+strong strong{font-weight:400}
+.keyseq{color:rgba(51,51,51,.8)}
+kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background-color:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
+.keyseq kbd:first-child{margin-left:0}
+.keyseq kbd:last-child{margin-right:0}
+.menuseq,.menuref{color:#000}
+.menuseq b:not(.caret),.menuref{font-weight:inherit}
+.menuseq{word-spacing:-.02em}
+.menuseq b.caret{font-size:1.25em;line-height:.8}
+.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
+b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
+b.button::before{content:"[";padding:0 3px 0 2px}
+b.button::after{content:"]";padding:0 2px 0 3px}
+p a>code:hover{color:rgba(0,0,0,.9)}
+#header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
+#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
+#header::after,#content::after,#footnotes::after,#footer::after{clear:both}
+#content{margin-top:1.25em}
+#content::before{content:none}
+#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
+#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
+#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
+#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap}
+#header .details span:first-child{margin-left:-.125em}
+#header .details span.email a{color:rgba(0,0,0,.85)}
+#header .details br{display:none}
+#header .details br+span::before{content:"\00a0\2013\00a0"}
+#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
+#header .details br+span#revremark::before{content:"\00a0|\00a0"}
+#header #revnumber{text-transform:capitalize}
+#header #revnumber::after{content:"\00a0"}
+#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
+#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
+#toc>ul{margin-left:.125em}
+#toc ul.sectlevel0>li>a{font-style:italic}
+#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
+#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
+#toc li{line-height:1.3334;margin-top:.3334em}
+#toc a{text-decoration:none}
+#toc a:active{text-decoration:underline}
+#toctitle{color:#7a2518;font-size:1.2em}
+@media screen and (min-width:768px){#toctitle{font-size:1.375em}
+body.toc2{padding-left:15em;padding-right:0}
+#toc.toc2{margin-top:0!important;background-color:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
+#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
+#toc.toc2>ul{font-size:.9em;margin-bottom:0}
+#toc.toc2 ul ul{margin-left:0;padding-left:1em}
+#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
+body.toc2.toc-right{padding-left:0;padding-right:15em}
+body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
+@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
+#toc.toc2{width:20em}
+#toc.toc2 #toctitle{font-size:1.375em}
+#toc.toc2>ul{font-size:.95em}
+#toc.toc2 ul ul{padding-left:1.25em}
+body.toc2.toc-right{padding-left:0;padding-right:20em}}
+#content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
+#content #toc>:first-child{margin-top:0}
+#content #toc>:last-child{margin-bottom:0}
+#footer{max-width:100%;background-color:rgba(0,0,0,.8);padding:1.25em}
+#footer-text{color:rgba(255,255,255,.8);line-height:1.44}
+#content{margin-bottom:.625em}
+.sect1{padding-bottom:.625em}
+@media screen and (min-width:768px){#content{margin-bottom:1.25em}
+.sect1{padding-bottom:1.25em}}
+.sect1:last-child{padding-bottom:0}
+.sect1+.sect1{border-top:1px solid #e7e7e9}
+#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
+#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
+#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
+#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
+#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
+.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
+.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
+table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
+.paragraph.lead>p,#preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
+table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:inherit}
+.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
+.admonitionblock>table td.icon{text-align:center;width:80px}
+.admonitionblock>table td.icon img{max-width:none}
+.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
+.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6)}
+.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
+.exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px}
+.exampleblock>.content>:first-child{margin-top:0}
+.exampleblock>.content>:last-child{margin-bottom:0}
+.sidebarblock{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
+.sidebarblock>:first-child{margin-top:0}
+.sidebarblock>:last-child{margin-bottom:0}
+.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
+.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
+.literalblock pre,.listingblock pre:not(.highlight),.listingblock pre[class="highlight"],.listingblock pre[class^="highlight "],.listingblock pre.CodeRay,.listingblock pre.prettyprint{background:#f7f7f8}
+.sidebarblock .literalblock pre,.sidebarblock .listingblock pre:not(.highlight),.sidebarblock .listingblock pre[class="highlight"],.sidebarblock .listingblock pre[class^="highlight "],.sidebarblock .listingblock pre.CodeRay,.sidebarblock .listingblock pre.prettyprint{background:#f2f1f1}
+.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;overflow-x:auto;padding:1em;font-size:.8125em}
+@media screen and (min-width:768px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:.90625em}}
+@media screen and (min-width:1280px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:1em}}
+.literalblock pre.nowrap,.literalblock pre.nowrap pre,.listingblock pre.nowrap,.listingblock pre.nowrap pre{white-space:pre;word-wrap:normal}
+.literalblock.output pre{color:#f7f7f8;background-color:rgba(0,0,0,.9)}
+.listingblock pre.highlightjs{padding:0}
+.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px}
+.listingblock pre.prettyprint{border-width:0}
+.listingblock>.content{position:relative}
+.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:#999}
+.listingblock:hover code[data-lang]::before{display:block}
+.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:#999}
+.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
+table.pyhltable{border-collapse:separate;border:0;margin-bottom:0;background:none}
+table.pyhltable td{vertical-align:top;padding-top:0;padding-bottom:0;line-height:1.45}
+table.pyhltable td.code{padding-left:.75em;padding-right:0}
+pre.pygments .lineno,table.pyhltable td:not(.code){color:#999;padding-left:0;padding-right:.5em;border-right:1px solid #dddddf}
+pre.pygments .lineno{display:inline-block;margin-right:.25em}
+table.pyhltable .linenodiv{background:none!important;padding-right:0!important}
+.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
+.quoteblock>.title{margin-left:-1.5em;margin-bottom:.75em}
+.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
+.quoteblock blockquote{margin:0;padding:0;border:0}
+.quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
+.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
+.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
+.verseblock{margin:0 1em 1.25em}
+.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
+.verseblock pre strong{font-weight:400}
+.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
+.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
+.quoteblock .attribution br,.verseblock .attribution br{display:none}
+.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
+.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
+.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
+.quoteblock.abstract{margin:0 1em 1.25em;display:block}
+.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
+.quoteblock.excerpt,.quoteblock .quoteblock{margin:0 0 1.25em;padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
+.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
+.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;text-align:left;margin-right:0}
+table.tableblock{max-width:100%;border-collapse:separate}
+p.tableblock:last-child{margin-bottom:0}
+td.tableblock>.content{margin-bottom:-1.25em}
+table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
+table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0}
+table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0}
+table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0}
+table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px}
+table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0}
+table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0}
+table.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0}
+table.frame-all{border-width:1px}
+table.frame-sides{border-width:0 1px}
+table.frame-topbot,table.frame-ends{border-width:1px 0}
+table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd){background:#f8f8f7}
+table.stripes-none tr,table.stripes-odd tr:nth-of-type(even){background:none}
+th.halign-left,td.halign-left{text-align:left}
+th.halign-right,td.halign-right{text-align:right}
+th.halign-center,td.halign-center{text-align:center}
+th.valign-top,td.valign-top{vertical-align:top}
+th.valign-bottom,td.valign-bottom{vertical-align:bottom}
+th.valign-middle,td.valign-middle{vertical-align:middle}
+table thead th,table tfoot th{font-weight:bold}
+tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7}
+tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
+p.tableblock>code:only-child{background:none;padding:0}
+p.tableblock{font-size:1em}
+td>div.verse{white-space:pre}
+ol{margin-left:1.75em}
+ul li ol{margin-left:1.5em}
+dl dd{margin-left:1.125em}
+dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
+ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
+ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
+ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
+ul.unstyled,ol.unstyled{margin-left:0}
+ul.checklist{margin-left:.625em}
+ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
+ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em}
+ul.inline{display:-ms-flexbox;display:-webkit-box;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
+ul.inline>li{margin-left:1.25em}
+.unstyled dl dt{font-weight:400;font-style:normal}
+ol.arabic{list-style-type:decimal}
+ol.decimal{list-style-type:decimal-leading-zero}
+ol.loweralpha{list-style-type:lower-alpha}
+ol.upperalpha{list-style-type:upper-alpha}
+ol.lowerroman{list-style-type:lower-roman}
+ol.upperroman{list-style-type:upper-roman}
+ol.lowergreek{list-style-type:lower-greek}
+.hdlist>table,.colist>table{border:0;background:none}
+.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
+td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
+td.hdlist1{font-weight:bold;padding-bottom:1.25em}
+.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
+.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
+.colist td:not([class]):first-child img{max-width:none}
+.colist td:not([class]):last-child{padding:.25em 0}
+.thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd}
+.imageblock.left{margin:.25em .625em 1.25em 0}
+.imageblock.right{margin:.25em 0 1.25em .625em}
+.imageblock>.title{margin-bottom:0}
+.imageblock.thumb,.imageblock.th{border-width:6px}
+.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
+.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
+.image.left{margin-right:.625em}
+.image.right{margin-left:.625em}
+a.image{text-decoration:none;display:inline-block}
+a.image object{pointer-events:none}
+sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
+sup.footnote a,sup.footnoteref a{text-decoration:none}
+sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
+#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
+#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
+#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
+#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
+#footnotes .footnote:last-of-type{margin-bottom:0}
+#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
+.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0}
+.gist .file-data>table td.line-data{width:99%}
+div.unbreakable{page-break-inside:avoid}
+.big{font-size:larger}
+.small{font-size:smaller}
+.underline{text-decoration:underline}
+.overline{text-decoration:overline}
+.line-through{text-decoration:line-through}
+.aqua{color:#00bfbf}
+.aqua-background{background-color:#00fafa}
+.black{color:#000}
+.black-background{background-color:#000}
+.blue{color:#0000bf}
+.blue-background{background-color:#0000fa}
+.fuchsia{color:#bf00bf}
+.fuchsia-background{background-color:#fa00fa}
+.gray{color:#606060}
+.gray-background{background-color:#7d7d7d}
+.green{color:#006000}
+.green-background{background-color:#007d00}
+.lime{color:#00bf00}
+.lime-background{background-color:#00fa00}
+.maroon{color:#600000}
+.maroon-background{background-color:#7d0000}
+.navy{color:#000060}
+.navy-background{background-color:#00007d}
+.olive{color:#606000}
+.olive-background{background-color:#7d7d00}
+.purple{color:#600060}
+.purple-background{background-color:#7d007d}
+.red{color:#bf0000}
+.red-background{background-color:#fa0000}
+.silver{color:#909090}
+.silver-background{background-color:#bcbcbc}
+.teal{color:#006060}
+.teal-background{background-color:#007d7d}
+.white{color:#bfbfbf}
+.white-background{background-color:#fafafa}
+.yellow{color:#bfbf00}
+.yellow-background{background-color:#fafa00}
+span.icon>.fa{cursor:default}
+a span.icon>.fa{cursor:inherit}
+.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
+.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
+.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
+.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
+.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
+.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
+.conum[data-value]{display:inline-block;color:#fff!important;background-color:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
+.conum[data-value] *{color:#fff!important}
+.conum[data-value]+b{display:none}
+.conum[data-value]::after{content:attr(data-value)}
+pre .conum[data-value]{position:relative;top:-.125em}
+b.conum *{color:inherit!important}
+.conum:not([data-value]):empty{display:none}
+dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
+h1,h2,p,td.content,span.alt{letter-spacing:-.01em}
+p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
+p,blockquote,dt,td.content,span.alt{font-size:1.0625rem}
+p{margin-bottom:1.25rem}
+.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
+.exampleblock>.content{background-color:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}
+.print-only{display:none!important}
+@page{margin:1.25cm .75cm}
+@media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important}
+html{font-size:80%}
+a{color:inherit!important;text-decoration:underline!important}
+a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
+a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
+abbr[title]::after{content:" (" attr(title) ")"}
+pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
+thead{display:table-header-group}
+svg{max-width:100%}
+p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
+h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
+#toc,.sidebarblock,.exampleblock>.content{background:none!important}
+#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
+body.book #header{text-align:center}
+body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
+body.book #header .details{border:0!important;display:block;padding:0!important}
+body.book #header .details span:first-child{margin-left:0!important}
+body.book #header .details br{display:block}
+body.book #header .details br+span::before{content:none!important}
+body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
+body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
+.listingblock code[data-lang]::before{display:block}
+#footer{padding:0 .9375em}
+.hide-on-print{display:none!important}
+.print-only{display:block!important}
+.hide-for-print{display:none!important}
+.show-for-print{display:inherit!important}}
+@media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem}
+.sect1{padding:0!important}
+.sect1+.sect1{border:0}
+#footer{background:none}
+#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
+@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
+</style>
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
+</head>
+<body class="book toc2 toc-left">
+<div id="header">
+<h1>Apache uimaFITâ¢</h1>
+<div class="details">
+<span id="author" class="author">Apache UIMA⢠Development Community</span><br>
+<span id="revnumber">version 3.2.0</span>
+</div>
+<div id="toc" class="toc2">
+<div id="toctitle">User Guide</div>
+<ul class="sectlevel1">
+<li><a href="#_ugr.tools.uimafit.introduction">Introduction</a>
+<ul class="sectlevel2">
+<li><a href="#_simplify_component_implementation">Simplify Component Implementation</a></li>
+<li><a href="#_simplify_component_instantiation">Simplify Component Instantiation</a>
+<ul class="sectlevel3">
+<li><a href="#_from_a_class">From a class</a></li>
+<li><a href="#_from_an_xml_descriptor">From an XML descriptor</a></li>
+</ul>
+</li>
+<li><a href="#_is_this_cheating">Is this cheating?</a></li>
+<li><a href="#_conclusion">Conclusion</a></li>
+</ul>
+</li>
+<li><a href="#_ugr.tools.uimafit.gettingstarted">Getting Started</a>
+<ul class="sectlevel2">
+<li><a href="#_adding_uimafit_to_your_project">Adding uimaFIT to your project</a>
+<ul class="sectlevel3">
+<li><a href="#_maven_users">Maven users</a></li>
+<li><a href="#_non_maven_users">Non-Maven users</a></li>
+</ul>
+</li>
+<li><a href="#_a_simple_analysis_engine_implementation">A simple analysis engine implementation</a></li>
+<li><a href="#_running_the_analysis_engine">Running the analysis engine</a></li>
+<li><a href="#_generate_a_descriptor_file">Generate a descriptor file</a></li>
+</ul>
+</li>
+<li><a href="#_ugr.tools.uimafit.pipelines">Pipelines</a>
+<ul class="sectlevel2">
+<li><a href="#_examples">Examples</a></li>
+<li><a href="#_tips_tricks">Tips & Tricks</a></li>
+</ul>
+</li>
+<li><a href="#_ugr.tools.uimafit.validation">Validating CASes</a>
+<ul class="sectlevel2">
+<li><a href="#_example_use_case">Example use case</a></li>
+<li><a href="#_defining_a_validation_check">Defining a validation check</a></li>
+<li><a href="#_registering_the_check_for_auto_detection">Registering the check for auto-detection</a></li>
+<li><a href="#_validating_a_cas">Validating a CAS</a></li>
+</ul>
+</li>
+<li><a href="#_ugr.tools.uimafit.experiments">Running Experiments</a></li>
+<li><a href="#_ugr.tools.uimafit.casutil">CAS Utilities</a>
+<ul class="sectlevel2">
+<li><a href="#_access_methods">Access methods</a></li>
+</ul>
+</li>
+<li><a href="#_ugr.tools.uimafit.configurationparameters">Configuration Parameters</a></li>
+<li><a href="#_ugr.tools.uimafit.externalresources">External Resources</a>
+<ul class="sectlevel2">
+<li><a href="#_resource_injection">Resource injection</a>
+<ul class="sectlevel3">
+<li><a href="#_regular_uima_components">Regular UIMA components</a></li>
+<li><a href="#_uimafit_aware_components">uimaFIT-aware components</a></li>
+<li><a href="#_resources_extending_resource_implbase">Resources extending Resource_ImplBase</a></li>
+<li><a href="#_resources_implementing_sharedresourceobject">Resources implementing SharedResourceObject</a></li>
+<li><a href="#_note_on_injecting_resources_into_resources">Note on injecting resources into resources</a></li>
+</ul>
+</li>
+<li><a href="#_resource_locators">Resource locators</a></li>
+</ul>
+</li>
+<li><a href="#_ugr.tools.uimafit.typesystem">Type System Detection</a>
+<ul class="sectlevel2">
+<li><a href="#_making_types_auto_detectable">Making types auto-detectable</a></li>
+<li><a href="#_making_index_definitions_and_type_priorities_auto_detectable">Making index definitions and type priorities auto-detectable</a></li>
+<li><a href="#_using_type_auto_detection">Using type auto-detection</a></li>
+<li><a href="#_multiple_meta_inforg_apache_uima_fittypes_txt_files">Multiple META-INF/org.apache.uima.fit/types.txt files</a></li>
+<li><a href="#_performance_note_and_caching">Performance note and caching</a></li>
+<li><a href="#_potential_problems">Potential problems</a>
+<ul class="sectlevel3">
+<li><a href="#_m2eclipse_fails_to_copy_descriptors_to_targetclasses">m2eclipse fails to copy descriptors to target/classes</a></li>
+<li><a href="#_class_version_conflicts">Class version conflicts</a></li>
+<li><a href="#_classes_and_resources_in_the_default_package">Classes and resources in the default package</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="#_ugr.tools.uimafit.packaging">Building an executable JAR</a></li>
+<li><a href="#_tools.uimafit.maven">uimaFIT Maven Plugin</a>
+<ul class="sectlevel2">
+<li><a href="#_enhance_goal">enhance goal</a></li>
+<li><a href="#_generate_goal">generate goal</a></li>
+</ul>
+</li>
+<li><a href="#_ugr.tools.uimafit.migration">Migration Guide</a>
+<ul class="sectlevel2">
+<li><a href="#_version_3_0_x_to_3_1_x">Version 3.0.x to 3.1.x</a></li>
+<li><a href="#_version_2_x_to_3_x">Version 2.x to 3.x</a></li>
+<li><a href="#_version_2_3_0_to_2_4_0">Version 2.3.0 to 2.4.0</a></li>
+<li><a href="#_version_2_2_0_to_2_3_0">Version 2.2.0 to 2.3.0</a></li>
+<li><a href="#_version_2_1_0_to_2_2_0">Version 2.1.0 to 2.2.0</a></li>
+<li><a href="#_version_2_0_0_to_2_1_0">Version 2.0.0 to 2.1.0</a></li>
+<li><a href="#_version_1_4_0_to_2_0_0">Version 1.4.0 to 2.0.0</a></li>
+</ul>
+</li>
+</ul>
+</div>
+</div>
+<div id="content">
+<div id="preamble">
+<div class="sectionbody">
+<div class="paragraph">
+<p>The document is a manual for users of uimaFIT, a friendly API to the Apache UIMA framework.</p>
+</div>
+<h4 id="_license_and_disclaimer" class="discrete">License and Disclaimer</h4>
+<div class="paragraph">
+<p>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>
+<div class="paragraph text-center">
+<p><a href="http://www.apache.org/licenses/LICENSE-2.0" class="bare">http://www.apache.org/licenses/LICENSE-2.0</a></p>
+</div>
+<div class="paragraph">
+<p>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>
+</div>
+<h4 id="_trademarks" class="discrete">Trademarks</h4>
+<div class="paragraph">
+<p>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>
+<div class="sect1">
+<h2 id="_ugr.tools.uimafit.introduction"><a class="anchor" href="#_ugr.tools.uimafit.introduction"></a>Introduction</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<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>
+<div class="sect2">
+<h3 id="_simplify_component_implementation"><a class="anchor" href="#_simplify_component_implementation"></a>Simplify Component Implementation</h3>
+<div class="paragraph">
+<p>The first broad theme of uimaFIT provides features that <em>simplify component
+ implementation</em>.
+Our favorite example of this is the <code class="class">@ConfigurationParameter</code> annotation which allows you to annotate a member variable as a configuration parameter.
+This annotation in combination with the method <code class="method">ConfigurationParameterInitializer.initialize()</code> completely automates the process of initializing member variables with values from the <code class="interface">UimaContext</code> passed into your analysis engine’s initialize method.
+Similarly, the annotation <code class="class">@ExternalResource</code> annotation in combination with the method <code class="method">ExternalResourceInitializer.initialize()</code> completely automates the binding of an external resource as defined in the <code class="interface">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="class">Locale</code>.
+With uimaFIT you can simply annotate the member variable with <code class="class">@ConfigurationParameter</code> and have your initialize method automatically initialize the variable correctly with a string value in the <code class="interface">UimaContext</code> such as <code>en_US</code>.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_simplify_component_instantiation"><a class="anchor" href="#_simplify_component_instantiation"></a>Simplify Component Instantiation</h3>
+<div class="paragraph">
+<p>The second broad theme of uimaFIT provides features that <em>simplify component
+ instantiation</em>.
+Working with UIMA, have you ever said to yourself “but I
+ just want to tag some text!?” What does it take to “just tag some text?” Here’s a list of things you must do with the traditional approach:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>wrap your tagger as a UIMA analysis engine</p>
+</li>
+<li>
+<p>write a descriptor file for your analysis engine</p>
+</li>
+<li>
+<p>write a CAS consumer that produces the desired output</p>
+</li>
+<li>
+<p>write another descriptor file for the CAS consumer</p>
+</li>
+<li>
+<p>write a descriptor file for a collection reader</p>
+</li>
+<li>
+<p>write a descriptor file that describes a pipeline</p>
+</li>
+<li>
+<p>invoke the Collection Processing Manager with your pipeline descriptor file</p>
+</li>
+</ul>
+</div>
+<div class="sect3">
+<h4 id="_from_a_class"><a class="anchor" href="#_from_a_class"></a>From a class</h4>
+<div class="paragraph">
+<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>
+</div>
+<div class="paragraph">
+<p>Here’s a simple snippet of Java code that illustrates “tagging some text” with uimaFIT:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-java" data-lang="java">import static org.apache.uima.fit.factory.JCasFactory.createJCas;
import static org.apache.uima.fit.pipeline.SimplePipeline.runPipeline;
-import static
+import static
org.apache.uima.fit.factory.AnalysisEngineFactory.createEngineDescription;
-
+
JCas jCas = createJCas();
jCas.setDocumentText("some text");
-runPipeline(jCas,
- createEngineDescription(MyTokenizer.class),
+runPipeline(jCas,
+ createEngineDescription(MyTokenizer.class),
createEngineDescription(MyTagger.class));
-for(Token token : iterate(jCas, Token.class)){
+for (Token token : iterate(jCas, Token.class)){
System.out.println(token.getTag());
-}</pre>
- <p>This code uses several static method imports 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="d5e72">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">AnalysisEngineDescription tagger = createEngineDescription(
- "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">createEngineDescriptionFromPath()</code>. However, if you want to dispense
- with XML descriptor files altogether (and you probably do), you can use the method
- <code class="methodname">createEngineDescription()</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="d5e81">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">createEngineDescription()</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> 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">createEngineDescription()</code> method. This is because when you pass
- configuration parameter values in to the <code class="methodname">createEngineDescription()</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="d5e100">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="d5e107">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="d5e110">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>
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>This code uses several static method imports 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>
+<div class="sect3">
+<h4 id="_from_an_xml_descriptor"><a class="anchor" href="#_from_an_xml_descriptor"></a>From an XML descriptor</h4>
+<div class="paragraph">
+<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="class">MyTagger</code> (as shown above), then you can instead instantiate the analysis engine with:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-java" data-lang="java">AnalysisEngineDescription tagger = createEngineDescription(
+ "mypackage.MyTagger");</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>This will find the descriptor file <em class="path">mypackage/MyTagger.xml</em> by name.
+Similarly, you can find a descriptor file by location with <code class="method">createEngineDescriptionFromPath()</code>.
+However, if you want to dispense with XML descriptor files altogether (and you probably do), you can use the method <code class="method">createEngineDescription()</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>
+<div class="sect2">
+<h3 id="_is_this_cheating"><a class="anchor" href="#_is_this_cheating"></a>Is this cheating?</h3>
+<div class="paragraph">
+<p>One question that is often raised by new uimaFIT users is whether or not it breaks the <em>UIMA way</em>.
+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 <em>no</em>.
+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="method">createEngineDescription()</code> is called (as shown above) an <code class="interface">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="interface">AnalysisEnginedDescription</code> you can generate an XML descriptor file using <code class="method">AnalysisEngineDescription.toXML()</code>.
+So, uimaFIT actually provides a very simple and direct path for <em>generating</em> XML descriptor files rather than manually creating and maintaining them!</p>
+</div>
+<div class="paragraph">
+<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="class">@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="interface">UimaContext</code> regardless of whether you instantiate your analysis engine in the <em>UIMA way</em> or use one of uimaFIT’s factory methods.
+Similarly, a UIMA component does not need to be annotated with <code class="class">@ConfiguratioParameter</code> for you to make use of the <code class="method">createEngineDescription()</code> method.
+This is because when you pass configuration parameter values in to the <code class="method">createEngineDescription()</code> method, they are added to an <code class="interface">AnalysisEngineDescription</code> which is used by UIMA to populate a <code class="interface">UimaContext</code> - just as it would if you used a descriptor file.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_conclusion"><a class="anchor" href="#_conclusion"></a>Conclusion</h3>
+<div class="paragraph">
+<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>
+</div>
+<div class="sect1">
+<h2 id="_ugr.tools.uimafit.gettingstarted"><a class="anchor" href="#_ugr.tools.uimafit.gettingstarted"></a>Getting Started</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<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 <em>uimaFIT-examples</em> module.</p>
+</div>
+<div class="sect2">
+<h3 id="_adding_uimafit_to_your_project"><a class="anchor" href="#_adding_uimafit_to_your_project"></a>Adding uimaFIT to your project</h3>
+<div class="paragraph">
+<p>The following instructions describe how to add uimaFIT to your project’s classpath.</p>
+</div>
+<div class="sect3">
+<h4 id="_maven_users"><a class="anchor" href="#_maven_users"></a>Maven users</h4>
+<div class="paragraph">
+<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>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-xml" data-lang="xml"><dependency>
<groupId>org.apache.uima</groupId>
<artifactId>uimafit-core</artifactId>
- <version>3.1.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="d5e115">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-3.1.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="d5e120">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
+ <version>3.2.0</version>
+</dependency></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>uimaFIT distributions are hosted by Maven Central and so no repository needs to be added to your pom.xml file.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_non_maven_users"><a class="anchor" href="#_non_maven_users"></a>Non-Maven users</h4>
+<div class="paragraph">
+<p>If you do not build with Maven, then download uimaFIT from the <a href="http://uima.apache.org/downloads.cgi">Apache UIMA downloads page</a>.
+The file name should be uimafit—​bin.zip.
+Download and unpack this file.
+The contents of the resulting upacked directory will contain a directory called <em class="path">lib</em>.
+Add all of the files in this directory to your classpath.</p>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_a_simple_analysis_engine_implementation"><a class="anchor" href="#_a_simple_analysis_engine_implementation"></a>A simple analysis engine implementation</h3>
+<div class="paragraph">
+<p>Here is the complete analysis engine implementation for this example.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-java" data-lang="java">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="d5e135">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();
-
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The first thing to note is that the member variable <code class="var">stringParam</code> is annotated with <code class="class">@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>PARAM_STRING</code> The second thing to note is that we extend uimaFIT’s version of the <code class="class">JCasAnnotator_ImplBase</code>.
+The initialize method of this super class calls:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-java" data-lang="java">ConfigurationParameterInitializer.initializeConfigurationParameters(
+ Object, UimaContext)</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>which populates the configuration parameters with the appropriate contents of the <code class="interface">UimaContext</code>.
+If you do not want to extend uimaFIT’s <code class="class">JCasAnnotator_ImplBase</code>, then you can call this method directly in the <code class="method">initialize</code> method of your analysis engine or any class that implements <code class="interface">Initializable</code>.
+You can call this method for an instance of any class that has configuration parameters.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_running_the_analysis_engine"><a class="anchor" href="#_running_the_analysis_engine"></a>Running the analysis engine</h3>
+<div class="paragraph">
+<p>The following lines of code demonstrate how to instantiate and run the analysis engine from a main method:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-java" data-lang="java">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
+analysisEngine.process(jCas);</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<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="interface">JCas</code>.
+Line 3 instantiates the analysis engine using <code class="class">AnalysisEngineFactory</code> and sets the string parameter named <code class="parameter">stringParam</code> to the value <code>uimaFIT</code>.
+Running this simple program sends the following output to the console:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>Hello world! Say 'hi' to uimaFIT</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<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 <em class="path">META-INF/org.apache.uima.fit/types.txt</em> 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>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>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="d5e148">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(
+classpath*:org/apache/uima/fit/examples/tutorial/type/*.xml</code></pre>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_generate_a_descriptor_file"><a class="anchor" href="#_generate_a_descriptor_file"></a>Generate a descriptor file</h3>
+<div class="paragraph">
+<p>The following lines of code demonstrate how a descriptor file can be generated using the class definition:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-java" data-lang="java">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 =
+ new FileOutputStream("GetStartedQuickAE.xml"));</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>If you open the resulting descriptor file you will see that the configuration parameter <code class="parameter">stringParam</code> is defined with the value set to <code>uimaFIT</code>.
+We could now instantiate an analysis engine using this descriptor file with a line of code like this:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-java" data-lang="java">AnalysisEngineFactory.createEngine("GetStartedQuickAE");</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<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>
+</div>
+<div class="paragraph">
+<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>
+</div>
+<div class="sect1">
+<h2 id="_ugr.tools.uimafit.pipelines"><a class="anchor" href="#_ugr.tools.uimafit.pipelines"></a>Pipelines</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>UIMA is a component-based architecture that allows composing various processing components into a complex processing pipeline.
+A pipeline typically involves a <em>collection
+ reader</em> which ingests documents and <em>analysis engines</em> that do the actual processing.</p>
+</div>
+<div class="paragraph">
+<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>
+</div>
+<div class="paragraph">
+<p>As uimaFIT does not supply any readers or processing components, we just assume that we have written three components:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code class="class">TextReader</code> - reads text files from a directory</p>
+</li>
+<li>
+<p><code class="class">Tokenizer</code> - annotates tokens</p>
+</li>
+<li>
+<p><code class="class">TokenFrequencyWriter</code> - writes a list of tokens and their frequency to a file</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>We create descriptors for all components and run them as a pipeline:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-java" data-lang="java">CollectionReaderDescription reader =
CollectionReaderFactory.createReaderDescription(
- TextReader.class,
+ TextReader.class,
TextReader.PARAM_INPUT, "/home/uimafit/documents");
-AnalysisEngineDescription tokenizer =
+AnalysisEngineDescription tokenizer =
AnalysisEngineFactory.createEngineDescription(
Tokenizer.class);
-AnalysisEngineDescription tokenFrequencyWriter =
+AnalysisEngineDescription tokenFrequencyWriter =
AnalysisEngineFactory.createEngineDescription(
- TokenFrequencyWriter.class,
+ 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 =
+SimplePipeline.runPipeline(reader, tokenizer, writer);</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<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>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-java" data-lang="java">CollectionReaderDescription reader =
CollectionReaderFactory.createReaderDescription(
- TextReader.class,
+ TextReader.class,
TextReader.PARAM_INPUT, "/home/uimafit/documents");
-AnalysisEngineDescription tokenizer =
+AnalysisEngineDescription tokenizer =
AnalysisEngineFactory.createEngineDescription(
Tokenizer.class);
for (JCas jcas : SimplePipeline.iteratePipeline(reader, tokenizer)) {
- System.out.printf("Found %d tokens%n",
+ System.out.printf("Found %d tokens%n",
JCasUtil.select(jcas, Token.class).size());
-}</pre>
+}</code></pre>
+</div>
</div>
+<div class="paragraph">
+<p>[[_ugr.tools.uimafit.testing"]]
+= Testing UIMA components</p>
+</div>
+<div class="paragraph">
+<p>Writing tests without uimaFIT can be a laborious process that results in fragile tests that are very verbose and break easily when code is refactored. This page demonstrates how you can write tests that are both concise and robust. Here is an outline of how you might create a test for a UIMA component <em>without</em> uimaFIT:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>write a descriptor file that configures your component appropriately for the test. This requires a minimum of 30-50 lines of XML.</p>
+</li>
+<li>
+<p>begin a test with 5-10 lines of code that instantiate the e.g. analysis engine.</p>
+</li>
+<li>
+<p>run the analysis engine against some text and test the contents of the CAS.</p>
+</li>
+<li>
+<p>repeat steps 1-3 for your next test usually by copying the descriptor file, renaming it, and changing e.g. configuration parameters.</para></p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>If you have gone through the pain of creating tests like these and then decided you should refactor your code, then you know how tedious it is to maintain them.</p>
+</div>
+<div class="paragraph">
+<p>Instead of pasting variants of the setup code (see step 2) into other tests we began to create a library of utility methods that we could call which helped shorten our code. We extended these methods so that we could instantiate our components directly without a descriptor file. These utility methods became the initial core of uimaFIT.</p>
+</div>
+<div class="sect2">
+<h3 id="_examples"><a class="anchor" href="#_examples"></a>Examples</h3>
+<div class="paragraph">
+<p>There are several examples that can be found in the <em>uimafit-examples</em> module.</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>There are a number of examples of unit tests in both the test suite for the <em>uimafit-core</em> module and the <em>uimafit-examples</em> module. In particular, there are some well-documented unit tests in the latter which can be found in <code>RoomNumberAnnotator1Test</code>.</p>
+</li>
+<li>
+<p>You can improve your testing strategy by introducing a <code>TestBase</code> class such as the one found in <code>ExamplesTestBase</code>. This class is intended as a super class for your other test classes and sets up a <code>JCas</code> that is always ready to use along with a <code>TypeSystemDescription</code> and a <code>TypePriorities</code>. An example test that subclasses from <code>ExamplesTestBase</code> is <code>RoomNumberAnnotator2Test</code>.</p>
+</li>
+<li>
+<p>Most analysis engines that you want to test will generally be downstream of many other components that add annotations to the CAS. These annotations will likely need to be in the CAS so that a downstream analysis engine will do something sensible. This poses a problem for tests because it may be undesirable to set up and run an entire pipeline every time you want to test a downstream analysis engine. Furthermore, such tests can become fragile in the face of behavior changes to upstream components. For this reason, it can be advantageous to serialize a CAS as an XMI file and use this as a starting point rather than running an entire pipeline. An example of this approach can be found in <code>XmiTest</code>.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_tips_tricks"><a class="anchor" href="#_tips_tricks"></a>Tips & Tricks</h3>
+<div class="paragraph">
[... 2358 lines stripped ...]