Getting Started: Installing the Apache UIMA Java Framework and SDK, and Running Examples

This guide helps you install the Apache UIMA™ Java SDK release package and shows you how run the UIMA analysis example using some of the UIMA tooling.

Install UIMA SDK

To get started with UIMA, you first have to install the Apache UIMA Java SDK release package. The packages are available at the UIMA download page in different data formats for different platforms. Choose for example the .zip packages when you work on Windows or the .tar.gz packages when you work on Linux. Further we have two different package types, the binary distribution that contains the compiled sources with script files to run the tooling and the source distribution that only contains the sources of the release. The package you want to download and install is the core Java SDK package. (Other packages include additional annotators and tools, and an Asynchronous Scaleout package enabling deployment of UIMA configurations using clusters of machines, for higher performance.) To install the core UIMA SDK you have to: Download the perferred binary distribution package. To verify the download you can use the signature files provided for each file. For details on how to verify the download please refer to "Verifying a Release Download" Unzip the downloaded release package to a target directory of your choice. Create an UIMA_HOME environment variable that points to the target directory where you have unzipped the downloaded release package. If you haven't already set a JAVA_HOME variable, create a JAVA_HOME environment variable that points to a JDK (Java Development Kit) of your choice. UIMA requires at least a Java level 1.5 to run. For more details about the supported Java versions, please refer to the README document of the release package. Optional: If you want to have the UIMA script files in the PATH environment variable of your system you additionally have to add $UIMA_HOME/bin (or for Windows %UIMA_HOME%\bin) to your PATH settings. Optional: To use the provided examples you have to adjust the examples to your UIMA installation directory. To do that, just run the adjustExamplePaths.sh (or for Windows .bat) script in the bin subdirectory of your UIMA installation. Now the installation of UIMA is finished and all the tooling and the examples should work properly.

Running The UIMA Analysis Example

UIMA comes with many examples for the different UIMA components and artifacts that can be created. All these examples are explained and used in the UIMA documentation when the specific components or artifacts are introduced. The UIMA analysis example that we want to use now is a combination of some of these example components that shows a basic document analysis using UIMA. To run the UIMA analysis example, we use the UIMA DocumentAnalyzer tooling that comes with the UIMA SDK. The tool can run UIMA analysis components (also know as annotators) on a given set of text documents and shows the result of the analysis run at the end. To start the UIMA DocumentAnalyzer, start the documentAnalyzer.sh (or for Windows .bat) file located in the bin subdirectory of your UIMA installation. The DocumentAnalyzer window pops up where the following values must be set to run the UIMA analysis example: Input Directory: <UIMA_HOME>/examples/data Output Directory: <UIMA_HOME>/examples/data/processed AE XML Descriptor: <UIMA_HOME>/examples/descriptors/analysis_engine/UIMA_Analysis_Example.xml Replace <UIMA_HOME> above with the path of your Apache UIMA installation directory. In the sample screenshot below, the Apache UIMA installation directory was "C:\programme\apache-uima". To analyze the doccuments, click the "Run" button, which should, after a brief pause, pop up an "Analyzed Results" window. To display the analysis results for one of the documents, just double-click the desired document. The important one for the UIMA analysis example is the Apache_UIMA.xmi file. When you open this document from the result list, you will see different kind of annotations such as: EmailAddress annotations Name annotations PersonTitle annotations Sentence annotations Token annotations When selecting the check-box for those annotations the highlighting in the text for those annotations can be turned on or off. This concludes the exercise. You may wish to experiment by submitting text of your own for analysis. To do that you can use the DocumentAnalyzer in the interactive mode. Just click the "Interactive" button instead of the "Run" button when you have entered the settings for the analysis example as seen in the screenshot above. After clicking the "Interactive" button to following screen is displayed where you can enter your text. When clicking the "Analyze" button your text will be analyzed and you will see the analysis results in the annotation view in the same way as for the example above.