UIMA Overview & SDK Setup

All of the UIMA Java package names have changed in Apache UIMA. They now start with org.apache rather than com.ibm. There have been other changes as well. The package name segment reference_impl has been shortened to impl, and some segments have been reordered. For example com.ibm.uima.reference_impl.analysis_engine has become org.apache.uima.analysis_engine.impl. Tools are now consolidated under org.apache.uima.tools and service adapters under org.apache.uima.adapter.

The migration utility will replace all occurrences of IBM UIMA package names with their Apache UIMA equivalents. It will not replace prefixes of package names, so if your code uses a package called com.ibm.uima.myproject (although that is not recommended), it will not be replaced.

The XML namespace in UIMA component descriptors has changed from http://uima.watson.ibm.com/resourceSpecifier to http://uima.apache.org/resourceSpecifier. The value of the <frameworkImplementation> must now be org.apache.uima.java or org.apache.uima.cpp. The migration script will apply these replacements.

In Apache UIMA the TCAS interface has been removed. All uses of it must now be replaced by the CAS interface. (All methods that used to be defined on TCAS were moved to CAS in v2.0.) The method CAS.getTCAS() is replaced with CAS.getCurrentView() and CAS.getTCAS(String) is replaced with CAS.getView(String) . The following have also been removed and replaced with the equivalent "CAS" variants: TCASException, TCASRuntimeException, TCasPool, and CasCreationUtils.createTCas(...).

The migration script will apply the necessary replacements.

In previous versions, user code accessed the JCas class directly. In Apache UIMA there is now an interface, org.apache.uima.jcas.JCas, which all JCas-based user code must now use. Static methods that were previously on the JCas class (and called from JCas cover classes generated by JCasGen) have been moved to the new org.apache.uima.jcas.JCasRegistry class. The migration script will apply the necessary replacements to your code, including any JCas cover classes that are part of your codebase.

The UIMA JAR file names have changed slightly. Underscores have been replaced with hyphens to be consistent with Apache naming conventions. For example uima_core.jar is now uima-core.jar. Also uima_jcas_builtin_types.jar has been renamed to uima-document-annotation.jar. Finally, the jVinci.jar file is now in the lib directory rather than the lib/vinci directory as was previously the case. The migration script will apply the necessary replacements, for example to script files or Eclipse launch configurations. (See Section 1.4.1, “Running the Migration Utility” for a list of file extensions that the migration utility will process by default.)

The versions of the UIMA SDK prior to the move into Apache came with a semantic search engine. The Apache version does not include this search engine. The search engine has been repackaged and is separately available from http://www.alphaworks.ibm.com/tech/uima. The intent is to hook up (over time) with other open source search engines, such as the Lucene search engine project in Apache.

New Primitive data types. UIMA now supports Boolean (bit), Byte, Short (16 bit integers), Long (64 bit integers), and Double (64 bit floating point) primitive types, and arrays of these. These types can be used like all the other primitive types.

Simpler Analysis Engines and CASes. Version 1.x made a distinction between Analysis Engines and Text Analysis Engines. This distinction has been eliminated in Version 2 - new code should just refer to Analysis Engines. Analysis Engines can operate on multiple kinds of artifacts, including text.

Sofas and CAS Views simplified. The APIs for manipulating multiple subjects of analysis (Sofas) and their corresponding CAS Views have been simplified.

Analysis Component generalized to support multiple new CAS outputs. Analysis Components, in general, can make use of new capabilities to return multiple new CASes, in addition to returning the original CAS that is passed in. This allows components to have Collection Reader-like capabilities, but be placed anywhere in the flow. See Chapter 7, CAS Multiplier Developer's Guide in UIMA Tutorial and Developers' Guides .

User-customized Flow Controllers. A new component, the Flow Controller, can be supplied by the user to implement arbitrary flow control for CASes within an Aggregate. This is in addition to the two built-in flow control choices of linear and language-capability flow. See Chapter 4, Flow Controller Developer's Guide in UIMA Tutorial and Developers' Guides .

New additional Annotator API ImplBase.  As of version 2.1, UIMA has a new set of Annotator interfaces. Annotators should now extend CasAnnotator_ImplBase or JCasAnnotator_ImplBase instead of the v1.x TextAnnotator_ImplBase and JTextAnnotator_ImplBase. The v1.x annotator interfaces are unchanged and are still supported for backwards compatibility.

