UIMA Tutorial and Developers' Guides

The first step in developing an annotator is to define the CAS Feature Structure types that it creates. This is done in an XML file called a Type System Descriptor. UIMA defines basic primitive types such as Boolean, Byte, Short, Integer, Long, Float, and Double, as well as Arrays of these primitive types. UIMA also defines the built-in types TOP, which is the root of the type system, analogous to Object in Java; FSArray, which is an array of Feature Structures (i.e. an array of instances of TOP); and Annotation, which we will discuss in more detail in this section.

UIMA includes an Eclipse plug-in that will help you edit Type System Descriptors, so if you are using Eclipse you will not need to worry about the details of the XML syntax. See Chapter 3, Setting up the Eclipse IDE to work with UIMA for instructions on setting up Eclipse and installing the plugin.

The Type System Descriptor for our annotator is located in the file descriptors/tutorial/ex1/TutorialTypeSystem.xml. (This and all other examples are located in the examples directory of the installation of the UIMA SDK, which can be imported into an Eclipse project for your convenience, as described in Section 3.2, “Setting up Eclipse to view Example Code”.)

In Eclipse, expand the uimaj-examples project in the Package Explorer view, and browse to the file descriptors/tutorial/ex1/TutorialTypeSystem.xml. Right-click on the file in the navigator and select Open With → Component Descriptor Editor. Once the editor opens, click on the “Type System” tab at the bottom of the editor window. You should see a view such as the following:

Our annotator will need only one type – org.apache.uima.tutorial.RoomNumber. (We use the same namespace conventions as are used for Java classes.) Just as in Java, types have supertypes. The supertype is listed in the second column of the left table. In this case our RoomNumber annotation extends from the built-in type uima.tcas.Annotation.

Descriptions can be included with types and features. In this example, there is a description associated with the building feature. To see it, hover the mouse over the feature.

The bottom tab labeled “Source” will show you the XML source file associated with this descriptor.

The built-in Annotation type declares three fields (called Features in CAS terminology). The features begin and end store the character offsets of the span of text to which the annotation refers. The feature sofa (Subject of Analysis) indicates which document the begin and end offsets point into. The sofa feature can be ignored for now since we assume in this tutorial that the CAS contains only one subject of analysis (document).

Our RoomNumber type will inherit these three features from uima.tcas.Annotation, its supertype; they are not visible in this view because inherited features are not shown. One additional feature, building, is declared. It takes a String as its value. Instead of String, we could have declared the range-type of our feature to be any other CAS type (defined or built-in).

If you are not using Eclipse, if you need to edit the type system, do so using any XML or text editor, directly. The following is the actual XML representation of the Type System displayed above in the editor:

<?xml version="1.0" encoding="UTF-8" ?>
  <typeSystemDescription xmlns="http://uima.apache.org/resourceSpecifier">
    <name>TutorialTypeSystem</name>
    <description>Type System Definition for the tutorial examples - 
        as of Exercise 1</description>
    <vendor>Apache Software Foundation</vendor>
    <version>1.0</version>
    <types>
      <typeDescription>
        <name>org.apache.uima.tutorial.RoomNumber</name>
        <description></description>
        <supertypeName>uima.tcas.Annotation</supertypeName>
        <features>
          <featureDescription>
            <name>building</name>
            <description>Building containing this room</description>
            <rangeTypeName>uima.cas.String</rangeTypeName>
          </featureDescription>
        </features>
      </typeDescription>
    </types>
  </typeSystemDescription>

When you save a descriptor that you have modified, the Component Descriptor Editor will automatically generate Java classes corresponding to the types that are defined in that descriptor (unless this has been disabled), using a utility called JCasGen. These Java classes will have the same name (including package) as the CAS types, and will have get and set methods for each of the features that you have defined.

This feature is enabled/disabled using the UIMA menu pulldown (or the Eclipse Preferences → UIMA). If automatic running of JCasGen is not happening, please make sure the option is checked:

The Java class for the example org.apache.uima.tutorial.RoomNumber type can be found in src/org/apache/uima/tutorial/RoomNumber.java . You will see how to use these generated classes in the next section.

If you are not using the Component Descriptor Editor, you will need to generate these Java classes by using the JCasGen tool. JCasGen reads a Type System Descriptor XML file and generates the corresponding Java classes that you can then use in your annotator code. To launch JCasGen, run the jcasgen shell script located in the /bin directory of the UIMA SDK installation. This should launch a GUI that looks something like this:

Use the “Browse” buttons to select your input file (TutorialTypeSystem.xml) and output directory (the root of the source tree into which you want the generated files placed). Then click the “Go” button. If the Type System Descriptor has no errors, new Java source files will be generated under the specified output directory.

There are some additional options to choose from when running JCasGen; please refer to the Chapter 8, JCasGen User's Guide for details.

Annotator implementations all implement a standard interface (AnalysisComponent), having several methods, the most important of which are:

initialize is called by the framework once when it first creates an instance of the annotator class. process is called once per item being processed. destroy may be called by the application when it is done using your annotator. There is a default implementation of this interface for annotators using the JCas, called JCasAnnotator_ImplBase, which has implementations of all required methods except for the process method.

Our annotator class extends the JCasAnnotator_ImplBase; most annotators that use the JCas will extend from this class, so they only have to implement the process method. This class is not restricted to handling just text; see Chapter 5, Annotations, Artifacts, and Sofas.

Annotators are not required to extend from the JCasAnnotator_ImplBase class; they may instead directly implement the AnalysisComponent interface, and provide all method implementations themselves. ^[1] This allows you to have your annotator inherit from some other superclass if necessary. If you would like to do this, see the Javadocs for JCasAnnotator for descriptions of the methods you must implement.

Annotator classes need to be public, cannot be declared abstract, and must have public, 0-argument constructors, so that they can be instantiated by the framework. ^[2] .

The class definition for our RoomNumberAnnotator implements the process method, and is shown here. You can find the source for this in the uimaj-examples/src/org/apache/uima/tutorial/ex1/RoomNumberAnnotator.java .

In Eclipse, open the RoomNumberAnnotator.java in the uimaj-examples project, under the src directory.

package org.apache.uima.tutorial.ex1;

import java.util.regex.Matcher;
import java.util.regex.Pattern;

import org.apache.uima.analysis_component.JCasAnnotator_ImplBase;
import org.apache.uima.jcas.JCas;
import org.apache.uima.tutorial.RoomNumber;

/**
 * Example annotator that detects room numbers using 
 * Java 1.4 regular expressions.
 */
public class RoomNumberAnnotator extends JCasAnnotator_ImplBase {
  private Pattern mYorktownPattern = 
        Pattern.compile("\\b[0-4]\\d-[0-2]\\d\\d\\b");

  private Pattern mHawthornePattern = 
        Pattern.compile("\\b[G1-4][NS]-[A-Z]\\d\\d\\b");

  public void process(JCas aJCas) {
    // Discussed Later
  }
}

The two Java class fields, mYorktownPattern and mHawthornePattern, hold regular expressions that will be used in the process method. Note that these two fields are part of the Java implementation of the annotator code, and not a part of the CAS type system. We are using the regular expression facility that is built into Java 1.4. It is not critical that you know the details of how this works, but if you are curious the details can be found in the Java API docs for the java.util.regex package.

The only method that we are required to implement is process. This method is typically called once for each document that is being analyzed. This method takes one argument, which is a JCas instance; this holds the document to be analyzed and all of the analysis results. ^[3]

public void process(JCas aJCas) {
  // get document text
  String docText = aJCas.getDocumentText();
  // search for Yorktown room numbers
  Matcher matcher = mYorktownPattern.matcher(docText);
  int pos = 0;
  while (matcher.find(pos)) {
    // found one - create annotation
    RoomNumber annotation = new RoomNumber(aJCas);
    annotation.setBegin(matcher.start());
    annotation.setEnd(matcher.end());
    annotation.setBuilding("Yorktown");
    annotation.addToIndexes();
    pos = matcher.end();
  }
  // search for Hawthorne room numbers
  matcher = mHawthornePattern.matcher(docText);
  pos = 0;
  while (matcher.find(pos)) {
    // found one - create annotation
    RoomNumber annotation = new RoomNumber(aJCas);
    annotation.setBegin(matcher.start());
    annotation.setEnd(matcher.end());
    annotation.setBuilding("Hawthorne");
    annotation.addToIndexes();
    pos = matcher.end();
  }
}

The Matcher class is part of the java.util.regex package and is used to find the room numbers in the document text. When we find one, recording the annotation is as simple as creating a new Java object and calling some set methods:

RoomNumber annotation = new RoomNumber(aJCas);
annotation.setBegin(matcher.start());
annotation.setEnd(matcher.end());
annotation.setBuilding("Yorktown");

The RoomNumber class was generated from the type system description by the Component Descriptor Editor or the JCasGen tool, as discussed in the previous section.

Finally, we call annotation.addToIndexes() to add the new annotation to the indexes maintained in the CAS. By default, the CAS implementation used for analysis of text documents keeps an index of all annotations in their order from beginning to end of the document. Subsequent annotators or applications use the indexes to iterate over the annotations.

We're almost ready to test the RoomNumberAnnotator. There is just one more step remaining.

The UIMA architecture requires that descriptive information about an annotator be represented in an XML file and provided along with the annotator class file(s) to the UIMA framework at run time. This XML file is called an Analysis Engine Descriptor. The descriptor includes:

The Component Descriptor Editor plugin, which we previously used to edit the Type System descriptor, can also be used to edit Analysis Engine Descriptors.

A descriptor for our RoomNumberAnnotator is provided with the UIMA distribution under the name descriptors/tutorial/ex1/RoomNumberAnnotator.xml. To edit it in Eclipse, right-click on that file in the navigator and select Open With → Component Descriptor Editor.

If you are not using Eclipse, you will need to edit Analysis Engine descriptors manually. See Section 1.8, “Analysis Engine XML Descriptor” for an introduction to the Analysis Engine descriptor XML syntax. The remainder of this section assumes you are using the Component Descriptor Editor plug-in to edit the Analysis Engine descriptor.

The Component Descriptor Editor consists of several tabbed pages; we will only need to use a few of them here. For more information on using this editor, see Chapter 1, Component Descriptor Editor User's Guide.

The initial page of the Component Descriptor Editor is the Overview page, which appears as follows:

This presents an overview of the RoomNumberAnnotator Analysis Engine (AE). The left side of the page shows that this descriptor is for a Primitive AE (meaning it consists of a single annotator), and that the annotator code is developed in Java. Also, it specifies the Java class that implements our logic (the code which was discussed in the previous section). Finally, on the right side of the page are listed some descriptive attributes of our annotator.

The other two pages that need to be filled out are the Type System page and the Capabilities page. You can switch to these pages using the tabs at the bottom of the Component Descriptor Editor. In the tutorial, these are already filled out for you.

The RoomNumberAnnotator will be using the TutorialTypeSystem we looked at in Section Section 1.1.1, “Defining Types”. To specify this, we add this type system to the Analysis Engine's list of Imported Type Systems, using the Type System page's right side panel, as shown here:

On the Capabilities page, we define our annotator's inputs and outputs, in terms of the types in the type system. The Capabilities page is shown below:

Although capabilities come in sets, having multiple sets is deprecated; here we're just using one set. The RoomNumberAnnotator is very simple. It requires no input types, as it operates directly on the document text -- which is supplied as a part of the CAS initialization (and which is always assumed to be present). It produces only one output type (RoomNumber), and it sets the value of the building feature on that type. This is all represented on the Capabilities page.

The Capabilities page has two other parts for specifying languages and Sofas. The languages section allows you to specify which languages your Analysis Engine supports. The RoomNumberAnnotator happens to be language-independent, so we can leave this blank. The Sofas section allows you to specify the names of additional subjects of analysis. This capability and the Sofa Mappings at the bottom are advanced topics, described in Chapter 5, Annotations, Artifacts, and Sofas.

This is all of the information we need to provide for a simple annotator. If you want to peek at the XML that this tool saves you from having to write, click on the “Source” tab at the bottom to view the generated XML.

Having developed an annotator, we need a way to try it out on some example documents. The UIMA SDK includes a tool called the Document Analyzer that will allow us to do this. To run the Document Analyzer, execute the documentAnalyzer shell script that is in the bin directory of your UIMA SDK installation, or, if you are using the example Eclipse project, execute the “UIMA Document Analyzer” run configuration supplied with that project. (To do this, click on the menu bar Run → Run ... → and under Java Applications in the left box, click on UIMA Document Analyzer.)

You should see a screen that looks like this:

There are six options on this screen:

Use the Browse button next to the third item to set the “Location of AE XML Descriptor” field to the descriptor we've just been discussing — <where-you-installed-uima-e.g.UIMA_HOME> /examples/descriptors/tutorial/ex1/RoomNumberAnnotator.xml . Set the other fields to the values shown in the screen shot above (which should be the default values if this is the first time you've run the Document Analyzer). Then click the “Run” button to start processing.

When processing completes, an “Analysis Results” window should appear.

Make sure “Java Viewer” is selected as the Results Display Format, and double-click on the document UIMASummerSchool2003.txt to view the annotations that were discovered. The view should look something like this:

You can click the mouse on one of the highlighted annotations to see a list of all its features in the frame on the right.

You can use the DocumentAnalyzer to test any UIMA annotator — just make sure that the annotator's classes are in the class path.

The example RoomNumberAnnotator from the previous section used hardcoded regular expressions and location names, which is obviously not very flexible. For example, you might want to have the patterns of room numbers be supplied by a configuration parameter, rather than having to redo the annotator's Java code to add additional patterns. Rather than add a new hardcoded regular expression for a new pattern, a better solution is to use configuration parameters.

UIMA allows annotators to declare configuration parameters in their descriptors. The descriptor also specifies default values for the parameters, though these can be overridden at runtime.

1.2.1.1. Declaring Parameters in the Descriptor

The example descriptor descriptors/tutorial/ex2/RoomNumberAnnotator.xml is the same as the descriptor from the previous section except that information has been filled in for the Parameters and Parameter Settings pages of the Component Descriptor Editor.

First, in Eclipse, open example two's RoomNumberAnnotator in the Component Descriptor Editor, and then go to the Parameters page (click on the parameters tab at the bottom of the window), which is shown below:

Two parameters – Patterns and Locations -- have been declared. In this screen shot, the mouse (not shown) is hovering over Patterns to show its description in the small popup window. Every parameter has the following information associated with it:

• name – the name by which the annotator code refers to the parameter

• description – a natural language description of the intent of the parameter

• type – the data type of the parameter's value – must be one of String, Integer, Float, or Boolean.

• multiValued – true if the parameter can take multiple-values (an array), false if the parameter takes only a single value. Shown above as Multi.

• mandatory – true if a value must be provided for the parameter. Shown above as Req (for required).

Both of our parameters are mandatory and accept an array of Strings as their value.

Next, default values are assigned to the parameters on the Parameter Settings page:

Here the “Patterns” parameter is selected, and the right pane shows the list of values for this parameter, in this case the regular expressions that match particular room numbering conventions. Notice the third pattern is new, for matching the style of room numbers in the third building, which has room numbers such as J2-A11.

/**
* @see AnalysisComponent#initialize(UimaContext)
*/
public void initialize(UimaContext aContext) 
        throws ResourceInitializationException {
  super.initialize(aContext);
  
  // Get config. parameter values  
  String[] patternStrings = 
        (String[]) aContext.getConfigParameterValue("Patterns");
  mLocations = 
        (String[]) aContext.getConfigParameterValue("Locations");

  // compile regular expressions
  mPatterns = new Pattern[patternStrings.length];
  for (int i = 0; i < patternStrings.length; i++) {
    mPatterns[i] = Pattern.compile(patternStrings[i]);
  }
}

The UIMA SDK provides a logging facility, which is very similar to the java.util.logging.Logger class that was introduced in Java 1.4.

In the Java architecture, each logger instance is associated with a name. By convention, this name is often the fully qualified class name of the component issuing the logging call. The name can be referenced in a configuration file when specifying which kinds of log messages to actually log, and where they should go.

The UIMA framework supports this convention using the UimaContext object. If you access a logger instance using getContext().getLogger() within an Annotator, the logger name will be the fully qualified name of the Annotator implementation class.

Here is an example from the process method of org.apache.uima.tutorial.ex2.RoomNumberAnnotator:

getContext().getLogger().log(Level.FINEST,"Found: " + annotation);

The first argument to the log method is the level of the log output. Here, a value of FINEST indicates that this is a highly-detailed tracing message. While useful for debugging, it is likely that real applications will not output log messages at this level, in order to improve their performance. Other defined levels, from lowest to highest importance, are FINER, FINE, CONFIG, INFO, WARNING, and SEVERE.

If no logging configuration file is provided (see next section), the Java Virtual Machine defaults would be used, which typically set the level to INFO and higher messages, and direct output to the console.

