uimafit-doc/src/main/asciidoc/tools.uimafit.gettingstarted.adoc

// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements. See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership. The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the License for the
// specific language governing permissions and limitations
// under the License.

[[_ugr.tools.uimafit.gettingstarted]]
= Getting Started

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 _uimaFIT-examples_ module.

== Adding uimaFIT to your project

The following instructions describe how to add uimaFIT to your project's classpath.

=== Maven users

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:

[source,xml,subs="+attributes"]
----
<dependency>
  <groupId>org.apache.uima</groupId>
  <artifactId>uimafit-core</artifactId>
  <version>{revnumber}</version>
</dependency>
----

uimaFIT distributions are hosted by Maven Central and so no repository needs to be added to your pom.xml file. 

=== Non-Maven users

If you do not build with Maven, then download uimaFIT from the http://uima.apache.org/downloads.cgi[Apache UIMA downloads page].
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 [path]_lib_.
Add all of the files in this directory to your classpath.

== A simple analysis engine implementation

Here is the complete analysis engine implementation for this example.

[source,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);
  }
}
----

The first thing to note is that the member variable [var]``stringParam`` is annotated with [class]``@ConfigurationParameter`` 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 `PARAM_STRING` The second thing to note is that we extend uimaFIT's version of the [class]``JCasAnnotator_ImplBase``.
The initialize method of this super class calls:

[source,java]
----
ConfigurationParameterInitializer.initializeConfigurationParameters(
  Object, UimaContext)
----

which populates the configuration parameters with the appropriate contents of the [interface]``UimaContext``.
If you do not want to extend uimaFIT's [class]``JCasAnnotator_ImplBase``, then you can call this method directly in the [method]``initialize`` method of your analysis engine or any class that implements [interface]``Initializable``.
You can call this method for an instance of any class that has configuration parameters.

== Running the analysis engine

The following lines of code demonstrate how to instantiate and run the analysis engine from a main method:

[source,java]
----
JCas jCas = JCasFactory.createJCas();
  
AnalysisEngine analysisEngine = AnalysisEngineFactory.createEngine(
  GetStartedQuickAE.class,
  GetStartedQuickAE.PARAM_STRING, "uimaFIT");
  
analysisEngine.process(jCas);
----

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 [interface]``JCas``.
Line 3 instantiates the analysis engine using [class]``AnalysisEngineFactory`` and sets the string parameter named [parameter]``stringParam`` to the value ``uimaFIT``.
Running this simple program sends the following output to the console: 

[source]
----
Hello world!  Say 'hi' to uimaFIT
----

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 [path]_META-INF/org.apache.uima.fit/types.txt_ 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: 

[source]
----
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
----

== Generate a descriptor file

The following lines of code demonstrate how a descriptor file can be generated using the class definition:

[source,java]
----
AnalysisEngine analysisEngine = AnalysisEngineFactory.createEngine(
  GetStartedQuickAE.class,
  GetStartedQuickAE.PARAM_STRING, "uimaFIT");

analysisEngineDescription.toXML(
  new FileOutputStream("GetStartedQuickAE.xml"));
----

If you open the resulting descriptor file you will see that the configuration parameter [parameter]``stringParam`` is defined with the value set to ``uimaFIT``.
We could now instantiate an analysis engine using this descriptor file with a line of code like this:

[source,java]
----
AnalysisEngineFactory.createEngine("GetStartedQuickAE");
----

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!

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.