# UIMA Setup and Configuration

Setup and Configuration

## UIMA JVM Configuration Properties

Some updates change UIMA's behavior between released versions. For example, sometimes an error check is enhanced, and this can cause something that previously incorrect but not checked, to now signal an error. Often, users will want these kinds of things to be ignored, at least for a while, to give them time to analyze and correct the issues.

To enable users to gradually address these issues, there are some global JVM properties for UIMA that can restore earlier behaviors, in some cases. These are detailed in the table below. Additionally, there are other JVM properties that can be used in checking and optimizing some performance trade-offs, such as the automatic index protection. For the most part, you don't need to assign any values to these properties, just define them. For example to disable the enhanced check that insures you don't add a subtype of AnnotationBase to the wrong View, you could disable this by adding the JVM argument `-Duima.disable_enhanced_check_wrong_add_to_index`. This would remove the enhanced checking for this, added in version 2.7.0 (the previously existing partial checking is still there, though).

## Configuring index protection

A new feature in version 2.7.0 optionally can include checking for invalid feature updates which could corrupt indexes. Because this checking can slightly slow down performance, there are global JVM properties to control it. The suggested way to operation with these is as follows.

- At the beginning, run with automatic protection enabled (the default), but turn on explicit reporting (`-Duima.report_fs_update_corrupts_index`)

- For all reported instances, examine your code to see if you can restructure to do the updates before adding the FS to the indexes. Where you cannot, surround the code doing these updates with a try / finally or block form of `protectIndexes()`, which is described in (and also is similarly available with JCas).

- After no further reports, for maximum performance, leave in the protections you may have installed in the above step, and then disable the reporting and runtime checking, using the JVM argument `-Duima.disable_auto_protect_indexes`, and removing (if present) `-Duima.report_fs_update_corrupts_index`.

One additional JVM property, `-Duima.throw_exception_when_fs_update_corrupts_index`, is intended to be used in automated build / testing configurations. It causes the framework to throw a UIMARuntimeException if an update outside of a `protectIndexes` block occurs that could corrupt the indexes, rather than "recovering" this.

## Properties Table

This table describes the various JVM defined properties; specify these on the Java command line using -Dxxxxxx, where the xxxxxx is one of the properties starting with `uima.` from the table below.

Title | Property Name & Description | Since Version
Allow duplicate addToIndexes for identical Feature Structures | `uima.allow_duplicate_add_to_indexes` (default is false) See UIMA-4135 and UIMA-3399. As of version 2.7.0, adding a particular Feature Structure to the indexes more than once is ignored. The old behavior may be restored by this property. | 2.7.0
adding Annotation to wrong View | `uima.disable_enhanced_check_wrong_add_to_index` See UIMA-4099. Feature Structures which are subtypes of AnnotationBase may only be added to the View corresponding to their Sofa reference. From version 2.7.0, there is additional checking of this which can be disabled if needed for backward compatibility. | 2.7.0
Index protection properties
Report Illegal Index-key Feature Updates | `uima.report_fs_update_corrupts_index` (default is not to report) See UIMA-4135. Updating Features which are used in Set and Sorted indexes as "keys" may corrupt the indexes, if the Feature Structure (FS) has been added to the indexes. To update these, you must first completely remove the FS from the indexes in all views, then do the updates, and then add it back. UIMA now checks for this (unless specifically disabled, see below), and if this property is set, will log WARN messages for each occurrence unless the user does explicit `protectIndexes` (see CAS JavaDocs for CAS / JCas `protectIndexes` methods), if this property is defined. To scan the logs for these reports, search for instances of lines having the string `While FS was in the index, the feature` Specifying this property overrides `uima.disable_auto_protect_indexes`. Users would run with this property defined, and then for high performance, would use the report to manually change their code to avoid the problem or to wrap the updates with a `protectIndexes` kind of protection (see the reference manual, in the CAS or JCas chapters, for examples of user code doing this, and then run with the protection turned off (see below). | 2.7.0
Throw exception on illegal Index-key Feature Updates | `uima.exception_when_fs_update_corrupts_index` (default is false) See UIMA-4150. Throws a UIMARuntimeException if an Indexed FS feature used as a key in one or more indexes is updated, outside of an explicit `protectIndexes` block.. \ This is intended for use in automated build and test environments, to provide a strong signal if this kind of mistake gets into the build. If it is not set, then the other properties specify if corruption should be checked for, recovered automatically, and / or reported Specifying this property also forces `uima.report_fs_update_corrupts_index` to true even if it was set to false. | 2.7.0
Disable the index corruption checking | `uima.disable_auto_protect_indexes` See UIMA-4135. After you have fixed all reported issues identified with the above report, you may set this property to omit this check, which may slightly improve performance. Note that this property is ignored if the `-Dexception_when_fs_update_corrupts_index` or `-Dreport_fs_update_corrupts_index` | 2.7.0
Measurement / Tracing properties
Trace Feature Structure Creation/Updating | `uima.trace_fs_creation_and_updating` This causes a trace file to be produced in the current working directory. The file has one line for each Feature Structure that is created, and include information on the cas/cas-view, and the features that are set for the Feature Structure. There is, additionally, one line for each Feature Structure update. Updates that occur next-to trace information for the same Feature Structure are combined. This can generate a lot of output, and definately slows down execution. | 2.10.1