If you specify the standard UIMA SDK Logger.properties, the output will be directed to a file named uima.log, in the current working directory (often the “project” directory when running from Eclipse, for instance).

java "-Djava.util.logging.config.file=C:/Program Files/apache-uima/config/Logger.properties"

set UIMA_LOGGER_CONFIG_FILE=C:/myapp/MyLogger.properties

Logger logger = UIMAFramework.getLogger(TestClass.class);

-Dorg.apache.uima.logger.class=<loggerClass>

-Dorg.apache.uima.logger.class=<org.apache.uima.util.impl.Log4jLogger_impl>

The UIMA SDK makes it very easy to combine any sequence of Analysis Engines to form an Aggregate Analysis Engine. This is done through an XML descriptor; no Java code is required!

If you go to the examples/descriptors/tutorial/ex3 folder (in Eclipse, it's in your uimaj-examples project, under the descriptors/tutorial/ex3 folder), you will find a descriptor for a TutorialDateTime annotator. This annotator detects dates and times. To see what this annotator can do, try it out using the Document Analyzer. If you are curious as to how this annotator works, the source code is included, but it is not necessary to understand the code at this time.

We are going to combine the TutorialDateTime annotator with the RoomNumberAnnotator to create an aggregate Analysis Engine. This is illustrated in the following figure:

Figure 1.1. Combining Annotators to form an Aggregate Analysis Engine

The descriptor that does this is named RoomNumberAndDateTime.xml, which you can open in the Component Descriptor Editor plug-in. This is in the uimaj-examples project in the folder descriptors/tutorial/ex3.

The “Aggregate” page of the Component Descriptor Editor is used to define which components make up the aggregate. A screen shot is shown below. (If you are not using Eclipse, see Section 1.8, “Analysis Engine XML Descriptor” for the actual XML syntax for Aggregate Analysis Engine Descriptors.)

On the left side of the screen is the list of component engines that make up the aggregate – in this case, the TutorialDateTime annotator and the RoomNumberAnnotator. To add a component, you can click the “Add” button and browse to its descriptor. You can also click the “Find AE” button and search for an Analysis Engine in your Eclipse workspace.

The order of the components in the left pane does not imply an order of execution. The order of execution, or “flow” is determined in the “Component Engine Flow” section on the right. UIMA supports different types of algorithms (including user-definable) for determining the flow. Here we pick the simplest: FixedFlow. We have chosen to have the RoomNumberAnnotator execute first, although in this case it doesn't really matter, since the RoomNumber and DateTime annotators do not have any dependencies on one another.

If you look at the “Type System” page of the Component Descriptor Editor, you will see that it displays the type system but is not editable. The Type System of an Aggregate Analysis Engine is automatically computed by merging the Type Systems of all of its components.

The Capabilities page is where you explicitly declare the aggregate Analysis Engine's inputs and outputs. Sofas and Languages are described later.

Note that it is not automatically assumed that all outputs of each component Analysis Engine (AE) are passed through as outputs of the aggregate AE. If, for example, the TutorialDateTime annotator also produced Word and Sentence annotations, but those were not of interest as output in this case, we can exclude them from the list of outputs.

You can run this AE using the Document Analyzer in the same way that you run any other AE. Just select the examples/descriptors/tutorial/ex3/ RoomNumberAndDateTime.xml descriptor and click the Run button. You should see that RoomNumbers, Dates, and Times are all shown:

In addition to aggregating Analysis Engines, Aggregates can also contain CAS Consumers (see Chapter 2, Collection Processing Engine Developer's Guide, or even a mixture of these components with regular Analysis Engines. The UIMA Examples has an example of an Aggregate which contains both an analysis engine and a CAS consumer, in examples/descriptors/MixedAggregate.xml.

Analysis Engines support the collectionProcessComplete method, which is particularly important for many CAS Consumers. If an application (or a Collection Processing Engine) calls collectionProcessComplete no an aggregate, the framework will deliver that call to all of the components of the aggregate. If you use one of the built-in flow types (fixedFlow or capabilityLanguageFlow), then the order specified in that flow will be the same order in which the collectionProcessComplete calls are made to the components. If a custom flow is used, then the calls will be made in arbitrary order.

So far, we have been looking at annotators that look directly at the document text. However, annotators can also use the results of other annotators. One useful thing we can do at this point is look for the co-occurrence of a Date, a RoomNumber, and two Times – and annotate that as a Meeting.

The CAS maintains indexes of annotations, and from an index you can obtain an iterator that allows you to step through all annotations of a particular type. Here's some example code that would iterate over all of the TimeAnnot annotations in the JCas:

FSIndex timeIndex = aJCas.getAnnotationIndex(TimeAnnot.type);
Iterator timeIter = timeIndex.iterator();   
while (timeIter.hasNext()) {
  TimeAnnot time = (TimeAnnot)timeIter.next();

  //do something
}

Now that we've explained the basics, let's take a look at the process method for org.apache.uima.tutorial.ex4.MeetingAnnotator. Since we're looking for a combination of a RoomNumber, a Date, and two Times, there are four nested iterators. (There's surely a better algorithm for doing this, but to keep things simple we're just going to look at every combination of the four items.)

For each combination of the four annotations, we compute the span of text that includes all of them, and then we check to see if that span is smaller than a “window” size, a configuration parameter. There are also some checks to make sure that we don't annotate the same span of text multiple times. If all the checks pass, we create a Meeting annotation over the whole span. There's really nothing to it!

The XML descriptor, located in examples/descriptors/tutorial/ex4/MeetingAnnotator.xml , is also very straightforward. An important difference from previous descriptors is that this is the first annotator we've discussed that has input requirements. This can be seen on the “Capabilities” page of the Component Descriptor Editor:

If we were to run the MeetingAnnotator on its own, it wouldn't detect anything because it wouldn't have any input annotations to work with. The required input annotations can be produced by the RoomNumber and DateTime annotators. So, we create an aggregate Analysis Engine containing these two annotators, followed by the Meeting annotator. This aggregate is illustrated in Figure 1.2, “An Aggregate Analysis Engine where an internal component uses output from previous engines”. The descriptor for this is in examples/descriptors/tutorial/ex4/MeetingDetectorAE.xml . Give it a try in the Document Analyzer.

Figure 1.2. An Aggregate Analysis Engine where an internal component uses output from previous engines

The UIMA framework ensures that an Annotator instance is called by only one thread at a time. An instance never has to worry about running some method on one thread, and then asynchronously being called using another thread. This approach simplifies the design of annotators – they do not have to be designed to support multi-threading. When multiple threading is wanted, for performance, multiple instances of the Annotator are created, each one running on just one thread.

The following table defines the methods called by the framework, when they are called, and the requirements annotator implementations must follow.

There are two broad classes of errors that can occur: recoverable and unrecoverable. Because Annotators are often expected to process very large numbers of artifacts (for example, text documents), they should be written to recover where possible.

For example, if an upstream annotator created some input for an annotator which is invalid, the annotator may want to log this event, ignore the bad input and continue. It may include a notification of this event in the CAS, for further downstream annotators to consider. Or, it may throw an exception (see next section) – but in this case, it cannot do any further processing on that document.

Let's say an invalid regular expression was passed as a parameter to the RoomNumberAnnotator. Because this is an error related to the overall configuration, and not something we could expect to ignore, we should throw an appropriate exception, and most Java programmers would expect to do so like this:

throw new ResourceInitializationException(
    "The regular expression " + x + " is not valid.");

UIMA, however, does not do it this way. All UIMA exceptions are internationalized, meaning that they support translation into other languages. This is accomplished by eliminating hardcoded message strings and instead using external message digests. Message digests are files containing (key, value) pairs. The key is used in the Java code instead of the actual message string. This allows the message string to be easily translated later by modifying the message digest file, not the Java code. Also, message strings in the digest can contain parameters that are filled in when the exception is thrown. The format of the message digest file is described in the Javadocs for the Java class java.util.PropertyResourceBundle and in the load method of java.util.Properties.

The first thing an annotator developer must choose is what Exception class to use. There are three to choose from:

Generally you will not need to define your own custom exception classes, but if you do they must extend one of these three classes, which are the only types of Exceptions that the annotator interface permits annotators to throw.

All of the UIMA Exception classes share common constructor varieties. There are four possible arguments:

The name of the message digest to use (optional – if not specified the default UIMA message digest is used).

The key string used to select the message in the message digest.

An object array containing the parameters to include in the message. Messages can have substitutable parts. When the message is given, the string representation of the objects passed are substituted into the message. The object array is often created using the syntax new Object[]{x, y}.

Another exception which is the “cause” of the exception you are throwing. This feature is commonly used when you catch another exception and rethrow it. (optional)

If you look at source file (folder: src in Eclipse) org.apache.uima.tutorial.ex5.RoomNumberAnnotator, you will see the following code:

try {
  mPatterns[i] = Pattern.compile(patternStrings[i]);
} 
catch (PatternSyntaxException e) {
  throw new ResourceInitializationException(
     MESSAGE_DIGEST, "regex_syntax_error",
     new Object[]{patternStrings[i]}, e);
}

where the MESSAGE_DIGEST constant has the value "org.apache.uima.tutorial.ex5.RoomNumberAnnotator_Messages".

Message digests are specified using a dotted name, just like Java classes. This file, with the .properties extension, must be present in the class path. In Eclipse, you find this file under the src folder, in the package org.apache.uima.tutorial.ex5, with the name RoomNumberAnnotator_Messages.properties. Outside of Eclipse, you can find this in the uimaj-examples.jar with the name org/apache/uima/tutorial/ex5/RoomNumberAnnotator_Messages.properties. If you look in this file you will see the line:

regex_syntax_error = {0} is not a valid regular expression.

which is the error message for the example exception we showed above. The placeholder {0} will be filled by the toString() value of the argument passed to the exception constructor – in this case, the regular expression pattern that didn't compile. If there were additional arguments, their locations in the message would be indicated as {1}, {2}, and so on.

If a message digest is not specified in the call to the exception constructor, the default is UIMAException.STANDARD_MESSAGE_CATALOG (whose value is “org.apache.uima.UIMAException_Messages ” in the current release but may change). This message digest is located in the uima-core.jar file at org/apache/uima/UIMAException_messages.properties – you can take a look to see if any of these exception messages are useful to use.

To try out the regex_syntax_error exception, just use the Document Analyzer to run examples/descriptors/tutorial/ex5/RoomNumberAnnotator.xml , which happens to have an invalid regular expression in its configuration parameter settings.

To summarize, here are the steps to take if you want to define your own exception message:

Create a file with the .properties extension, where you declare message keys and their associated messages, using the same syntax as shown above for the regex_syntax_error exception. The properties file syntax is more completely described in the Javadocs for the load method of the java.util.Properties class.

Put your properties file somewhere in your class path (it can be in your annotator's .jar file).

Define a String constant (called MESSAGE_DIGEST for example) in your annotator code whose value is the dotted name of this properties file. For example, if your properties file is inside your jar file at the location org/myorg/myannotator/Messages.properties, then this String constant should have the value org.myorg.myannotator.Messages. Do not include the .properties extension. In Java Internationalization terminology, this is called the Resource Bundle name. For more information see the Javadocs for the PropertyResourceBundle class.

In your annotator code, throw an exception like this:

throw new ResourceInitializationException(
    MESSAGE_DIGEST, "your_message_name",
    new Object[]{param1,param2,...});

You may also wish to look at the Javadocs for the UIMAException class.

For more information on Java's internationalization features, see the Java Internationalization Guide.

External Resources are Java objects that have a life cycle where they are (optionally) initialized at startup time by reading external data from a file or via a URL (which can access information over the http protocol, for instance). It is not required that Extermal Resource objects do any external data reading to initialize themselves. However, this is such a common use case, that we will presume this mode of operation in the description below.

Sometimes you may want an annotator to read from an external resource, such as a URL or a file – for example, a long list of keys and values that you are going to build into a HashMap. You could, of course, just introduce a configuration parameter that holds the absolute path or URL to this resource, and build the HashMap in your annotator's initialize method. However, this is not the best solution for three reasons:

A better way to create these sharable Java objects and initialize them via external disk or URL sources is through the ResourceManager component. In this section we are going to show an example of how to use the Resource Manager.

This example annotator will annotate UIMA acronyms (e.g. UIMA, AE, CAS, JCas) and store the acronym's expanded form as a feature of the annotation. The acronyms and their expanded forms are stored in an external file.

First, look at the examples/descriptors/tutorial/ex6/UimaAcronymAnnotator.xml descriptor.

The values of the rows in the two tables are longer than can be easily shown. You can click the small button at the top right to shift the layout from two side-by-side tables, to a vertically stacked layout. You can also click the small twisty on the “Imports for External Resources and Bindings” to collapse this section, because it's not used here. Then the same screen will appear like this:

The top window has a scroll bar allowing you to see the rest of the line.

<externalResourceDependency>
  <key>AcronymTable</key> 
  <description>Table of acronyms and their expanded forms.</description> 
  <interfaceName>
    org.apache.uima.tutorial.ex6.StringMapResource
  </interfaceName> 
</externalResourceDependency>

StringMapResource mMap = 
  (StringMapResource)getContext().getResourceObject("AcronymTable");

InputStream stream = getContext().getResourceAsStream("AcronymTable");

URI uri = getContext().getResourceURI("AcronymTable");

1.5.4.3. Declaring Resources and Bindings

Refer back to the top window in the Resources page of the Component Descriptor Editor. This is where we specify the location of the resource data, and the Java class used to read the data. For the example, this corresponds to the following section of the descriptor:

<resourceManagerConfiguration>
  <externalResources>
    <externalResource>
      <name>UimaAcronymTableFile</name> 
      <description>
         A table containing UIMA acronyms and their expanded forms.
      </description> 
      <fileResourceSpecifier>
        <fileUrl>file:org/apache/uima/tutorial/ex6/uimaAcronyms.txt
        </fileUrl> 
      </fileResourceSpecifier>
      <implementationName>
         org.apache.uima.tutorial.ex6.StringMapResource_impl
      </implementationName> 
    </externalResource>
  </externalResources>

  <externalResourceBindings>
    <externalResourceBinding>
      <key>AcronymTable</key>    
      <resourceName>UimaAcronymTableFile</resourceName> 
    </externalResourceBinding>
  </externalResourceBindings>
</resourceManagerConfiguration>

The first section of this XML declares an externalResource, the UimaAcronymTableFile. With this, the fileUrl element specifies the path to the data file. This can be a file on the file system, but can also be a remote resource access via, e.g., the http protocol. The fileUrl element doesn't have to be a "file", it can be a URL. This can be an absolute URL (e.g. one that starts with file:/ or file:///, or file://my.host.org/), but that is not recommended because it makes installation of your component more difficult, as noted earlier. Better is a relative URL, which will be looked up within the classpath (and/or datapath), as used in this example. In this case, the file org/apache/uima/tutorial/ex6/uimaAcronyms.txt is located in uimaj-examples.jar, which is in the classpath. If you look in this file you will see the definitions of several UIMA acronyms.

The second section of the XML declares an externalResourceBinding, which connects the key AcronymTable, declared in the annotator's external resource dependency, to the actual resource name UimaAcronymTableFile. This is rather trivial in this case; for more on bindings see the example UimaMeetingDetectorAE.xml below. There is no global repository for external resources; it is up to the user to define each resource needed by a particular set of annotators.

In the Component Descriptor Editor, bindings are indicated below the external resource. To create a new binding, you select an external resource (which must have previously been defined), and an external resource dependency, and then click the Bind button, which only enables if you have selected two things to bind together.

When the Analysis Engine is initialized, it creates a single instance of StringMapResource_impl and loads it with the contents of the data file. This means that the framework calls the instance's load method, passing it an instance of DataResource, from which you can obtain a stream or URI/URL of the external resource that was declared in the external resource; for resources where loading does not make sense, you can implement a load method which ignores its argument and just returns, or performes whatever initialization is appropriate at startup time. See the Javadocs for SharedResourceObject for details on this.

The UimaAcronymAnnotator then accesses the data through the StringMapResource interface. This single instance could be shared among multiple annotators, as will be explained later.

Warning

Because the implementation of the resource is shared, you should insure your implementation is thread-safe, as it could be called multiple times on multiple threads, simultaneously.

Note that all resource implementation classes (e.g. StringMapResource_impl in the provided example) must be declared public must not be declared abstract, and must have public, 0-argument constructors, so that they can be instantiated by the framework. (Although Java classes in which you do not define any constructor will, by default, have a 0-argument constructor that doesn't do anything, a class in which you have defined at least one constructor does not get a default 0-argument constructor.)

All resource implementation classes that provide access to resource data must also implement the interface org.apache.uima.resource.SharedResourceObject. The UIMA Framework will invoke this interface's only method, load, after this object has been instantiated. The implementation of this method can then read data from the specified DataResource and use that data to initialize this object. It can also do whatever resource initialization might be appropriate to do at startup time.

This annotator is illustrated in Figure 1.3, “External Resource Binding”. To see it in action, just run it using the Document Analyzer. When it finishes, open up the UIMA_Seminars document in the processed results window, (double-click it), and then left-click on one of the highlighted terms, to see the expandedForm feature's value.

Figure 1.3. External Resource Binding

By designing our annotator in this way, we have gained some flexibility. We can freely replace the StringMapResource_impl class with any other implementation that implements the simple StringMapResource interface. (For example, for very large resources we might not be able to have the entire map in memory.) We have also made our external resource dependencies explicit in the descriptor, which will help others to deploy our annotator.

1.5.4.4. Sharing Resources among Annotators

Another advantage of the Resource Manager is that it allows our data to be shared between annotators. To demonstrate this we have developed another annotator that will use the same acronym table. The UimaMeetingAnnotator will iterate over Meeting annotations discovered by the Meeting Detector we previously developed and attempt to determine whether the topic of the meeting is related to UIMA. It will do this by looking for occurrences of UIMA acronyms in close proximity to the meeting annotation. We could implement this by using the UimaAcronymAnnotator, of course, but for the sake of this example we will have the UimaMeetingAnnotator access the acronym map directly.

The Java code for the UimaMeetingAnnotator in example 6 creates a new type, UimaMeeting, if it finds a meeting within 50 characters of the UIMA acronym.

We combine three analysis engines, the UimaAcronymAnnotator to annotate UIMA acronyms, the MeetingDectector from example 4 to find meetings and finally the UimaMeetingAnnotator to annotate just meetings about UIMA. Together these are assembled to form the new aggregate analysis engine, UimaMeetingDectector. This aggregate and the sharing of a common resource are illustrated in Figure 1.4, “Component engines of an aggregate share a common resource”.

Figure 1.4. Component engines of an aggregate share a common resource

The important thing to notice is in the UimaMeetingDetectorAE.xml aggregate descriptor. It includes both the UimaMeetingAnnotator and the UimaAcronymAnnotator, and contains a single declaration of the UimaAcronymTableFile resource. (The actual example has the order of the first two annotators reversed versus the above picture, which is OK since they do not depend on one another).

It also binds the resources as follows:

<externalResourceBindings>
  <externalResourceBinding>
    <key>UimaAcronymAnnotator/AcronymTable</key> 
    <resourceName>UimaAcronymTableFile</resourceName> 
  </externalResourceBinding>

  <externalResourceBinding>
    <key>UimaMeetingAnnotator/UimaTermTable</key> 
    <resourceName>UimaAcronymTableFile</resourceName> 
  </externalResourceBinding>
</externalResourceBindings>

This binds the resource dependencies of both the UimaAcronymAnnotator (which uses the name AcronymTable) and UimaMeetingAnnotator (which uses UimaTermTable) to the single declared resource named UimaAcronymFile. Therefore they will share the same instance. Resource bindings in the aggregate descriptor override any resource declarations in individual annotator descriptors.

If we wanted to have the annotators use different acronym tables, we could easily do that. We would simply have to change the resourceName elements in the bindings so that they referred to two different resources. The Resource Manager gives us the flexibility to make this decision at deployment time, without changing any Java code.

Annotators often are written to do a lot of computation and produce a lot of different outputs. For example, a tokenizer can, in addition to identifying tokens, look them up in dictionaries, create lemma forms (dropping suffexes and prefixes), etc. Result Specifications provide a way to dynamically specify what results are desired for a particular CAS being processed.

It is up to the annotator writer to take advantage of the result specification; using it is optional. If it is used, the annotator writer checks if a particular output is wanted, by asking the result specification if it contains a specific Type and/or Feature. If it does, then the annotator produces that type/feature; if not, it skips the computations for producing that type/feature.

The Result Specification querying may include the language. A typical use case: The CAS contains a document written in some language, and some upstream Annotator has discovered what this language is. The Annotator extracts the previously discovered language specification from the CAS and then includes it when querying the Result Specification. The exact method of encoding language specifications in the CAS is left up to annotator developers; however, the framework provides a commonly used type for this - the org.apache.uima.tcas.DocumentAnnotation type.

The Result Specification is passed to the annotator instance by calling its setResultSpecificaiton method (this call is typically done by the framework, based on Capability specifications). When called, the default implementation saves the result specification in an instance variable of the Annotator instance, which can be accessed by the annotator using the protected getResultSpecification() method.

A Result Specification is a list of output types and / or type:feature names, catagorized by language(s), which are expected to be output from (produced by) the annotator. Annotators may use this to optimize their operations, when possible, for those cases where only particular outputs are wanted. The interface to the Result Specification object (see the Javadocs) allows querying both types and particular features of types.

The languages specifications used by Result Specifications are the same that are specifiable in Capability Specifications; examples include "en" for English, "en-uk" for British English, etc. There is also a language type, "x-unspecified", which is presumed if no language specification(s) are given.

If a query of the Result Specification doesn't include a language, it is treated as if the language "x-unspecified" was specified. Language matching is hierarchically defaulted, in one direction: if a query includes the language "en-uk", meaning that the document being processed is in that language, it will match Result Specifications whose languages "en-uk", "en", or "x-unspecified". In other words, if the Result Specifications say to produce output if the actual document's language is en-uk, or en, or x-unspecified, then having the actual document's language be en-uk would "match" any of these Result Specifications. However the reverse is not true: If the query asks about producing output if the actual document's language is "x-unspecified", then it would not match if the Result Specification said to produce output only if the actual document is en-uk or en; the Result Specification would need to say to produce output for "x-unspecified).

If the Result Specification indicates it wants output produced for "en-uk", but the annotator is given a language which is unknown, or one that is known, but isn't "en-uk", then the query (using the language of the document) will return false. This is true even if the language is "en". However, if the Result Specification indicates it wants output for "en", and the query is for a document whose language is "en-uk" then the query will return true.

Sometimes you can specify the Result Specification; othertimes, you cannot (for instance, inside a Collection Processing Engine, you cannot). When you cannot specify it, or choose not to specify it (for example, using the form of the process(...) call on an Analysis Engine that doesn't include the Result Specification), a “Default” Result Specification is used.

JCas provides Java classes that correspond to each CAS type in an application. These classes are generated by the JCasGen utility (which can be automatically invoked from the Component Descriptor Editor).

The Java source classes generated by the JCasGen utility are typically compiled and packaged into a JAR file. This JAR file must be present in the classpath of the UIMA application.

For more details on issues around setting up this class path, including deployment issues where class loaders are being used to isolate multiple UIMA applications inside a single running Java Virtual Machine, please see Section 5.6.6, “Class Loaders in UIMA” .

The SDK includes a /bin subdirectory containing shell scripts, for Windows (.bat files) and Unix (.sh files). Many of these scripts invoke sample Java programs which require a class path; they call a common shell script, setUimaClassPath to set up the UIMA required files and directories on the class path.

If you need to include files on the class path, the scripts will add anything you specify in the environment variables CLASSPATH or UIMA_CLASSPATH to the classpath. So, for example, if you are running the document analyzer, and wanted it to find a Java class file named (on Windows) c:\a\b\c\myProject\myJarFile.jar, you could first issue a set command to set the UIMA_CLASSPATH to this file, followed by the documentAnalyzer script:

set UIMA_CLASSPATH=c:\a\b\c\myProject\myJarFile.jar
documentAnalyzer

Other environment variables are used by the shell scripts, as follows:

<?xml version="1.0" encoding="UTF-8" ?> 
<!--  Descriptor for the example RoomNumberAnnotator. --> 
<analysisEngineDescription xmlns="http://uima.apache.org/resourceSpecifier">
  <frameworkImplementation>org.apache.uima.java</frameworkImplementation> 
  <primitive>true</primitive> 
  <annotatorImplementationName>
    org.apache.uima.tutorial.ex1.RoomNumberAnnotator
  </annotatorImplementationName>

The document begins with a standard XML header and a comment. The root element of the document is named <analysisEngineDescription>, and must specify the XML namespace http://uima.apache.org/resourceSpecifier.

The first subelement, <frameworkImplementation>, must contain the value org.apache.uima.java. The second subelement, <primitive>, contains the Boolean value true, indicating that this XML document describes a Primitive Analysis Engine. A Primitive Analysis Engine is comprised of a single annotator. It is also possible to construct XML descriptors for non-primitive or Aggregate Analysis Engines; this is covered later.

The next element, <annotatorImplementationName>, contains the fully-qualified class name of our annotator class. This is how the UIMA framework determines which annotator class to instantiate.

<analysisEngineMetaData>
  <name>Room Number Annotator</name> 
  <description>An example annotator that searches for room numbers in
     the IBM Watson research buildings.</description> 
  <version>1.0</version> 
  <vendor>The Apache Software Foundation</vendor></para>

Here are shown four simple metadata fields – name, description, version, and vendor. Providing values for these fields is optional, but recommended.

<typeSystemDescription>
  <imports>
    <import location="TutorialTypeSystem.xml"/>
  </imports>
</typeSystemDescription>

This section of the XML descriptor defines which types the annotator works with. The recommended way to do this is to import the type system definition from a separate file, as shown here. The location specified here should be a relative path, and it will be resolved relative to the location of the aggregate descriptor. It is also possible to define types directly in the Analysis Engine descriptor, but these types will not be easily shareable by others.

<capabilities>
  <capability>
    <inputs /> 
    <outputs>
      <type>org.apache.uima.tutorial.RoomNumber</type> 
      <feature>org.apache.uima.tutorial.RoomNumber:building</feature> 
    </outputs>
  </capability>
</capabilities>

The last section of the descriptor describes the Capabilities of the annotator – the Types/Features it consumes (input) and the Types/Features that it produces (output). These must be the names of types and features that exist in the ANALYSIS ENGINE descriptor's type system definition.

Our annotator outputs only one Type, RoomNumber and one feature, RoomNumber:building. The fully-qualified names (including namespace) are needed.

The building feature is listed separately here, but clearly specifying every feature for a complex type would be cumbersome. Therefore, a shortcut syntax exists. The <outputs> section above could be replaced with the equivalent section:

<outputs>
  <type allAnnotatorFeatures ="true">
     org.apache.uima.tutorial.RoomNumber
  </type> 
</outputs>

A CPE can be assembled by writing an XML CPE descriptor. Details on the CPE descriptor, including its syntax and content, can be found in Chapter 3, Collection Processing Engine Descriptor Reference. Rather than edit raw XML, you may develop a CPE Descriptor using the CPE Configurator tool. The CPE Configurator tool is described briefly in this section, and in more detail in Chapter 2, Collection Processing Engine Configurator User's Guide.

The CPE Configurator tool can be run from Eclipse (see Section 2.2.2, “Running the CPE Configurator from Eclipse”, or using the cpeGui shell script (cpeGui.bat on Windows, cpeGui.sh on Unix), which is located in the bin directory of the UIMA SDK installation. Executing this batch file will display the window shown here:

The window is divided into three sections, one each for the Collection Reader, Analysis Engines, and CAS Consumers.^[5] In each section, you select the component(s) you want to include in the CPE by browsing to their XML descriptors. The configuration parameters present in the XML descriptors will then be displayed in the GUI; these can be modified to override the values present in the descriptor. For example, the screen shot below shows the CPE Configurator after the following components have been chosen:

Collection Reader: 
   %UIMA_HOME%/examples/descriptors/collection_reader/
          FileSystemCollectionReader.xml

Analysis Engine: 
   %UIMA_HOME%/examples/descriptors/analysis_engine/
          NamesAndPersonTitles_TAE.xml

CAS Consumer: 
    %UIMA_HOME%/examples/descriptors/cas_consumer/
          XmiWriterCasConsumer.xml

For the File System Collection Reader, ensure that the Input Directory is set to %UIMA_HOME%\examples\data^[6]. The other parameters may be left blank. For the External CAS Writer CAS Consumer, ensure that the Output Directory is set to %UIMA_HOME%\examples\data\processed.

After selecting each of the components and providing configuration settings, click the play (forward arrow) button at the bottom of the screen to begin processing. A progress bar should be displayed in the lower left corner. (Note that the progress bar will not begin to move until all components have completed their initialization, which may take several seconds.) Once processing has begun, the pause and stop buttons become enabled.

If an error occurs, you will be informed by an error dialog. If processing completes successfully, you will be presented with a performance report.

Using the File menu, you can select Save CPE Descriptor to create an .xml descriptor file that defines the CPE you have constructed. Later, you can use Open CPE Descriptor to restore the CPE Configurator to the saved state. Also, CPE descriptors can be used to run a CPE from a Java program – see section Section 2.3, “Running a CPE from Your Own Java Application”. CPE Descriptors allow specifying operational parameters, such as error handling options, that are not currently available for configuration through the CPE Configurator. For more information on manually creating a CPE Descriptor, see the Chapter 3, Collection Processing Engine Descriptor Reference.

The CPE configured above runs a simple name and title annotator on the sample data provided with the UIMA SDK and stores the results using the XMI Writer CAS Consumer. To view the results, start the External CAS Annotation Viewer by running the annotationViewer batch file (annotationViewer.bat on Windows, annotationViewer.sh on Unix), which is located in the bin directory of the UIMA SDK installation. Executing this batch file will display the window shown here:

Ensure that the Input Directory is the same as the Output Directory specified for the XMI Writer CAS Consumer in the CPE configured above (e.g., %UIMA_HOME%\examples\data\processed) and that the TAE Descriptor File is set to the Analysis Engine used in the CPE configured above (e.g., examples\descriptors\analysis_engine\NamesAndPersonTitles_TAE.xml ).

Click the View button to display the Analyzed Documents window:

Double click on any document in the list to view the analyzed document. Double clicking the first document, IBM_LifeSciences.txt, will bring up the following window:

This window shows the analysis results for the document. Clicking on any highlighted annotation causes the details for that annotation to be displayed in the right-hand pane. Here the annotation spanning “John M. Thompson” has been clicked.

Congratulations! You have successfully configured a CPE, saved its descriptor, run the CPE, and viewed the analysis results.

If you have followed the instructions in Chapter 3, Setting up the Eclipse IDE to work with UIMA and imported the example Eclipse project, then you should already have a Run configuration for the CPE Configurator tool (called UIMA CPE GUI) configured to run in the example project. Simply run that configuration to start the CPE Configurator.

If you haven't followed the Eclipse setup instructions and wish to run the CPE Configurator tool from Eclipse, you will need to do the following. As installed, this Eclipse launch configuration is associated with the “uimaj-examples” project. If you've not already done so, you may wish to import that project into your Eclipse workspace. It's located in %UIMA_HOME%/docs/examples. Doing this will supply the Eclipse launcher with all the class files it needs to run the CPE configurator. If you don't do this, please manually add the JAR files for UIMA to the launch configuration.

Also, you need to add any projects or JAR files for any UIMA components you will be running to the launch class path.

Next, in the Eclipse menu select Run → Run..., which brings up the Run configuration screen.

In the Main tab, set the main class to org.apache.uima.tools.cpm.CpmFrame

In the arguments tab, add the following to the VM arguments:

-Xms128M -Xmx256M 
-Duima.home="C:\Program Files\Apache\uima"

(or wherever you installed the UIMA SDK)

Click the Run button to launch the CPE Configurator, and use it as previously described in this section.

Updates of the CPM's progress, including any errors that occur, are sent to the callback handler that is registered by the call to addStatusCallbackListener, above. The callback handler is a class that implements the CPM's StatusCallbackListener interface. It responds to events by printing messages to the console. The source code is fairly straightforward and is not included in this chapter – see the org.apache.uima.examples.cpe.SimpleRunCPE.java in the %UIMA_HOME%\examples\src directory for the complete code.

If you need more control over the information in the CPE descriptor, you can manually configure it via its API. See the Javadocs for package org.apache.uima.collection for more details.

A Collection Reader is responsible for obtaining documents from the collection and returning each document as a CAS. Like all UIMA components, a Collection Reader consists of two parts — the code and an XML descriptor.

A simple example of a Collection Reader is the “File System Collection Reader,” which simply reads documents from files in a specified directory. The Java code is in the class org.apache.uima.examples.cpe.FileSystemCollectionReader and the XML descriptor is %UIMA_HOME%/examples/src/main/descriptors/collection_reader/ FileSystemCollectionReader.xml.

2.4.1.1. Java Class for the Collection Reader

The Java class for a Collection Reader must implement the org.apache.uima.collection.CollectionReader interface. You may build your Collection Reader from scratch and implement this interface, or you may extend the convenience base class org.apache.uima.collection.CollectionReader_ImplBase .

The convenience base class provides default implementations for many of the methods defined in the CollectionReader interface, and provides abstract definitions for those methods that you are required to implement in your new Collection Reader. Note that if you extend this base class, you do not need to declare that your new Collection Reader implements the CollectionReader interface.

Tip

Eclipse tip – if you are using Eclipse, you can quickly create the boiler plate code and stubs for all of the required methods by clicking File → New → Class to bring up the “New Java Class” dialogue, specifying org.apache.uima.collection.CollectionReader_ImplBase as the Superclass, and checking “Inherited abstract methods” in the section “Which method stubs would you like to create?”, as in the screenshot below:

For the rest of this section we will assume that your new Collection Reader extends the CollectionReader_ImplBase class, and we will show examples from the org.apache.uima.examples.cpe.FileSystemCollectionReader . If you must inherit from a different superclass, you must ensure that your Collection Reader implements the CollectionReader interface – see the Javadocs for CollectionReader for more details.

public void initialize() throws ResourceInitializationException {
  File directory = new File(
            (String)getConfigParameterValue(PARAM_INPUTDIR));
  mEncoding = (String)getConfigParameterValue(PARAM_ENCODING);
  mDocumentTextXmlTagName = (String)getConfigParameterValue(PARAM_XMLTAG);
  mLanguage = (String)getConfigParameterValue(PARAM_LANGUAGE);
  mCurrentIndex = 0; 
  
  //get list of files (not subdirectories) in the specified directory
  mFiles = new ArrayList();
  File[] files = directory.listFiles();
  for (int i = 0; i < files.length; i++) {
    if (!files[i].isDirectory()) {
      mFiles.add(files[i]);  
    }
  }
}

public boolean hasNext() {
  return mCurrentIndex < mFiles.size();
}

  public void getNext(CAS aCAS) throws IOException, CollectionException {
    JCas jcas;
    try {
      jcas = aCAS.getJCas();
    } catch (CASException e) {
      throw new CollectionException(e);
    }

    // open input stream to file
    File file = (File) mFiles.get(mCurrentIndex++);
    BufferedInputStream fis = 
            new BufferedInputStream(new FileInputStream(file));
    try {
      byte[] contents = new byte[(int) file.length()];
      fis.read(contents);
      String text;
      if (mEncoding != null) {
        text = new String(contents, mEncoding);
      } else {
        text = new String(contents);
      }
      // put document in CAS
      jcas.setDocumentText(text);
    } finally {
      if (fis != null)
        fis.close();
    }

    // set language if it was explicitly specified 
    //as a configuration parameter
    if (mLanguage != null) {
      ((DocumentAnnotation) jcas.getDocumentAnnotationFs()).
            setLanguage(mLanguage);
    }

    // Also store location of source document in CAS. 
    // This information is critical if CAS Consumers will 
    // need to know where the original document contents 
    // are located.
    // For example, the Semantic Search CAS Indexer 
    // writes this information into the search index that 
    // it creates, which allows applications that use the 
    // search index to locate the documents that satisfy 
    //their semantic queries.
    SourceDocumentInformation srcDocInfo = 
            new SourceDocumentInformation(jcas);
    srcDocInfo.setUri(
            file.getAbsoluteFile().toURL().toString());
    srcDocInfo.setOffsetInSource(0);
    srcDocInfo.setDocumentSize((int) file.length());
    srcDocInfo.setLastSegment(
            mCurrentIndex == mFiles.size());
    srcDocInfo.addToIndexes();
  }

public Progress[] getProgress() {
  return new Progress[]{
     new ProgressImpl(mCurrentIndex,mFiles.size(),Progress.ENTITIES)};
}

public void close() throws IOException { }

<collectionReaderDescription 
          xmlns="http://uima.apache.org/resourceSpecifier">
  <frameworkImplementation>org.apache.uima.java</frameworkImplementation>
  <implementationName>
    org.apache.uima.examples.cpe.FileSystemCollectionReader
  </implementationName>
  <processingResourceMetaData>
    <name>File System Collection Reader</name>
    <description>Reads files from the filesystem.</description>
    <version>1.0</version>
    <vendor>The Apache Software Foundation</vendor>
    <configurationParameters>
      <configurationParameter>
        <name>InputDirectory</name>
        <description>Directory containing input files</description>
        <type>String</type>
        <multiValued>false</multiValued>
        <mandatory>true</mandatory>
      </configurationParameter>
      <configurationParameter>
        <name>Encoding</name>
        <description>Character encoding for the documents.</description>
        <type>String</type>
        <multiValued>false</multiValued>
        <mandatory>false</mandatory>
      </configurationParameter>
      <configurationParameter>
        <name>Language</name>
        <description>ISO language code for the documents</description>
        <type>String</type>
        <multiValued>false</multiValued>
        <mandatory>false</mandatory>
      </configurationParameter>
    </configurationParameters>
    <configurationParameterSettings>
      <nameValuePair>
        <name>InputDirectory</name>
        <value>
          <string>C:/Program Files/apache/uima/examples/data</string>
        </value>
      </nameValuePair>
    </configurationParameterSettings>
    
    <!-- Type System of CASes returned by this Collection Reader -->
    
    <typeSystemDescription>
      <imports>
        <import name="org.apache.uima.examples.SourceDocumentInformation"/>
      </imports>
    </typeSystemDescription>
    
    <capabilities>
      <capability>
        <inputs/>
        <outputs>
          <type allAnnotatorFeatures="true">
            org.apache.uima.examples.SourceDocumentInformation
          </type>
        </outputs>
      </capability>
    </capabilities>
    <operationalProperties>
      <modifiesCas>true</modifiesCas>
      <multipleDeploymentAllowed>false</multipleDeploymentAllowed>
      <outputsNewCASes>true</outputsNewCASes>
    </operationalProperties>
  </processingResourceMetaData>
</collectionReaderDescription>

In UIMA 1.x, the CAS Initializer component was intended to be used as a plug-in to the Collection Reader for when the task of populating the CAS from a raw document is complex and might be reusable with other data collections.

A CAS Initializer Java class must implement the interface org.apache.uima.collection.CasInitializer, and will also generally extend from the convenience base class org.apache.uima.collection.CasInitializer_ImplBase. A CAS Initializer also must have an XML descriptor, which has the exact same form as a Collection Reader Descriptor except that the outer tag is <casInitializerDescription>.

CAS Initializers have optional initialize(), reconfigure(), and typeSystemInit() methods, which perform the same functions as they do for Collection Readers. The only required method for a CAS Initializer is initializeCas(Object, CAS). This method takes the raw document (for example, an InputStream object from which the document can be read) and a CAS, and populates the CAS from the document.

A CAS Consumer receives each CAS after it has been analyzed by the Analysis Engine. CAS Consumers typically do not update the CAS; they typically extract data from the CAS and persist selected information to aggregate data structures such as search engine indexes or databases.

A CAS Consumer Java class must implement the interface org.apache.uima.collection.CasConsumer, and will also generally extend from the convenience base class org.apache.uima.collection.CasConsumer_ImplBase. A CAS Consumer also must have an XML descriptor, which has the exact same form as a Collection Reader Descriptor except that the outer tag is <casConsumerDescription>.

CAS Consumers have optional initialize(), reconfigure(), and typeSystemInit() methods, which perform the same functions as they do for Collection Readers and CAS Initializers. The only required method for a CAS Consumer is processCas(CAS), which is where the CAS Consumer does the bulk of its work (i.e., consume the CAS).

The CasConsumer interface (as well as the version 2 Analysis Engine interfac) additionally defines batch and collection level processing methods. The CAS Consumer or Analysis Engine can implement the batchProcessComplete() method to perform processing that should occur at the end of each batch of CASes. Similarly, the CAS Consumer or Analysis Engine can implement the collectionProcessComplete() method to perform any collection level processing at the end of the collection.

A very simple example of a CAS Consumer, which writes an XML representation of the CAS to a file, is the XMI Writer CAS Consumer. The Java code is in the class org.apache.uima.examples.cpe.XmiWriterCasConsumer and the descriptor is in %UIMA_HOME%/examples/descriptors/cas_consumer/XmiWriterCasConsumer.xml .

public void initialize() throws ResourceInitializationException {
  mDocNum = 0;
  mOutputDir = new File((String) getConfigParameterValue(PARAM_OUTPUTDIR));
  if (!mOutputDir.exists()) {
    mOutputDir.mkdirs();
  }
}

public void processCas(CAS aCAS) throws ResourceProcessException {
  String modelFileName = null;

  JCas jcas;
  try {
    jcas = aCAS.getJCas();
  } catch (CASException e) {
    throw new ResourceProcessException(e);
  }
 
    // retreive the filename of the input file from the CAS
  FSIterator it = jcas
            .getAnnotationIndex(SourceDocumentInformation.type)
                  .iterator();
  File outFile = null;
  if (it.hasNext()) {
    SourceDocumentInformation fileLoc = 
            (SourceDocumentInformation) it.next();
    File inFile;
    try {
      inFile = new File(new URL(fileLoc.getUri()).getPath());
      String outFileName = inFile.getName();
      if (fileLoc.getOffsetInSource() > 0) {
        outFileName += ("_" + fileLoc.getOffsetInSource());
      }
      outFileName += ".xmi";
      outFile = new File(mOutputDir, outFileName);
      modelFileName = mOutputDir.getAbsolutePath() + 
            "/" + inFile.getName() + ".ecore";
    } catch (MalformedURLException e1) {
      // invalid URL, use default processing below
    }
  }
  if (outFile == null) {
    outFile = new File(mOutputDir, "doc" + mDocNum++);
  }
  // serialize XCAS and write to output file
  try {
    writeXmi(jcas.getCas(), outFile, modelFileName);
  } catch (IOException e) {
    throw new ResourceProcessException(e);
  } catch (SAXException e) {
    throw new ResourceProcessException(e);
  }
}

Managed CAS Processor deployment is shown in Figure 2.3, “CPE with Managed CAS Processors”. A managed CAS Processor is deployed by the CPE as a Vinci service. The CPE manages the lifecycle of the CAS Processor including service launch, restart on failures, and service shutdown. A managed CAS Processor runs on the same machine as the CPE, but in a separate process. This provides the necessary fault isolation for the CPE to protect it from non-robust CAS Processors. A fatal failure of a managed CAS Processor does not threaten the stability of the CPE.

Figure 2.3. CPE with Managed CAS Processors

The CPE communicates with managed CAS Processors using the Vinci communication protocol. A CAS Processor is launched as a Vinci service and its process() method is invoked remotely via a Vinci command. The CPE uses its own internal VNS to support managed CAS processors. The VNS, by default, listens on port 9005. If this port is not available, the VNS will increment its listen port until it finds one that is available. All managed CAS Processors are internally configured to “talk” to the CPE managed VNS. This internal VNS is transparent to the end user launching the CPE.

To deploy a managed CAS Processor, the CPE deployer must change the CPE descriptor. The following is a section from the CPE descriptor that shows an example configuration specifying a managed CAS Processor.

<casProcessor deployment="local" name="Meeting Detector TAE">
  <descriptor>
    <include href="deploy/vinci/Deploy_MeetingDetectorTAE.xml"/>
  </descriptor>
  <runInSeparateProcess>
    <exec dir="." executable="java">
      <env key="CLASSPATH" 
         value="src;
                C:/Program Files/apache/uima/lib/uima-core.jar;
                C:/Program Files/apache/uima/lib/uima-cpe.jar;
                C:/Program Files/apache/uima/lib/uima-examples.jar;
                C:/Program Files/apache/uima/lib/uima-adapter-vinci.jar;
                C:/Program Files/apache/uima/lib/jVinci.jar"/>
      <arg>-DLOG=C:/Temp/service.log</arg>
      <arg>org.apache.uima.reference_impl.collection.
         service.vinci.VinciAnalysisEnginerService_impl</arg>
      <arg>${descriptor}</arg>
    </exec>
  </runInSeparateProcess>
  <deploymentParameters/>
  <filter/>
  <errorHandling>
    <errorRateThreshold action="terminate" value="1/100"/>
    <maxConsecutiveRestarts action="terminate" value="3"/>
    <timeout max="100000"/>
  </errorHandling>
  <checkpoint batch="10000"/>
</casProcessor>

See Chapter 3, Collection Processing Engine Descriptor Reference for details and required settings.

Non-managed CAS Processor deployment is shown in Figure 2.4, “CPE with non-managed CAS Processors”. In non-managed mode, the CPE supports connectivity to CAS Processors running on local or remote computers using Vinci. Non-managed processors are different from managed processors in two aspects:

Figure 2.4. CPE with non-managed CAS Processors

While non-managed CAS Processors provide the same level of fault isolation and robustness as managed CAS Processors, error recovery support for non-managed CAS Processors is much more limited. In particular, the CPE cannot restart a non-managed CAS Processor after an error.

Non-managed CAS Processors also require a separate Vinci Naming Service running on the network. This VNS must be manually started and monitored by the end user or application. Instructions for running a VNS can be found in Section 3.6.5.1, “Starting VNS”.

To deploy a non-managed CAS Processor, the CPE deployer must change the CPE descriptor. The following is a section from the CPE descriptor that shows an example configuration for the non-managed CAS Processor.

<casProcessor deployment="remote" name="Meeting Detector TAE">
  <descriptor>
    <include href=
        "descriptors/vinciService/MeetingDetectorVinciService.xml"/>
  </descriptor>
  <deploymentParameters/>
  <filter/>
  <errorHandling>
    <errorRateThreshold action="terminate" value="1/100"/>
    <maxConsecutiveRestarts action="terminate" value="3"/>
    <timeout max="100000"/>
  </errorHandling>
  <checkpoint batch="10000"/>
</casProcessor>

See Chapter 3, Collection Processing Engine Descriptor Reference for details and required settings.

Integrated CAS Processors are shown in Figure 2.5, “CPE with integrated CAS Processor”. Here the CAS Processors run in the same JVM as the CPE, just like the Collection Reader and CAS Initializer. This deployment method results in minimal CAS communication and transport overhead as the CAS is shared in the same process space of the JVM. However, a CPE running with all integrated CAS Processors is limited in scalability by the capability of the single computer on which the CPE is running. There is also a stability risk associated with integrated processors because a poorly written CAS Processor can cause the JVM, and hence the entire CPE, to abort.

Figure 2.5. CPE with integrated CAS Processor

The following is a section from a CPE descriptor that shows an example configuration for the integrated CAS Processor.

<casProcessor deployment=“integrated” name=“Meeting Detector TAE”>
  <descriptor>
    <include href="descriptors/tutorial/ex4/MeetingDetectorTAE.xml"/>
  </descriptor>
  <deploymentParameters/>
  <filter/>
  <errorHandling>
    <errorRateThreshold action="terminate" value="100/1000"/>
    <maxConsecutiveRestarts action="terminate" value="30"/>
    <timeout max="100000"/>
  </errorHandling>
  <checkpoint batch="10000"/>
</casProcessor>

See Chapter 3, Collection Processing Engine Descriptor Reference for details and required settings.

The following code shows how to instantiate an AE from its XML descriptor:

  //get Resource Specifier from XML file
XMLInputSource in = new XMLInputSource("MyDescriptor.xml");
ResourceSpecifier specifier = 
    UIMAFramework.getXMLParser().parseResourceSpecifier(in);

  //create AE here
AnalysisEngine ae = 
    UIMAFramework.produceAnalysisEngine(specifier);

The first two lines parse the XML descriptor (for AEs with multiple descriptor files, one of them is the “main” descriptor - the AE documentation should indicate which it is). The result of the parse is a ResourceSpecifier object. The third line of code invokes a static factory method UIMAFramework.produceAnalysisEngine, which takes the specifier and instantiates an AnalysisEngine object.

There is one caveat to using this approach - the Analysis Engine instance that you create will not support multiple threads running through it concurrently. If you need to support this, see Section 3.2.5, “Multi-threaded Applications”.

There are two ways to use the AE interface to analyze documents. You can either use the JCas interface, which is described in detail by Chapter 5, JCas Reference or you can directly use the CAS interface, which is described in detail in Chapter 4, CAS Reference. Besides text documents, other kinds of artifacts can also be analyzed; see Chapter 5, Annotations, Artifacts, and Sofas for more information.

The basic structure of your application will look similar in both cases:

Using the JCas

  //create a JCas, given an Analysis Engine (ae)
JCas jcas = ae.newJCas();
  
  //analyze a document
jcas.setDocumentText(doc1text);
ae.process(jcas);
doSomethingWithResults(jcas);
jcas.reset();
  
  //analyze another document
jcas.setDocumentText(doc2text);
ae.process(jcas);
doSomethingWithResults(jcas);
jcas.reset();
...
  //done
ae.destroy();

Using the CAS

//create a CAS
CAS aCasView = ae.newCAS();

//analyze a document
aCasView.setDocumentText(doc1text);
ae.process(aCasView);
doSomethingWithResults(aCasView);
aCasView.reset();

//analyze another document
aCasView.setDocumentText(doc2text);
ae.process(aCasView);
doSomethingWithResults(aCasView);
aCasView.reset();
...
//done
ae.destroy();

First, you create the CAS or JCas that you will use. Then, you repeat the following four steps for each document:

Analyzing non-text artifacts is similar to analyzing text documents. The main difference is that instead of using the setDocumentText method, you need to use the Sofa APIs to set the artifact into the CAS. See Chapter 5, Annotations, Artifacts, and Sofas for details.

Annotators (and applications) access the results of analysis via the CAS, using the CAS or JCas interfaces. These results are accessed using the CAS Indexes. There is one built-in index for instances of the built-in type uima.tcas.Annotation that can be used to retrieve instances of Annotation or any subtype of Annotation. You can also define additional indexes over other types.

Indexes provide a method to obtain an iterators over their contents; the iterator returns the matching elements one at time from the CAS.

The simplest way to use an AE in a multi-threaded environment is to use the Java synchronized keyword to ensure that only one thread is using an AE at any given time. For example:

public class MyApplication {
  private AnalysisEngine mAnalysisEngine;
  private CAS mCAS;

  public MyApplication() {
    //get Resource Specifier from XML file
    XMLInputSource in = new XMLInputSource("MyDescriptor.xml");
    ResourceSpecifier specifier = 
        UIMAFramework.getXMLParser().parseResourceSpecifier(in);
 
    //create Analysis Engine here
    mAnalysisEngine = UIMAFramework.produceAnalysisEngine(specifier);
    mCAS = mAnalysisEngine.newCAS();
  }

  // Assume some other part of your multi-threaded application could
  // call “analyzeDocument” on different threads, asynchronusly

  public synchronized void analyzeDocument(String aDoc) {
    //analyze a document
    mCAS.setDocumentText(aDoc);
    mAnalysisEngine.process();  
    doSomethingWithResults(mCAS);
    mCAS.reset();
  }
  ...
}

Without the synchronized keyword, this application would not be thread-safe. If multiple threads called the analyzeDocument method simultaneously, they would both use the same CAS and clobber each others' results. The synchronized keyword ensures that no more than one thread is executing this method at any given time. For more information on thread synchronization in Java, see http://java.sun.com/docs/books/tutorial/essential/threads/multithreaded.html .

The synchronized keyword ensures thread-safety, but does not allow you to process more than one document at a time. If you need to process multiple documents simultaneously (for example, to make use of a multiprocessor machine), you'll need to use more than one CAS instance.

Because CAS instances use memory and can take some time to construct, you don't want to create a new CAS instance for each request. Instead, you should use a feature of the UIMA SDK called the CAS Pool, implemented by the type CasPool.

A CAS Pool contains some number of CAS instances (you specify how many when you create the pool). When a thread wants to use a CAS, it checks out an instance from the pool. When the thread is done using the CAS, it must release the CAS instance back into the pool. If all instances are checked out, additional threads will block and wait for an instance to become available. Here is some example code:

public class MyApplication {
  private CasPool mCasPool;
  
  private AnalysisEngine mAnalysisEngine;
  
  public MyApplication()
  {
    //get Resource Specifier from XML file
    XMLInputSource in = new XMLInputSource("MyDescriptor.xml");
    ResourceSpecifier specifier = 
      UIMAFramework.getXMLParser().parseResourceSpecifier(in);
 
    //Create multithreadable AE that will 
    //Accept 3 simultaneous requests
    //The 3rd parameter specifies a timeout.
    //When the number of simultaneous requests exceeds 3,
    // additional requests will wait for other requests to finish. 
    // This parameter determines the maximum number of milliseconds 
    // that a new request should wait before throwing an
    // - a value of 0 will cause them to wait forever.
    mAnalysisEngine = UIMAFramework.produceAnalysisEngine(specifier,3,0);

    //create CAS pool with 3 CAS instances
    mCasPool = new CasPool(3, mAnalysisEngine);
  }

  public void analyzeDocument(String aDoc) {
    //check out a CAS instance (argument 0 means no timeout)
    CAS cas = mCasPool.getCas(0);  
    try {
      //analyze a document 
      cas.setDocumentText(aDoc);   
      mAnalysisEngine.process(cas);  
      doSomethingWithResults(cas);
    } finally {
      //MAKE SURE we release the CAS instance
      mCasPool.releaseCas(cas);  
    }
  }
  ...
}

There is not much more code required here than in the previous example. First, there is one additional parameter to the AnalysisEngine producer, specifying the number of annotator instances to create^[7]. Then, instead of creating a single CAS in the constructor, we now create a CasPool containing 3 instances. In the analyze method, we check out a CAS, use it, and then release it.

The getCAS() method returns a CAS which is not specialized to any particular subject of analysis. To process things other than this, please refer to Chapter 5, Annotations, Artifacts, and Sofas .

Note the use of the try...finally block. This is very important, as it ensures that the CAS we have checked out will be released back into the pool, even if the analysis code throws an exception. You should always use try...finally when using the CAS pool; if you do not, you risk exhausting the pool and causing deadlock.

The parameter 0 passed to the CasPool.getCas() method is a timeout value. If this is set to a positive integer, it is the maximum number of milliseconds that the thread will wait for an instance to become available in the pool. If this time elapses, the getCas method will return null, and the application can do something intelligent, like ask the user to try again later. A value of 0 will cause the thread to wait for an available CAS, potentially forever.

In most cases, the easiest way to use multiple Analysis Engines from within an application is to combine them into an aggregate AE. For instructions, see Section 1.3, “Building Aggregate Analysis Engines”. Be sure that you understand this method before deciding to use the more advanced feature described in this section.

If you decide that your application does need to instantiate multiple AEs and have those AEs share a single CAS, then you will no longer be able to use the various methods on the AnalysisEngine class that create CASes (or JCases) to create your CAS. This is because these methods create a CAS with a data model specific to a single AE and which therefore cannot be shared by other AEs. Instead, you create a CAS as follows:

Suppose you have two analysis engines, and one CAS Consumer, and you want to create one type system from the merge of all of their type specifications. Then you can do the following:

AnalysisEngineDescription aeDesc1 =
  UIMAFramework.getXMLParser().parseAnalysisEngineDescription(...);
  
  AnalysisEngineDescription aeDesc2 =
  UIMAFramework.getXMLParser().parseAnalysisEngineDescription(...);

  CasConsumerDescription ccDesc =
  UIMAFramework.getXMLParser().parseCasConsumerDescription(...);

  List list = new ArrayList();

  list.add(aeDesc1);
  list.add(aeDesc2);
  list.add(ccDesc);

  CAS cas = CasCreationUtils.createCas(list);

  // (optional, if using the JCas interface) 
  JCas jcas = cas.getJCas();

The CasCreationUtils class takes care of the work of merging the AEs' type systems and producing a CAS for the combined type system. If the type systems are not compatible, an exception will be thrown.

The UIMA framework provides APIs to save and restore the contents of a CAS to streams. The CASes are stored in an XML format. There are two forms of this format. The preferred form is the XMI form (see Section 8.3, “Using XMI CAS Serialization”). An older format is also available, called XCAS.

To save an XMI representation of a CAS, use the serialize method of the class org.apache.uima.util.XmlCasSerializer. To save an XCAS representation of a CAS, use the class org.apache.uima.cas.impl.XCASSerializer instead; see the Javadocs for details.

Both of these external forms can be read back in, using the deserialize method of the class org.apache.uima.util.XmlCasDeserializer. This method deserializes into a pre-existing CAS, which you must create ahead of time, pre-set-up with the proper type system. See the Javadocs for details.

Section 2.3, “Running a CPE from Your Own Java Application” describes how to use the APIs to read a CPE descriptor and run it from an application.

For the finest level of control over the CPE descriptor settings, the CPE offers programmatic access to the descriptor via an API. With this API, a developer can create a complete descriptor and then save the result to a file. This also can be used to read in a descriptor (using XMLParser.parseCpeDescription as shown in the previous section), modify it, and write it back out again. The CPE Descriptor API allows a developer to redefine default behavior related to error handling for each component, turn-on check-pointing, change performance characteristics of the CPE, and plug-in a custom timer.

Below is some example code that illustrates how this works. See the Javadocs for package org.apache.uima.collection.metadata for more details.

//Creates descriptor with default settings
CpeDescription cpe = CpeDescriptorFactory.produceDescriptor();

//Add CollectionReader 
cpe.addCollectionReader([descriptor]);

//Add CasInitializer (deprecated)
cpe.addCasInitializer(<cas initializer descriptor>);

// Provide the number of CASes the CPE will use
cpe.setCasPoolSize(2);

//  Define and add Analysis Engine 
CpeIntegratedCasProcessor personTitleProcessor = 
   CpeDescriptorFactory.produceCasProcessor (“Person”);

// Provide descriptor for the Analysis Engine
personTitleProcessor.setDescriptor([descriptor]);

//Continue, despite errors and skip bad Cas
personTitleProcessor.setActionOnMaxError(“continue”);

  //Increase amount of time in ms the CPE waits for response
//from this Analysis Engine
personTitleProcessor.setTimeout(100000);

//Add Analysis Engine to the descriptor
cpe.addCasProcessor(personTitleProcessor);
                                
//  Define and add CAS Consumer
CpeIntegratedCasProcessor consumerProcessor = 
CpeDescriptorFactory.produceCasProcessor(“Printer”);
consumerProcessor.setDescriptor([descriptor]);

//Define batch size
consumerProcessor.setBatchSize(100);

//Terminate CPE on max errors
consumerProcessor.setActionOnMaxError(“terminate”);

//Add CAS Consumer to the descriptor
cpe.addCasProcessor(consumerProcessor);

//  Add Checkpoint file and define checkpoint frequency (ms)
cpe.setCheckpoint(“[path]/checkpoint.dat”, 3000);

//  Plug in custom timer class used for timing events
cpe.setTimer(“org.apache.uima.internal.util.JavaTimer”);

//  Define number of documents to process
cpe.setNumToProcess(1000);

//  Dump the descriptor to the System.out
((CpeDescriptionImpl)cpe).toXML(System.out);

The CPE descriptor for the above configuration looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<cpeDescription xmlns="http://uima.apache.org/resourceSpecifier">
  <collectionReader>
    <collectionIterator>
      <descriptor>
        <include href="[descriptor]"/>
      </descriptor>
      <configurationParameterSettings>...
      </configurationParameterSettings>
    </collectionIterator>

    <casInitializer>
      <descriptor>
        <include href="[descriptor]"/>
      </descriptor>
      <configurationParameterSettings>...
      </configurationParameterSettings>
    </casInitializer>
  </collectionReader>

  <casProcessors casPoolSize="2" processingUnitThreadCount="1">
    <casProcessor deployment="integrated" name="Person">
      <descriptor>
        <include href="[descriptor]"/>
      </descriptor>
      <deploymentParameters/>
      <errorHandling>
        <errorRateThreshold action="terminate" value="100/1000"/>
        <maxConsecutiveRestarts action="terminate" value="30"/>
        <timeout max="100000"/>
      </errorHandling>
      <checkpoint batch="100" time="1000ms"/>
    </casProcessor>

    <casProcessor deployment="integrated" name="Printer">
      <descriptor>
        <include href="[descriptor]"/>
      </descriptor>
      <deploymentParameters/>
      <errorHandling>
        <errorRateThreshold action="terminate"
          value="100/1000"/>
        <maxConsecutiveRestarts action="terminate"
          value="30"/>
        <timeout max="100000" default="-1"/>
      </errorHandling>
      <checkpoint batch="100" time="1000ms"/>
    </casProcessor>
  </casProcessors>

  <cpeConfig>
    <numToProcess>1000</numToProcess>
    <deployAs>immediate</deployAs>
    <checkpoint file="[path]/checkpoint.dat" time="3000ms"/>
    <timerImpl>
      org.apache.uima.reference_impl.util.JavaTimer
    </timerImpl>
  </cpeConfig>
</cpeDescription>

To build a semantic search index using the UIMA SDK, you run a Collection Processing Engine that includes your AE along with a CAS Consumer which takes the tokens and annotatitions, together with sentence boundaries, and feeds them to a semantic searcher's index term input. The alphaWorks semantic search component includes a CAS Consumer called the Semantic Search CAS Indexer that does this; this component is available from the alphaWorks site. Your AE must include an annotator that produces Tokens and Sentence annotations, along with any “semantic” annotations, because the Indexer requires this. The Semantic Search CAS Indexer's descriptor is located here: examples/descriptors/cas_consumer/SemanticSearchCasIndexer.xml .

<indexBuildSpecification>
  <indexBuildItem>
    <name>org.apache.uima.examples.tokenizer.Token</name>
    <indexRule>
      <style name="Term"/>
    </indexRule>    
  </indexBuildItem>
  <indexBuildItem>
    <name>org.apache.uima.examples.tokenizer.Sentence</name>
    <indexRule>
      <style name="Breaking"/>
    </indexRule>    
  </indexBuildItem>
  <indexBuildItem>
    <name>org.apache.uima.tutorial.Meeting</name>
    <indexRule>
      <style name="Annotation"/>
    </indexRule>    
  </indexBuildItem>
  <indexBuildItem>
    <name>org.apache.uima.tutorial.RoomNumber</name>
    <indexRule>
      <style name="Annotation">
        <attributeMappings>
          <mapping>
            <feature>building</feature>
            <indexName>building</indexName>
          </mapping>
        </attributeMappings>
      </style>
    </indexRule>    
  </indexBuildItem>
  <indexBuildItem>
    <name>org.apache.uima.tutorial.DateAnnot</name>
    <indexRule>
      <style name="Annotation"/>
    </indexRule>    
  </indexBuildItem>
  <indexBuildItem>
    <name>org.apache.uima.tutorial.TimeAnnot</name>
    <indexRule>
      <style name="Annotation"/>
    </indexRule>    
  </indexBuildItem>
</indexBuildSpecification>

The Semantic Search component from UIMA on alphaWorks contains a simple tool for running queries against a semantic search index. After building an index as described in the previous section, you can launch this tool by running the shell script: semanticSearch, found in the /bin subdirectory of the Semantic Search UIMA install, at the command prompt. If you are using Eclipse, and have installed the UIMA examples, there will be a Run configuration you can use to conveniently launch this, called UIMA Semantic Search. This will display the following screen:

Configure the fields on this screen as follows:

Now, in the “XML Fragments” field, you can type in single words or XML queries where the XML tags correspond to the labels in the index build specification file (e.g. <Meeting>UIMA</Meeting>). XML Fragments are described in the documentation for the semantic search engine component on http://www.alphaworks.ibm.com/tech/uima.

After you enter a query and click the “Search” button, a list of hits will appear. Select one of the documents and click “View Analysis” to view the document in the UIMA Annotation Viewer.

The source code for the Semantic Search query program is in examples/src/com/ibm/apache-uima/search/examples/SemanticSearchGUI.java . A simple command-line query program is also provided in examples/src/com/ibm/apache-uima/search/examples/SemanticSearch.java . Using these as a model, you can build a query interface from your own application. For details on the Semantic Search Engine query language and interface, see the documentation for the semantic search engine component on http://www.alphaworks.ibm.com/tech/uima.

To deploy a UIMA component as a SOAP Web Service, you need to first install the following software components:

Later versions of these components will likely also work, but have not been tested.

Next, you need to do the following setup steps:

Test your installation of Tomcat and Axis by starting Tomcat and going to http://localhost:8080/axis/happyaxis.jsp in your browser. Check to be sure that this reports that all of the required Axis libraries are present. One common missing file may be activation.jar, which you can get from java.sun.com.

After completing these setup instructions, you can deploy Analysis Engines or CAS Consumers as SOAP web services by using the deploytool utility, with is located in the /bin directory of the UIMA SDK. deploytool is a command line program utility that takes as an argument a web services deployment descriptors (WSDD file); example WSDD files are provided in the examples/deploy/soap directory of the UIMA SDK. Deployment Descriptors have been provided for deploying and undeploying some of the example Analysis Engines that come with the SDK.

As an example, the WSDD file for deploying the example Person Title annotator looks like this (important parts are in bold italics):

<deployment name="PersonTitleAnnotator" 
            xmlns="http://xml.apache.org/axis/wsdd/" 
            xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">

  <service name="urn:PersonTitleAnnotator" provider="java:RPC">

    <parameter name="scope" value="Request"/>

    <parameter name="className" 
      value="org.apache.uima.reference_impl.analysis_engine
                .service.soap.AxisAnalysisEngineService_impl"/>

    <parameter name="allowedMethods" value="getMetaData process"/>
    <parameter name="allowedRoles" value="*"/>
    <parameter name="resourceSpecifierPath" 
      value="C:/Program Files/apache/uima/examples/
           descriptors/analysis_engine/PersonTitleAnnotator.xml"/>

    <parameter name="numInstances" value="3"/>

    <!-- Type Mappings omitted from this document; 
          you will not need to edit them. -->

    <typeMapping .../>
    <typeMapping .../>
    <typeMapping .../>

  </service>

</deployment>

To modify this WSDD file to deploy your own Analysis Engine or CAS Consumer, just replace the areas indicated in bold italics (deployment name, service name, and resource specifier path) with values appropriate for your component.

The numInstances parameter specifies how many instances of your Analysis Engine or CAS Consumer will be created. This allows your service to support multiple clients concurrently. When a new request comes in, if all of the instances are busy, the new request will wait until an instance becomes available.

To deploy the Person Title annotator service, issue the following command:

C:/Program Files/apache/uima/bin>deploytool 
../examples/deploy/soap/Deploy_PersonTitleAnnotator.wsdd

Test if the deployment was successful by starting up a browser, pointing it to your Tomcat installation's “axis” webpage (e.g., http://localhost:8080/axis) and clicking on the List link. This should bring up a page which shows the deployed services, where you should see the service you just deployed.

The other components can be deployed by replacing Deploy_PersonTitleAnnotator.wsdd with one of the other Deploy descriptors in the deploy directory. The deploytool utility can also undeploy services when passed one of the Undeploy descriptors.

Once you have deployed your component as a web service, you may call it from a remote machine. See Section 3.6.3, “Calling a UIMA Service” for instructions.

There are no software prerequisites for deploying a Vinci service. The necessary libraries are part of the UIMA SDK. However, before you can use Vinci services you need to deploy the Vinci Naming Service (VNS), as described in section Section 3.6.5, “The Vinci Naming Services (VNS)”.

To deploy a service, you have to insure any components you want to include can be found on the class path. One way to do this is to set the environment variable UIMA_CLASSPATH to the set of class paths you need for any included components. Then run the startVinciService shell script, which is located in the bin directory, and pass it the path to a Vinci deployment descriptor, for example: C:UIMA>bin/startVinciService ../examples/deploy/vinci/Deploy_PersonTitleAnnotator.xml. If you are running Eclipse, and have the uimaj-examples project in your workspace, you can use the Eclipse Menu → Run → Run... and then pick “UIMA Start Vinci Service”.

This example deployment descriptor looks like:

<deployment name="Vinci Person Title Annotator Service">

  <service name="uima.annotator.PersonTitleAnnotator" provider="vinci">

    <parameter name="resourceSpecifierPath" 
      value="C:/Program Files/apache/uima/examples/descriptors/
          analysis_engine/PersonTitleAnnotator.xml"/>

    <parameter name="numInstances" value="1"/>

    <parameter name="serverSocketTimeout" value="120000"/>

  </service>

</deployment>

To modify this deployment descriptor to deploy your own Analysis Engine or CAS Consumer, just replace the areas indicated in bold italics (deployment name, service name, and resource specifier path) with values appropriate for your component.

The numInstances parameter specifies how many instances of your Analysis Engine or CAS Consumer will be created. This allows your service to support multiple clients concurrently. When a new request comes in, if all of the instances are busy, the new request will wait until an instance becomes available.

The serverSocketTimeout parameter specifies the number of milliseconds (default = 5 minutes) that the service will wait between requests to process something. After this amount of time, the server will presume the client may have gone away - and it “cleans up”, releasing any resources it is holding. The next call to process on the service will result in a cycle which will cause the client to re-establish its connection with the service (some additional overhead).

There are two additional parameters that you can add to your deployment descriptor:

The startVinciService script takes two additional optional parameters. The first one overrides the value of the VNS_HOST environment variable, allowing you to specify the name server to use. The second parameter if specified needs to be a unique (on this server) non-negative number, specifying the instance of this service. When used, this number allows multiple instances of the same named service to be started on one server; they will all register with the Vinci name service and be made available to client requests.

Once you have deployed your component as a web service, you may call it from a remote machine. See Section 3.6.3, “Calling a UIMA Service” for instructions.

Once an Analysis Engine or CAS Consumer has been deployed as a service, it can be used from any UIMA application, in the exact same way that a local Analysis Engine or CAS Consumer is used. For example, you can call an Analysis Engine service from the Document Analyzer or use the CPE Configurator to build a CPE that includes Analysis Engine and CAS Consumer services.

To do this, you use a service client descriptor in place of the usual Analysis Engine or CAS Consumer Descriptor. A service client descriptor is a simple XML file that indicates the location of the remote service and a few parameters. Example service client descriptors are provided in the UIMA SDK under the directories examples/descriptors/soapService and examples/descriptors/vinciService. The contents of these descriptors are explained below.

Also, before you can call a SOAP service, you need to have the necessary Axis JAR files in your classpath. If you use any of the scripts in the bin directory of the UIMA installation to launch your application, such as documentAnalyzer, these JARs are added to the classpath, automatically, using the CATALINA_HOME environment variable. The required files are the following (all part of the Apache Axis download)

<uriSpecifier xmlns="http://uima.apache.org/resourceSpecifier">
   <resourceType>AnalysisEngine</resourceType>
   <uri>http://localhost:8080/axis/services/urn:PersonTitleAnnotator</uri>
    <protocol>SOAP</protocol>
    <timeout>60000</timeout>           
</uriSpecifier>

<uriSpecifier xmlns="http://uima.apache.org/resourceSpecifier">
   <resourceType>AnalysisEngine</resourceType>
   <uri>uima.annot.PersonTitleAnnotator</uri>
   <protocol>Vinci</protocol>
   <timeout>60000</timeout> 
   <parameters>
     <parameter name="VNS_HOST" value="some.internet.ip.name-or-address"/>
     <parameter name="VNS_PORT" value="9000"/>
   </parameters>
</uriSpecifier>

Remotely deployed services are started on remote machines, using UIMA component descriptors on those remote machines. These descriptors supply any configuration and resource parameters for the service (configuration parameters are not transmitted from the calling instance to the remote one). Likewise, the remote descriptors supply the type system specification for the remote annotators that will be run (the type system of the calling instance is not transmitted to the remote one).

The remote service wrapper, when it receives a CAS from the caller, instantiates it for the remote service, making instances of all types which the remote service specifies. Other instances in the incoming CAS for types which the remote service has no type specification for are kept aside, and when the remote service returns the CAS back to the caller, these type instances are re-merged back into the CAS being transmitted back to the caller. Because of this design, a remote service which doesn't declare a type system won't receive any type instances.

Vinci consists of components for building network-accessible services, clients for accessing those services, and an infrastructure for locating and managing services. The primary infrastructure component is the Vinci directory, known as VNS (for Vinci Naming Service).

On startup, Vinci services locate the VNS and provide it with information that is used by VNS during service discovery. Vinci service provides the name of the host machine on which it runs, and the name of the service. The VNS internally creates a binding for the service name and returns the port number on which the Vinci service will wait for client requests. This VNS stores its bindings in a filesystem in a file called vns.services.

In Vinci, services are identified by their service name. If there is more than one physical service with the same service name, then Vinci assumes they are equivalent and will route queries to them randomly, provided that they are all running on different hosts. You should therefore use a unique service name if you don't want to conflict with other services listed in whatever VNS you have configured jVinci to use.

java.net.BindException: Address already in use:

JVM_Bind

[10/6/04 3:44 PM | main] WARNING: Config file doesn't exist, 
            creating a new empty config file!
[10/6/04 3:44 PM | main] Loading config file : .vns.services
[10/6/04 3:44 PM | main] Loading workspaces file : .vns.workspaces
[10/6/04 3:44 PM | main] ====================================
(WARNING) Unexpected exception:
java.io.FileNotFoundException: .vns.workspaces (The system cannot find
the file specified)
  at java.io.FileInputStream.open(Native Method)
  at java.io.FileInputStream.<init>(Unknown Source)
  at java.io.FileInputStream.<init>(Unknown Source)
  at java.io.FileReader.<init>(Unknown Source)
  at org.apache.vinci.transport.vns.service.VNS.loadWorkspaces(VNS.java:339
  at org.apache.vinci.transport.vns.service.VNS.startServing(VNS.java:237)
  at org.apache.vinci.transport.vns.service.VNS.main(VNS.java:179)
[10/6/04 3:44 PM | main] WARNING: failed to load workspace.
[10/6/04 3:44 PM | main] VNS Workspace : null
[10/6/04 3:44 PM | main] Loading counter file : .vns.counter
[10/6/04 3:44 PM | main] Could not load the counter file : .vns.counter
[10/6/04 3:44 PM | main] Starting backup thread,
            using files .vns.services.bak
and .vns.services
[10/6/04 3:44 PM | main] Serving on port : 9000
[10/6/04 3:44 PM | Thread-0] Backup thread started
[10/6/04 3:44 PM | Thread-0] Saving to config file : .vns.services.bak
>>>>>>>>>>>>> VNS is up and running! <<<<<<<<<<<<<<<<<
>>>>>>>>>>>>> Type 'quit' and hit ENTER to terminate VNS <<<<<<<<<<<<<
[10/6/04 3:44 PM | Thread-0] Config save required 10 millis.
[10/6/04 3:44 PM | Thread-0] Saving to config file : .vns.services
[10/6/04 3:44 PM | Thread-0] Config save required 10 millis.
[10/6/04 3:44 PM | Thread-0] Saving counter file : .vns.counter

java -DVNS_HOST=localhost -DVNS_PORT=9000 ...

java -DVNS_HOST=<host> -DVNS_PORT=9000 ...

(WARNING) Unexpected exception:
org.apache.vinci.transport.ServiceDownException: 
          VNS inaccessible: java.net.Connect
Exception: Connection refused: connect

[10/6/04 3:44 PM | main] Serving on port : 9000

UIMA has several timeout specifications, summarized here. The timeouts associated with remote services are discussed below. In addition there are timeouts that can be specified for:

If your application uses remote UIMA services it is important to consider how to set the timeout values appropriately. This is particularly important if your service can take a long time to process each request.

There are two types of timeout settings in UIMA, the client timeout and the server socket timeout. The client timeout is usually the most important, it specifies how long that client is willing to wait for the service to process each CAS. The client timeout can be specified for both Vinci and SOAP. The server socket timeout (Vinci only) specifies how long the service holds the connection open between calls from the client. After this amount of time, the server will presume the client may have gone away - and it “cleans up”, releasing any resources it is holding. The next call to process on the service will cause the client to re-establish its connection with the service (some additional overhead).

<uriSpecifier xmlns="http://uima.apache.org/resourceSpecifier">
   <resourceType>AnalysisEngine</resourceType>
   <uri>uima.annot.PersonTitleAnnotator</uri>
   <protocol>Vinci</protocol>
   <timeout>60000</timeout> 
   <parameters>
     <parameter name="VNS_HOST" value="some.internet.ip.name-or-address"/>
     <parameter name="VNS_PORT" value="9000"/>
   </parameters>
</uriSpecifier>

<errorHandling>
  <maxConsecutiveRestarts .../>
  <errorRateThreshold .../>
  <timeout max="60000"/>
</errorHandling>

<deployment name="Vinci Person Title Annotator Service">

  <service name="uima.annotator.PersonTitleAnnotator" provider="vinci">

    <parameter name="resourceSpecifierPath" 
      value="C:/Program Files/apache/uima/examples/descriptors/
          analysis_engine/PersonTitleAnnotator.xml"/>

    <parameter name="numInstances" value="1"/>

    <parameter name="serverSocketTimeout" value="120000"/>

  </service>

</deployment>

Flow Controller implementations should extend from the JCasFlowController_ImplBase or CasFlowController_ImplBase classes, depending on which CAS interface they prefer to use. As with other types of components, the Flow Controller ImplBase classes define optional initialize, destroy, and reconfigure methods. They also define the required method computeFlow.

The computeFlow method is called by the framework whenever a new CAS enters the Aggregate Analysis Engine. It is given the CAS as an argument and must return an object which implements the Flow interface (the Flow object). The Flow Controller developer must define this object. It is the object that is responsible for routing this particular CAS through the components of the Aggregate Analysis Engine. For convenience, the framework provides basic implementation of flow objects in the classes CasFlow_ImplBase and JCasFlow_ImplBase; use the JCas one if you are using the JCas interface to the CAS.

The framework then uses the Flow object and calls its next() method, which returns a Step object (implemented by the UIMA Framework) that indicates what to do next with this CAS next. There are three types of steps currently supported:

After executing the step, the framework will call the Flow object's next() method again to determine the next destination, and this will be repeated until the Flow Object indicates that processing is complete by returning a FinalStep.

The Flow Controller has access to a FlowControllerContext, which is a subtype of UimaContext. In addition to the configuration parameter and resource access provided by a UimaContext, the FlowControllerContext also gives access to the metadata for all of the Analysis Engines that the Flow Controller can route CASes to. Most Flow Controllers will need to use this information to make routing decisions. You can get a handle to the FlowControllerContext by calling the getContext() method defined in JCasFlowController_ImplBase and CasFlowController_ImplBase. Then, the FlowControllerContext.getAnalysisEngineMetaDataMap method can be called to get a map containing an entry for each of the Analysis Engines in the Aggregate. The keys in this map are the same as the delegate analysis engine keys specified in the aggregate descriptor, and the values are the corresponding AnalysisEngineMetaData objects.

Finally, the Flow Controller has optional methods addAnalysisEngines and removeAnalysisEngines. These methods are intended to notify the Flow Controller if new Analysis Engines are available to route CASes to, or if previously available Analysis Engines are no longer available. However, the current version of the Apache UIMA framework does not support dynamically adding or removing Analysis Engines to/from an aggregate, so these methods are not currently called. Future versions may support this feature.

This section walks through the source code of an example Flow Controller that simluates a simple version of the “Whiteboard” flow model. At each step of the flow, the Flow Controller looks it all of the available Analysis Engines that have not yet run on this CAS, and picks one whose input requirements are satisfied.

The Java class for the example is org.apache.uima.examples.flow.WhiteboardFlowController and the source code is included in the UIMA SDK under the examples/src directory.

public class WhiteboardFlowController 
          extends CasFlowController_ImplBase {
  public Flow computeFlow(CAS aCAS) 
          throws AnalysisEngineProcessException {
    WhiteboardFlow flow = new WhiteboardFlow();
    // As of release 2.3.0, the following is not needed,
    //   because the framework does this automatically
    // flow.setCas(aCAS); 
                        
    return flow;
  }

  class WhiteboardFlow extends CasFlow_ImplBase {
     // Discussed Later
  }
}

class WhiteboardFlow extends CasFlow_ImplBase {
  private Set mAlreadyCalled = new HashSet();

  public Step next() throws AnalysisEngineProcessException {
    // Get the CAS that this Flow object is responsible for routing.
    // Each Flow instance is responsible for a single CAS.
    CAS cas = getCas();

    // iterate over available AEs
    Iterator aeIter = getContext().getAnalysisEngineMetaDataMap().
        entrySet().iterator();
    while (aeIter.hasNext()) {
      Map.Entry entry = (Map.Entry) aeIter.next();
      // skip AEs that were already called on this CAS
      String aeKey = (String) entry.getKey();
      if (!mAlreadyCalled.contains(aeKey)) {
        // check for satisfied input capabilities 
        //(i.e. the CAS contains at least one instance
        // of each required input
        AnalysisEngineMetaData md = 
            (AnalysisEngineMetaData) entry.getValue();
        Capability[] caps = md.getCapabilities();
        boolean satisfied = true;
        for (int i = 0; i < caps.length; i++) {
          satisfied = inputsSatisfied(caps[i].getInputs(), cas);
          if (satisfied)
            break;
        }
        if (satisfied) {
          mAlreadyCalled.add(aeKey);
          if (mLogger.isLoggable(Level.FINEST)) {
            getContext().getLogger().log(Level.FINEST, 
                "Next AE is: " + aeKey);
          }
          return new SimpleStep(aeKey);
        }
      }
    }
    // no appropriate AEs to call - end of flow
    getContext().getLogger().log(Level.FINEST, "Flow Complete.");
    return new FinalStep();
  }

  private boolean inputsSatisfied(TypeOrFeature[] aInputs, CAS aCAS) {
      //implementation detail; see the actual source code
  }
}

return new SimpleStep(aeKey);

return new FinalStep();

The Artifact is the unstructured thing being analyzed by an annotator. It could be an HTML web page, an image, a video stream, a recorded audio conversation, an MPEG-4 stream, etc. Artifacts are often restructured in the course of processing to facilitate particular kinds of analysis. For instance, an HTML page may be converted into a “de-tagged” version. Annotators at different places in the pipeline may be analyzing different versions of the artifact.

Each representation of an Artifact is called a Subject of Analysis, abbreviated using the acronym “Sofa” which stands for Subject OF Analysis. Annotation metadata, which have explicit designations of sub-regions of the artifact to which they apply, are always associated with a particular Sofa. For instance, an annotation over text specifies two features, the begin and end, which represent the character offsets into the text string Sofa being analyzed.

Other examples of representations of Artifacts, which could be Sofas include: An HTML web page, a detagged web page, the translated text of that document, an audio or video stream, closed-caption text from a video stream, etc.

Often, there is one Sofa being analyzed in a CAS. The next chapter will show how UIMA facilitates working with multiple representations of an artifact at the same time, in the same CAS.

When a CAS is created, you can set its Sofa Data, just one time; this property insures that metadata describing regions of the Sofa remain valid. As a consequence, the following methods that set data for a given Sofa can only be called once for a given Sofa.

The following methods on the CAS set the Sofa Data to one of the 3 formats. Assume that the variable “aCas” holds a reference to a CAS:

aCas.setSofaDataString(document_text_string, mime_type_string);
aCas.setSofaDataArray(feature_structure_primitive_array, mime_type_string);
aCas.setSofaDataURI(uri_string, mime_type_string);

In addition, the method aCas.setDocumentText(document_text_string) may still be used, and is equivalent to setSofaDataString(string, "text"). The mime type is currently not used by the UIMA framework, but may be set and retrieved by user code.

Feature Structure primitive arrays are all the UIMA Array types except arrays of Feature Structures, Strings, and Booleans. Typically, these are arrays of bytes, but can be other types, such as floats, longs, etc.

The URI string should conform to the standard URI format.

The analysis algorithms typically work with the Sofa data. The following methods on the CAS access the Sofa Data:

String           aCas.getDocumentText();
String           aCas.getSofaDataString();
FeatureStructure aCas.getSofaDataArray();
String           aCas.getSofaDataURI();
String           aCas.getSofaMimeType();

The getDocumentText and getSofaDataString return the same text string. The getSofaDataURI returns the URI itself, not the data the URI is pointing to. You can use standard Java I/O capabilities to get the data associated with the URI, or use the UIMA Framework Streaming method described next.

The framework provides a consistent method for accessing the Sofa data, independent of it being stored locally, or accessed remotely using the URI. Get a Java InputStream instance from the Sofa data using:

InputStream inputStream = aCas.getSofaDataStream();

The built-in CAS type, uima.tcas.Annotation, is just one kind of definition of an Annotation. It was designed for annotating text strings, and has begin and end features which describe which substring of the Sofa being annotated.

For applications which have other kinds of Sofas, the UIMA developer will design their own kinds of Annotation types, as needed to describe an annotation, by declaring new types which are subtypes of uima.cas.AnnotationBase. For instance, for images, you might have the concept of a rectangular region to which the annotation applies. In this case, you might describe the region with 2 pairs of x, y coordinates.

Annotations are always associated with a particular Sofa. In subsequent chapters, you will learn how there can be multiple Sofas associated with an artifact; which Sofa an annotation refers to is described by the Annotation feature structure itself.

All annotation types extend from the built-in type uima.cas.AnnotationBase. This type has one feature, a reference to the Sofa associated with the annotation. This value is currently used by the Framework to support the getCoveredText() method on the annotation instance - this returns the portion of a text Sofa that the annotation spans. It also is used to insure that the Annotation is indexed only in the CAS View associated with this Sofa.

The developer assigns a name to the View / Sofa, which is a simple string (following the rules for Java identifiers, usually without periods, but see special exception below). These names are declared in the component XML metadata, and are used during assembly and by the runtime to enable switching among multiple Views of the CAS at the same time.

Some applications contain components that expect a variable number of Sofas as input or output. An example of a component that takes a variable number of input Sofas could be one that takes several translations of a document and merges them, where each translation was in a separate Sofa.

You can specify a variable number of input or output sofa names, where each name has the same base part, by writing the base part of the name (with no periods), followed by a period character and an asterisk character (.*). These denote sofas that have names matching the base part up to the period; for example, names such as base_name_part.TTX_3d would match a specification of base_name_part.*.

Components and applications can be written to be Multi-View or Single-View. Most components used as primitive building blocks are expected to be Single-View. UIMA provides capabilities to combine these kinds of components with Multi-View components when assembling analysis aggregates or applications.

Single-View components and applications use only one subject of analysis, and one CAS View. The code and descriptors for these components do not use the facilities described in this chapter.

Conversely, Multi-View components and applications are aware of the possibility of multiple Views and Sofas, and have code and XML descriptors that create and manipulate them.

Every UIMA component has an associated XML Component Descriptor. Multi-View components are identified simply as those whose descriptors declare one or more Sofa names in their Capability sections, as inputs or outputs. If a Component Descriptor does not mention any input or output Sofa names, the framework treats that component as a Single-View component.

A Multi-View component is passed a special kind of a CAS object, called a base CAS, which it must use to switch to the particular view it wishes to process. The base CAS object itself has no Sofa and no ability to use Indexes; only the views have that capability.

Additional capabilities provided for components and applications aware of the possibilities of multiple Views and Sofas include:

Each Multi-View component that creates a Sofa or wants to switch to a specific previously created Sofa must declare the name for the Sofa in the capabilities section. For example, a component expecting as input a web document in html format and creating a plain text document for further processing might declare:

<capabilities>
  <capability>
    <inputs/>
    <outputs/>
    <inputSofas>
      <sofaName>rawContent</sofaName>
    </inputSofas>
    <outputSofas>
      <sofaName>detagContent</sofaName>
    </outputSofas>
  </capability>
</capabilities>

Details on this specification are found in Chapter 2, Component Descriptor Reference. The Component Descriptor Editor supports Sofa declarations on the Section 1.9, “Capabilities Page”.

For each component of an Aggregate, name mapping specifies the conversion between component Sofa names and names at the aggregate level.

Here's an example. Consider two Multi-View annotators to be assembled into an aggregate which takes an audio segment consisting of spoken English and produces a German text translation.

The first annotator takes an audio segment as input Sofa and produces a text transcript as output Sofa. The annotator designer might choose these Sofa names to be “AudioInput” and “TranscribedText”.

The second annotator is designed to translate text from English to German. This developer might choose the input and output Sofa names to be “EnglishDocument” and “GermanDocument”, respectively.

In order to hook these two annotators together, the following section would be added to the top level of the aggregate descriptor:

<sofaMappings>
  <sofaMapping>
    <componentKey>SpeechToText</componentKey>
    <componentSofaName>AudioInput</componentSofaName>
    <aggregateSofaName>SegementedAudio</aggregateSofaName>
  </sofaMapping>
  <sofaMapping>
    <componentKey>SpeechToText</componentKey>
    <componentSofaName>TranscribedText</componentSofaName>
    <aggregateSofaName>EnglishTranscript</aggregateSofaName>
  </sofaMapping>
  <sofaMapping>
    <componentKey>EnglishToGermanTranslator</componentKey>
    <componentSofaName>EnglishDocument</componentSofaName>
    <aggregateSofaName>EnglishTranscript</aggregateSofaName>
  </sofaMapping>
  <sofaMapping>
    <componentKey>EnglishToGermanTranslator</componentKey>
    <componentSofaName>GermanDocument</componentSofaName>
    <aggregateSofaName>GermanTranslation</aggregateSofaName>
  </sofaMapping>
</sofaMappings>

The Component Descriptor Editor supports Sofa name mapping in aggregates and simplifies the task. See Section 1.9.1, “Sofa (and view) name mappings” for details.

The CPE descriptor aggregates together a Collection Reader and CAS Processors (Annotators and CAS Consumers). Sofa mappings can be added to the following elements of CPE descriptors: <collectionIterator>, <casInitializer> and the <casProcessor>. To be consistent with the organization of CPE descriptors, the maps for the CPE descriptor are distributed among the XML markup for each of the parts (collectionIterator, casInitializer, casProcessor). Because of this the <componentKey> element is not needed. Finally, rather than sub-elements for the parts, the XML markup for these uses attributes. See Section 3.6.1.3, “<sofaNameMappings> Element”.

Here's an example. Let's use the aggregate from the previous section in a collection processing engine. Here we will add a Collection Reader that outputs audio segments in an output Sofa named “nextSegment”. Remember to declare an output Sofa nextSegment in the collection reader description. We'll add a CAS Consumer in the next section.

<collectionReader>
  <collectionIterator>
    <descriptor>
    . . .
    </descriptor>
    <configurationParameterSettings>...</configurationParameterSettings>
    <sofaNameMappings>
      <sofaNameMapping componentSofaName="nextSegment"
                       cpeSofaName="SegementedAudio"/>
      </sofaNameMappings>
  </collectionIterator>
  <casInitializer/>
<collectionReader>

At this point the CAS Processor section for the aggregate does not need any Sofa mapping because the aggregate input Sofa has the same name, “SegementedAudio”, as is being produced by the Collection Reader.

Single-View components receive a Sofa named “_InitialView”, or a Sofa that is mapped to this name.

For example, assume that the CAS Consumer to be used in our CPE is a Single-View component that expects the analysis results associated with the input CAS, and that we want it to use the results from the translated German text Sofa. The following mapping added to the CAS Processor section for the CPE will instruct the CPE to get the CAS view for the German text Sofa and pass it to the CAS Consumer:

<casProcessor>
  . . .
  <sofaNameMappings>
    <sofaNameMapping componentSofaName="_InitialView"
                           cpeSofaName="GermanTranslation"/>
  <sofaNameMappings>
</casProcessor>

An alternative syntax for this kind of mapping is to simply leave out the component sofa name in this case.

Applications which instantiate UIMA components directly using the UIMAFramework methods can also create a top level Sofa mapping using the “additional parameters” capability.

//create a "root" UIMA context for your whole application

UimaContextAdmin rootContext =
   UIMAFramework.newUimaContext(UIMAFramework.getLogger(),
      UIMAFramework.newDefaultResourceManager(),
      UIMAFramework.newConfigurationManager());

input = new XMLInputSource("test.xml");
desc = UIMAFramework.getXMLParser().parseAnalysisEngineDescription(input);

//setup sofa name mappings using the api

HashMap sofamappings = new HashMap();
sofamappings.put("localName1", "globalName1");
sofamappings.put("localName2", "globalName2");
  
//create a UIMA Context for the new AE we are about to create

//first argument is unique key among all AEs used in the application
UimaContextAdmin childContext = rootContext.createChild("myAE", sofamap);

//instantiate AE, passing the UIMA Context through the additional
//parameters map

Map additionalParams = new HashMap();
additionalParams.put(Resource.PARAM_UIMA_CONTEXT, childContext);

AnalysisEngine ae = 
        UIMAFramework.produceAnalysisEngine(desc,additionalParams);

Sofa mappings are applied from the inside out, i.e., local to global. First, any aggregate mappings are applied, then any CPE mappings, and finally, any specified using this “additional parameters” capability.

Currently, no client-side Sofa mapping information is passed from a UIMA client to a remote service. This can cause complications for UIMA services in a Multi-View application.

Remote Multi-View services will work only if the service is Single-View, or if the Sofa names expected by the service exactly match the Sofa names produced by the client.

If your application requires Sofa mappings for a remote Analysis Engine, you can wrap your remotely deployed AE in an aggregate (on the remote side), and specify the necessary Sofa mappings in the descriptor for that aggregate.

The annotator descriptor in examples/descriptors/analysis_engine/SofaExampleAnnotator.xml declares an input Sofa named “EnglishDocument” and an output Sofa named “GermanDocument”. A custom type “CrossAnnotation” is also defined:

<typeDescription>
  <name>sofa.test.CrossAnnotation</name>
  <description/>
  <supertypeName>uima.tcas.Annotation</supertypeName>
  <features>
    <featureDescription>
      <name>otherAnnotation</name>
      <description/>
      <rangeTypeName>uima.tcas.Annotation</rangeTypeName>
    </featureDescription>
  </features>
</typeDescription>

The CrossAnnotation type is derived from uima.tcas.Annotation and includes one new feature: a reference to another annotation.

The application driver instantiates an analysis engine, seAnnotator, from the annotator descriptor, obtains a new base CAS using that engine's CAS definition, and creates the expected input Sofa using:

CAS cas = seAnnotator.newCAS();
CAS aView = cas.createView("EnglishDocument");

Since seAnnotator is a primitive component, and no Sofa mapping has been defined, the SofaID will be “EnglishDocument”. Local Sofa data is set using:

aView.setDocumentText("this beer is good");

At this point the CAS contains all necessary inputs for the translation annotator and its process method is called.

Annotator processing consists of parsing the English document into individual words, doing word-by-word translation and concatenating the translations into a German translation. Analysis metadata on the English Sofa will be an annotation for each English word. Analysis metadata on the German Sofa will be a CrossAnnotation for each German word, where the otherAnnotation feature will be a reference to the associated English annotation.

Code of interest includes two CAS views:

// get View of the English text Sofa
englishView = aCas.getView("EnglishDocument");

// Create the output German text Sofa
germanView = aCas.createView("GermanDocument");

the indexing of annotations with the appropriate view:

englishView.addFsToIndexes(engAnnot);
. . .
germanView.addFsToIndexes(germAnnot);

and the combining of metadata belonging to different Sofas in the same feature structure:

// add link to English text
germAnnot.setFeatureValue(other, engAnnot);

The application needs to get the results of analysis, which may be in different views. Analysis results for each Sofa are dumped independently by iterating over all annotations for each associated CAS view. For the English Sofa:

//get annotation iterator for this CAS
FSIndex anIndex = aView.getAnnotationIndex();
FSIterator anIter = anIndex.iterator();
while (anIter.isValid()) {
  AnnotationFS annot = (AnnotationFS) anIter.get();
  System.out.println(" " + annot.getType().getName()
                         + ": " + annot.getCoveredText());
  anIter.moveToNext();
}

Iterating over all German annotations looks the same, except for the following:

if (annot.getType() == cross) {
  AnnotationFS crossAnnot =
          (AnnotationFS) annot.getFeatureValue(other);
  System.out.println("   other annotation feature: "
          + crossAnnot.getCoveredText());
}

Of particular interest here is the built-in Annotation type method getCoveredText(). This method uses the “begin” and “end” features of the annotation to create a substring from the CAS document. The SofaRef feature of the annotation is used to identify the correct Sofa's data from which to create the substring.

The example program output is:

---Printing all annotations for English Sofa---
uima.tcas.DocumentAnnotation: this beer is good
uima.tcas.Annotation: this
uima.tcas.Annotation: beer
uima.tcas.Annotation: is
uima.tcas.Annotation: good
      
---Printing all annotations for German Sofa---
uima.tcas.DocumentAnnotation: das bier ist gut
sofa.test.CrossAnnotation: das
 other annotation feature: this
sofa.test.CrossAnnotation: bier
 other annotation feature: beer
sofa.test.CrossAnnotation: ist
 other annotation feature: is
sofa.test.CrossAnnotation: gut
 other annotation feature: good

CAS Multiplier implementations should extend from the JCasMultiplier_ImplBase or CasMultiplier_ImplBase classes, depending on which CAS interface they prefer to use. As with other types of analysis components, the CAS Multiplier ImplBase classes define optional initialize, destroy, and reconfigure methods. There are then three required methods: process, hasNext, and next. The framework interacts with these methods as follows:

From the time when process is called until the hasNext method returns false (or process is called again), the CAS Multiplier “owns” the CAS that was passed to its process method. The CAS Multiplier can store a reference to this CAS in a local field and can read from it or write to it during this time. Once the ending condition occurs, the CAS Multiplier gives up ownership of the input CAS and should no longer retain a reference to it.

The CAS Multiplier's next method must return a CAS instance that represents a new representation of the input artifact. Since CAS instances are managed by the framework, the CAS Multiplier cannot actually create a new CAS; instead it should request an empty CAS by calling the method:

CAS getEmptyCAS()

or

JCas getEmptyJCas()

which are defined on the CasMultiplier_ImplBase and JCasMultiplier_ImplBase classes, respectively.

Note that if it is more convenient you can request an empty CAS during the process or hasNext methods, not just during the next method.

By default, a CAS Multiplier is only allowed to hold one output CAS instance at a time. You must return the CAS from the next method before you can request a second CAS. If you try to call getEmptyCAS a second time you will get an Exception. You can change this default behavior by overriding the method getCasInstancesRequired to return the number of CAS instances that you need. Be aware that CAS instances consume a significant amount of memory, so setting this to a large value will cause your application to use a lot of RAM. So, for example, it is not a good practice to attempt to generate a large number of new CASes in the CAS Multiplier's process method. Instead, you should spread your processing out across the calls to the hasNext or next methods.

The Type System of the empty CAS will contain all of the type definitions for all components of the outermost Aggregate Analysis Engine or Collection Processing Engine that contains your CAS Multiplier. Therefore downstream components that receive these CASes can add new instances of any type that they define.

This section walks through the source code of an example CAS Multiplier that breaks text documents into smaller pieces. The Java class for the example is org.apache.uima.examples.casMultiplier.SimpleTextSegmenter and the source code is included in the UIMA SDK under the examples/src directory.

public class SimpleTextSegmenter extends JCasMultiplier_ImplBase {
  private String mDoc;
  private int mPos;
  private int mSegmentSize;
  private String mDocUri;  
  
  public void initialize(UimaContext aContext) 
          throws ResourceInitializationException
  { ... }

  public void process(JCas aJCas) throws AnalysisEngineProcessException
  { ... }

  public boolean hasNext() throws AnalysisEngineProcessException
  { ... }

  public AbstractCas next() throws AnalysisEngineProcessException
  { ... }
}

public void initialize(UimaContext aContext) throws
                    ResourceInitializationException {
  super.initialize(aContext);
  mSegmentSize = ((Integer)aContext.getConfigParameterValue(
                            "segmentSize")).intValue();
}

public void process(JCas aJCas) 
       throws AnalysisEngineProcessException {
  mDoc = aJCas.getDocumentText();
  mPos = 0;
  // retreive the filename of the input file from the CAS so that it can 
  // be added to each segment
  FSIterator it = aJCas.
          getAnnotationIndex(SourceDocumentInformation.type).iterator();
  if (it.hasNext()) {
    SourceDocumentInformation fileLoc = 
          (SourceDocumentInformation)it.next();
    mDocUri = fileLoc.getUri();
  }
  else {
    mDocUri = null;
  }
 }

public boolean hasNext() throws AnalysisEngineProcessException {
  return mPos < mDoc.length();
}

public AbstractCas next() throws AnalysisEngineProcessException {
  int breakAt = mPos + mSegmentSize;
  if (breakAt > mDoc.length())
    breakAt = mDoc.length();
          
  // search for the next newline character. 
  // Note: this example segmenter implementation
  // assumes that the document contains many newlines. 
  // In the worst case, if this segmenter
  // is run on a document with no newlines, 
  // it will produce only one segment containing the
  // entire document text. 
  // A better implementation might specify a maximum segment size as
  // well as a minimum.
          
  while (breakAt < mDoc.length() && 
         mDoc.charAt(breakAt - 1) != '\n')
    breakAt++;

  JCas jcas = getEmptyJCas();
  try {
    jcas.setDocumentText(mDoc.substring(mPos, breakAt));
    // if original CAS had SourceDocumentInformation, 
          also add SourceDocumentInformatio
    // to each segment
    if (mDocUri != null) {
      SourceDocumentInformation sdi = 
          new SourceDocumentInformation(jcas);
      sdi.setUri(mDocUri);
      sdi.setOffsetInSource(mPos);
      sdi.setDocumentSize(breakAt - mPos);
      sdi.addToIndexes();

      if (breakAt == mDoc.length()) {
        sdi.setLastSegment(true);
      }
    }

    mPos = breakAt;
    return jcas;
  } catch (Exception e) {
    jcas.release();
    throw new AnalysisEngineProcessException(e);
  }
}

JCas jcas = getEmptyJCas();

Since CAS Multiplier are considered a type of Analysis Engine, adding them to an aggregate works the same way as for other Analysis Engines. Using the CDE, you just click the “Add...” button in the Component Engines view and browse to the Analysis Engine Descriptor of your CAS Multiplier. If editing the aggregate descriptor directly, just import the Analysis Engine Descriptor of your CAS Multiplier as usual.

An example descriptor for an Aggregate Analysis Engine containing a CAS Multiplier is provided in examples/descriptors/cas_multiplier/SegmenterAndTokenizerAE.xml. This Aggregate runs the SimpleTextSegmenter example to break a large document into segments, and then runs each segment through the SimpleTokenAndSentenceAnnotator. Try running it in the Document Analyzer tool with a large text file as input, to see that it outputs multiple output CASes, one for each segment produced by the SimpleTextSegmenter.

CAS Multipliers are only supported in the context of Fixed Flow or custom Flow Control. If you use the built-in “Fixed Flow” for your Aggregate Analysis Engine, you can position the CAS Multiplier anywhere in that flow. Processing then works as follows: When a CAS is input to the Aggregate AE, that CAS is routed to the components in the order specified by the Fixed Flow, until that CAS reaches a CAS Multiplier.

Upon reaching a CAS Multiplier, if that CAS Multiplier produces new output CASes, then each output CAS from that CAS Multiplier will continue through the flow, starting at the node immediately after the CAS Multiplier in the Fixed Flow. No further processing will be done on the original input CAS after it has reached a CAS Multiplier – it will not continue in the flow.

If the CAS Multiplier does not produce any output CASes for a given input CAS, then that input CAS will continue in the flow. This behavior is appropriate, for example, for a CAS Multiplier that may segment an input CAS into pieces but only does so if the input CAS is larger than a certain size.

It is possible to put more than one CAS Multiplier in your flow. In this case, when a new CAS output from the first CAS Multiplier reaches the second CAS Multiplier and if the second CAS Multiplier produces output CASes, then no further processing will occur on the input CAS, and any new output CASes produced by the second CAS Multiplier will continue the flow starting at the node after the second CAS Multiplier.

This default behavior can be customized. The FixedFlowController component that implement's UIMA's default flow defines a configuration parameter ActionAfterCasMultiplier that can take the following values:

You can override this parameter in your Aggregate Analysis Engine the same way you would override a parameter in a delegate Analysis Engine. But to do so you must first explicitly identify that you are using the FixedFlowController implementation by importing its descriptor into your aggregate as follows:

<flowController key="FixedFlowController">
          <import name="org.apache.uima.flow.FixedFlowController"/>
        </flowController>      

The parameter could then be overriden as, for example:

<configurationParameters>
          <configurationParameter>
            <name>ActionForIntermediateSegments</name>
            <type>String</type>
            <multiValued>false</multiValued>
            <mandatory>false</mandatory>
            <overrides>
              <parameter>
                FixedFlowController/ActionAfterCasMultiplier
              </parameter>
            </overrides>
          </configurationParameter>   
        </configurationParameters>
  
       <configurationParameterSettings>
         <nameValuePair>
           <name>ActionForIntermediateSegments</name>
           <value>
             <string>drop</string>
           </value>
         </nameValuePair>
       </configurationParameterSettings>

This overriding can also be done using the Component Descriptor Editor tool. An example of an Analysis Engine that overrides this parameter can be found in examples/descriptors/cas_multiplier/Segment_Annotate_Merge_AE.xml. For more information about how to specify a flow controller as part of your Aggregate Analysis Engine descriptor, see Section 4.3, “Adding Flow Controller to an Aggregate”.

If you would like to further customize the flow, you will need to implement a custom FlowController as described in Chapter 4, Flow Controller Developer's Guide. For example, you could implement a flow where a CAS that is input to a CAS Multiplier will be processed further by some downstream components, but not others.

An important consideration when you put a CAS Multiplier inside an Aggregate Analysis Engine is whether you want the Aggregate to also function as a CAS Multiplier – that is, whether you want the new output CASes produced within the Aggregate to be output from the Aggregate. This is controlled by the <outputsNewCASes> element in the Operational Properties of your Aggregate Analysis Engine descriptor. The syntax is the same as what was described in Section 7.2, “CAS Multiplier Descriptor” .

If you set this property to true, then any new output CASes produced by a CAS Multiplier inside this Aggregate will be output from the Aggregate. Thus the Aggregate will function as a CAS Multiplier and can be used in any of the ways in which a primitive CAS Multiplier can be used.

If you set the <outputsNewCASes> property to false , then any new output CASes produced by a CAS Multiplier inside the Aggregate will be dropped (i.e. the CASes will be released back to the pool) once they have finished being processed. Such an Aggregate Analysis Engine functions just like a “normal” non-CAS-Multiplier Analysis Engine; the fact that CAS Multiplication is occurring inside it is hidden from users of that Analysis Engine.

The AnalysisEngine interface has the following methods that allow you to interact with CAS Multiplier:

From your application, you call processAndOutputNewCASes and pass it the input CAS. An iterator is returned that allows you to step through each of the new output CASes that are produced by the Analysis Engine.

It is very important to realize that CASes are pooled objects and so your application must release each CAS (by calling the CAS.release() method) that it obtains from the CasIterator before it calls the CasIterator.next method again. Otherwise, the CAS pool will be exhausted and a deadlock will occur.

The example code in the class org.apache.uima.examples.casMultiplier. CasMultiplierExampleApplication illusrates this. Here is the main processing loop:

CasIterator casIterator = ae.processAndOutputNewCASes(initialCas);
while (casIterator.hasNext()) {
  CAS outCas = casIterator.next();

  //dump the document text and annotations for this segment
  System.out.println("********* NEW SEGMENT *********");
  System.out.println(outCas.getDocumentText());
  PrintAnnotations.printAnnotations(outCas, System.out); 

  //release the CAS (important)
  outCas.release();

Note that as defined by the CAS Multiplier contract in Section 7.1.1, “CAS Multiplier Interface Overview”, the CAS Multiplier owns the input CAS (initialCas in the example) until the last new output CAS has been produced. This means that the application should not try to make changes to initialCas until after the CasIterator.hasNext method has returned false, indicating that the segmenter has finished.

Note that the processing time of the Analysis Engine is spread out over the calls to the CasIterator's hasNext and next methods. That is, the next output CAS may not actually be produced and annotated until the application asks for it. So the application should not expect calls to the CasIterator to necessarily complete quickly.

Also, calls to the CasIterator may throw Exceptions indicating an error has occurred during processing. If an Exception is thrown, all processing of the input CAS will stop, and no more output CASes will be produced. There is currently no error recovery mechanism that will allow processing to continue after an exception.

In your application you can take the output CASes from a CAS Multiplier and pass them to the process method of other Analysis Engines. However there are some special considerations regarding the Type System of these CASes.

By default, the output CASes of a CAS Multiplier will have a Type System that contains all of the types and features declared by any component in the outermost Aggregate Analysis Engine or Collection Processing Engine that contains the CAS Multiplier. If in your application you create a CAS Multiplier and another Analysis Engine, where these are not enclosed in an aggregate, then the output CASes from the CAS Multiplier will not support any types or features that are declared in the latter Analysis Engine but not in the CAS Multiplier.

This can be remedied by forcing the CAS Multiplier and Analysis Engine to share a single UimaContext when they are created, as follows:

//create a "root" UIMA context for your whole application

UimaContextAdmin rootContext =
   UIMAFramework.newUimaContext(UIMAFramework.getLogger(),
      UIMAFramework.newDefaultResourceManager(),
      UIMAFramework.newConfigurationManager());

XMLInputSource input = new XMLInputSource("MyCasMultiplier.xml");
AnalysisEngineDescription desc = UIMAFramework.getXMLParser().
        parseAnalysisEngineDescription(input);
 
//create a UIMA Context for the new AE we are about to create

//first argument is unique key among all AEs used in the application
UimaContextAdmin childContext = rootContext.createChild(
        "myCasMultiplier", Collections.EMPTY_MAP);

//instantiate CAS Multiplier AE, passing the UIMA Context through the 
//additional parameters map

Map additionalParams = new HashMap();
additionalParams.put(Resource.PARAM_UIMA_CONTEXT, childContext);

AnalysisEngine casMultiplierAE = UIMAFramework.produceAnalysisEngine(
        desc,additionalParams);

//repeat for another AE      
XMLInputSource input2 = new XMLInputSource("MyAE.xml");
AnalysisEngineDescription desc2 = UIMAFramework.getXMLParser().
        parseAnalysisEngineDescription(input2);
 
UimaContextAdmin childContext2 = rootContext.createChild(
        "myAE", Collections.EMPTY_MAP);

Map additionalParams2 = new HashMap();
additionalParams2.put(Resource.PARAM_UIMA_CONTEXT, childContext2);

AnalysisEngine myAE = UIMAFramework.produceAnalysisEngine(
        desc2, additionalParams2);

An example CAS Multiplier that merges CASes can be found is provided in the UIMA SDK. The Java class for this example is org.apache.uima.examples.casMultiplier.SimpleTextMerger and the source code is located under the examples/src directory.

public void process(JCas aJCas) throws AnalysisEngineProcessException {
    // procure a new CAS if we don't have one already
    if (mMergedCas == null) {
      mMergedCas = getEmptyJCas();
    }

    // append document text
    String docText = aJCas.getDocumentText();
    int prevDocLen = mDocBuf.length();
    mDocBuf.append(docText);

    // copy specified annotation types
    // CasCopier takes two args: the CAS to copy from.
    //                           the CAS to copy into.
    CasCopier copier = new CasCopier(aJCas.getCas(), mMergedCas.getCas());
    
    // needed in case one annotation is in two indexes (could    
    // happen if specified annotation types overlap)
    Set copiedIndexedFs = new HashSet(); 
    for (int i = 0; i < mAnnotationTypesToCopy.length; i++) {
      Type type = mMergedCas.getTypeSystem()
          .getType(mAnnotationTypesToCopy[i]);
      FSIndex index = aJCas.getCas().getAnnotationIndex(type);
      Iterator iter = index.iterator();
      while (iter.hasNext()) {
        FeatureStructure fs = (FeatureStructure) iter.next();
        if (!copiedIndexedFs.contains(fs)) {
          Annotation copyOfFs = (Annotation) copier.copyFs(fs);
          // update begin and end
          copyOfFs.setBegin(copyOfFs.getBegin() + prevDocLen);
          copyOfFs.setEnd(copyOfFs.getEnd() + prevDocLen);
          mMergedCas.addFsToIndexes(copyOfFs);
          copiedIndexedFs.add(fs);
        }
      }
    }

// get the SourceDocumentInformation FS, 
// which indicates the sourceURI of the document
// and whether the incoming CAS is the last segment
FSIterator it = aJCas
        .getAnnotationIndex(SourceDocumentInformation.type).iterator();
if (!it.hasNext()) {
  throw new RuntimeException("Missing SourceDocumentInformation");
}
SourceDocumentInformation sourceDocInfo = 
      (SourceDocumentInformation) it.next();
if (sourceDocInfo.getLastSegment()) {
  // time to produce an output CAS
  // set the document text
  mMergedCas.setDocumentText(mDocBuf.toString());

  // add source document info to destination CAS
  SourceDocumentInformation destSDI = 
      new SourceDocumentInformation(mMergedCas);
  destSDI.setUri(sourceDocInfo.getUri());
  destSDI.setOffsetInSource(0);
  destSDI.setLastSegment(true);
  destSDI.addToIndexes();

  mDocBuf = new StringBuffer();
  mReadyToOutput = true;
}

public boolean hasNext() throws AnalysisEngineProcessException {
    return mReadyToOutput;
  }

  public AbstractCas next() throws AnalysisEngineProcessException {
    if (!mReadyToOutput) {
      throw new RuntimeException("No next CAS");
    }
    JCas casToReturn = mMergedCas;
    mMergedCas = null;
    mReadyToOutput = false;
    return casToReturn;
  }

An example descriptor for an Aggregate Analysis Engine that uses the SimpleTextMerger is provided in examples/descriptors/cas_multiplier/Segment_Annotate_Merge_AE.xml. This Aggregate first runs the SimpleTextSegmenter example to break a large document into segments. It then runs each segment through the example tokenizer and name recognizer annotators. Finally it runs the SimpleTextMerger to reassemble the segments back into one CAS. The Name annotations are copied to the final merged CAS but the Token annotations are not.

This example illustrates how you can break large artifacts into pieces for more efficient processing and then reassemble a single output CAS containing only the results most useful to the application. Intermediate results such as tokens, which may consume a lot of space, need not be retained over the entire input artifact.

The intermediate segments are dropped and are never output from the Aggregate Analysis Engine. This is done by configuring the Fixed Flow Controller as described in Section 7.3.2, “CAS Multipliers and Flow Control”, above.

Try running this Analysis Engine in the Document Analyzer tool with a large text file as input, to see that it outputs just one CAS per input file, and that the final CAS contains only the Name annotations.

Note that not all valid Unicode characters are valid XML characters, at least not in XML 1.0. Moreover, it is possible to create characters in Java that are not even valid Unicode characters, let alone XML characters. As UIMA character data is translated directly into XML character data on serialization, this may lead to issues. UIMA will therefore check that the character data that is being serialized is valid for the version of XML being used. If non-serializable character data is encountered during serialization, an exception is thrown and serialization fails (to avoid creating invalid XML data). UIMA does not simply replace the offending characters with some valid replacement character; the assumption being that most applications would not like to have their data modified automatically.

If you know you are going to use XML serialization, and you would like to avoid such issues on serialization, you should check any character data you create in UIMA ahead of time. Issues most often arise with the document text, as documents may originate at various sources, and may be of varying quality. So it's a particularly good idea to check the document text for characters that will cause issues for serialization.

UIMA provides a handful of functions to assist you in checking Java character data. Those methods are located in org.apache.uima.internal.util.XMLUtils.checkForNonXmlCharacters(), with several overloads. Please check the javadocs for further information.

Please note that these issues are not specific to XMI serialization, they apply to the older XCAS format in the same way.