blob: 3ab1dc56bad88a041f66de14eaca0bf3e9663b25 [file] [log] [blame]
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
<chapter id="">
<title>Getting Started</title>
<para>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 <emphasis>uimaFIT-examples</emphasis> module.</para>
<title>Adding uimaFIT to your project</title>
<para>The following instructions describe how to add uimaFIT to your project's classpath.</para>
<title>Maven users</title>
<para>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:</para>
&lt;version><?eval ${project.version}?>&lt;/version>
<para>uimaFIT distributions are hosted by Maven Central and so no repository needs to be added
to your pom.xml file. </para>
<title>Non-Maven users</title>
<para>If you do not build with Maven, then download uimaFIT from the <ulink
url="">Apache UIMA downloads page</ulink>. The file
name should be uimafit-<?eval ${project.version}?> Download and unpack this file.
The contents of the resulting upacked directory will contain a directory called
<filename>lib</filename>. Add all of the files in this directory to your classpath.</para>
<title>A simple analysis engine implementation</title>
<para> Here is the complete analysis engine implementation for this example.</para>
<programlisting format="linespecific">public class GetStartedQuickAE
extends {
public static final String PARAM_STRING = "stringParam";
@ConfigurationParameter(name = PARAM_STRING)
private String stringParam;
public void process(JCas jCas) throws AnalysisEngineProcessException {
System.out.println("Hello world! Say 'hi' to " + stringParam);
<para>The first thing to note is that the member variable <varname>stringParam</varname> is
annotated with <classname>@ConfigurationParameter</classname> 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 <classname>JCasAnnotator_ImplBase</classname>. The initialize
method of this super class calls:</para>
<programlisting format="linespecific">ConfigurationParameterInitializer.initializeConfigurationParameters(
Object, UimaContext) </programlisting>
<para>which populates the configuration parameters with the appropriate contents of the
<interfacename>UimaContext</interfacename>. If you do not want to extend uimaFIT's
<classname>JCasAnnotator_ImplBase</classname>, then you can call this method directly in the
<methodname>initialize</methodname> method of your analysis engine or any class that
implements <interfacename>Initializable</interfacename>. You can call this method for an
instance of any class that has configuration parameters.</para>
<title>Running the analysis engine</title>
<para>The following lines of code demonstrate how to instantiate and run the analysis engine
from a main method:</para>
<programlisting>JCas jCas = JCasFactory.createJCas();
AnalysisEngine analysisEngine = AnalysisEngineFactory.createEngine(
GetStartedQuickAE.PARAM_STRING, "uimaFIT");
analysisEngine.process(jCas); </programlisting>
<para>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
<interfacename>JCas</interfacename>. Line 3 instantiates the analysis engine using
<classname>AnalysisEngineFactory</classname> and sets the string parameter named
<parameter>stringParam</parameter> to the value <literal>uimaFIT</literal>. Running this
simple program sends the following output to the console: </para>
<programlisting>Hello world! Say 'hi' to uimaFIT </programlisting>
<para>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
<filename>META-INF/</filename> 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: </para>
classpath*:org/apache/uima/fit/examples/tutorial/type/*.xml </programlisting>
<title>Generate a descriptor file</title>
<para>The following lines of code demonstrate how a descriptor file can be generated using the
class definition:</para>
<programlisting>AnalysisEngine analysisEngine = AnalysisEngineFactory.createEngine(
GetStartedQuickAE.PARAM_STRING, "uimaFIT");
new FileOutputStream("GetStartedQuickAE.xml"));</programlisting>
<para>If you open the resulting descriptor file you will see that the configuration parameter
<parameter>stringParam</parameter> is defined with the value set to
<literal>uimaFIT</literal>. We could now instantiate an analysis engine using this
descriptor file with a line of code like this:</para>
<para>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!</para>
<para>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.</para>