The new Annotator interfaces support the changed approaches for ResultSpecifications and the changed exception names (see below), and have all the methods that CAS Consumers have, including CollectionProcessComplete and BatchProcessComplete.

UIMA Exceptions rationalized. In version 1 there were different exceptions for the methods of an AnalysisEngine and for the corresponding methods of an Annotator; these were merged in version 2.

The previous exceptions are still available, but new code should use the new exceptions.

Changes in Result Specifications. In version 1, the process(...) method took a second argument, a ResultSpecification. Now it is set when changed and it's up to the annotator to store it in a local field and make it available when needed. This approach lets the annotator receive a specific signal (a method call) when the Result Specification changes. Previously, it would need to check on every call to see if it changed. The default impl base classes provide set/getResultSpecification(...) methods for this

Only one Capability Set. In version one, you can define multiple capability sets. These were not supported well, and for version two, this is now simplified - you should only use one capability set. (For backwards compatibility, if you use more, this won't cause a problem for now).

TextAnalysisEngine deprecated; use AnalysisEngine instead. TextAnalysisEngine has been deprecated - it is now no different than AnalysisEngine. Previous code that uses this should still continue to work, however.

Annotator Context deprecated; use UimaContext instead. The context for the Annotator is the same as the overall UIMA context. The impl base classes provide a getContext() method which returns now the UimaContext object.

DocumentAnalyzer tool uses XMI formats. The DocumentAnalyzer tool saves outputs in the new XMI serialization format. The AnnotationViewer and SemanticSearchGUI tools can read both the new XMI format and the previous XCAS format.

CAS Initializer deprecated. Example code that used CAS Initializers has been rewritten to not use this.

Other than the changes from IBM UIMA to Apache UIMA described above, most UIMA 1.x applications should not require additional changes to upgrade to UIMA 2.x. However, there are a few exceptions that UIMA 1.x users may need to be aware of:

If you have run JCasGen it is likely that you have the classes com.ibm.uima.jcas.tcas.DocumentAnnotation and com.ibm.uima.jcas.tcas.DocumentAnnotation_Type as part of your code. This package name is no longer valid, and the migration utility does not move your files between directories so it is unable to fix this.

If you have not made manual modifications to these classes, the best solution is usually to just delete these two classes (and their containing package). There is a default version in the uima-document-annotation.jar file that is included in Apache UIMA. If you have made custom changes, then you should not delete the file but instead move it to the correct package org.apache.uima.jcas.tcas. For more information about JCas and DocumentAnnotation please see Section 5.5.4, “Adding Features to DocumentAnnotation” in UIMA References

The deprecated method JCas.getDocumentAnnotation has been removed. Its use must be replaced with JCas.getDocumentAnnotationFs. The method JCas.getDocumentAnnotationFs() returns type TOP, so your code must cast this to type DocumentAnnotation. The reasons for this are described in Section 5.5.4, “Adding Features to DocumentAnnotation” in UIMA References.

The use of <xi:include> in UIMA component descriptors has been discouraged for some time, and in Apache UIMA support for it has been removed. If you have descriptors that use that, you must change them to use UIMA's <import> syntax instead. The proper syntax is described in Section 2.2, “Imports” in UIMA References.

Because TCAS has been replaced by CAS, if you had two methods distinguished only by whether an argument type was TCAS or CAS, the migration tool will cause these to have identical signatures, which will be a compile error. If this happens, consider why the two variants were needed in the first place. Often, it may work to simply delete one of the methods.

Previous UIMA versions has some methods in the com.ibm.uima.util package that were for internal use and were not documented in the Javadoc. (There are also many methods in that package which are documented, and there is no issue with using these.) It is not recommended that you use any of the undocumented methods. If you do, the migration script will not handle them correctly. These have now been moved to org.apache.uima.internal.util, and you will have to manually update your imports to point to this location.

If you have placed your own classes in a package that has exactly the same name as one of the UIMA packages (not recommended), this will cause problems when your run the migration script. Since the script replaces UIMA package names, all of your imports that refer to your class will get replaced and your code will no longer compile. If this happens, you can fix it by manually moving your code to the new Apache UIMA package name (i.e., whatever name your imports got replaced with). However, we recommend instead that you do not use Apache UIMA package names for your own code.

An even more rare case would be if you had a package name that started with a capital letter (poor Java style) AND was prefixed by one of the UIMA package names, for example a package named com.ibm.uima.MyPackage. This would be treated as a class name and replaced with org.apache.uima.MyPackage wherever it occurs.

This change may affect user code to a small extent, as some of the APIs on CASException and CASRuntimeException no longer exist. On the up side, all UIMA exceptions are now derived from the same base classes and behave the same way. The most significant change is that you can no longer check for the specific type of exception the way you used to. For example, if you had code like this:

catch (CASRuntimeException e) {
  if (e.getError() == CASRuntimeException.ILLEGAL_ARRAY_SIZE) {
  // Do something in case this particular error is caught

you will need to replace it with the following:

catch (CASRuntimeException e) {
  if (e.getMessageKey().equals(CASRuntimeException.ILLEGAL_ARRAY_SIZE)) {
  // Do something in case this particular error is caught

as the message keys are now strings. This change is not handled by the migration script.

A general and common type used in artifact analysis and from which additional types are often derived is the annotation type.

The annotation type is used to annotate or label regions of an artifact. Common artifacts are text documents, but they can be other things, such as audio streams. The annotation type for text includes two features, namely begin and end. Values of these features represent integer offsets in the artifact and delimit a span. Any particular annotation object identifies the span it annotates with the begin and end features.

The key idea here is that the annotation type is used to identify and label or “annotate” a specific region of an artifact.

Consider that the Person type is defined as a subtype of annotation. An annotator, for example, can create a Person annotation to record the discovery of a mention of a person between position 141 and 143 in document D102. The annotator can create another person annotation to record the detection of a mention of a person in the span between positions 101 and 112.

While the annotation type is a useful type for annotating regions of a document, annotations are not the only kind of types in a CAS. A CAS is a general representation scheme and may store arbitrary data structures to represent the analysis of documents.

As an example, consider statement 3 above (repeated here for your convenience).

(3) The Person denoted by span 101 to 112 and 
  the Person denoted by span 141 to 143 in document D102 
  refer to the same Entity.

This statement mentions two person annotations in the CAS; the first, call it P1 delimiting the span from 101 to 112 and the other, call it P2, delimiting the span from 141 to 143. Statement 3 asserts explicitly that these two spans refer to the same entity. This means that while there are two expressions in the text represented by the annotations P1 and P2, each refers to one and the same person.

The Entity type may be introduced into a type system to capture this kind of information. The Entity type is not an annotation. It is intended to represent an object in the domain which may be referred to by different expressions (or mentions) occurring multiple times within a document (or across documents within a collection of documents). The Entity type has a feature named occurrences. This feature is used to point to all the annotations believed to label mentions of the same entity.

Consider that the spans annotated by P1 and P2 were “Fred Center” and “He” respectively. The annotator might create a new Entity object called FredCenter. To represent the relationship in statement 3 above, the annotator may link FredCenter to both P1 and P2 by making them values of its occurrences feature.

Figure 2.2, “Objects represented in the Common Analysis Structure (CAS)” also illustrates that an entity may be linked to annotations referring to regions of image documents as well. To do this the annotation type would have to be extended with the appropriate features to point to regions of an image.

UIMA supports the simultaneous analysis of multiple views of a document. This support comes in handy for processing multiple forms of the artifact, for example, the audio and the closed captioned views of a single speech stream, or the tagged and detagged views of an HTML document.

AEs analyze one or more views of a document. Each view contains a specific subject of analysis(Sofa), plus a set of indexes holding metadata indexed by that view. The CAS, overall, holds one or more CAS Views, plus the descriptive objects that represent the analysis results for each.

Another common example of using CAS Views is for different translations of a document. Each translation may be represented with a different CAS View. Each translation may be described by a different set of analysis results. For more details on CAS Views and Sofas see Chapter 6, Multiple CAS Views of an Artifact in UIMA Tutorial and Developers' Guides and Chapter 5, Annotations, Artifacts, and Sofas in UIMA Tutorial and Developers' Guides.