uima-docbook-references/src/docbook/ref.config.xml - uima-uimaj - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
 <!ENTITY imgroot "images/references/ref.config/">
 <!ENTITY tp "ugr.ref.config.">
 <!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >
 %uimaents;
 ]>
 <!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
 -->
 <chapter id="ugr.ref.config">
   <title>UIMA Setup and Configuration</title>
   <titleabbrev>Setup and Configuration</titleabbrev>

   <section id="ugr.ref.config.properties">
     <title>UIMA JVM Configuration Properties</title>

     <para> 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.
     </para>

     <para>
       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 <code>-Duima.disable_enhanced_check_wrong_add_to_index</code>.
   This would remove the enhanced
   checking for this, added in version 2.7.0 (the previously existing partial checking is
   still there, though).
     </para>
   </section>

   <section id="ugr.ref.config.protect-index">
     <title>Configuring index protection</title>

     <para>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.
     <itemizedlist>
 	    <listitem><para>At the beginning, run with automatic protection enabled (the default), but
 	    turn on explicit reporting (<code>-Duima.report_fs_update_corrupts_index</code>)</para></listitem>
 	    <listitem><para>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 <code>protectIndexes()</code>,
 	    which is described in
 	     <xref linkend="ugr.ref.cas.updating_indexed_feature_structures"/> (and also is similarly available with JCas).
 	    </para></listitem>
 	    <listitem><para>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
 	    <code>-Duima.disable_auto_protect_indexes</code>, and removing (if present)
 	    <code>-Duima.report_fs_update_corrupts_index</code>.</para></listitem>
     </itemizedlist>
     One additional JVM property, <code>-Duima.throw_exception_when_fs_update_corrupts_index</code>,
     is intended to be used in automated build / testing configurations.  It causes the framework to throw
     a UIMARuntimeException if an update outside of a <code>protectIndexes</code> block occurs
     that could corrupt the indexes,
     rather than "recovering" this.
     </para>
   </section>

   <section id="ugr.ref.config.property-table">
     <title>Properties Table</title>

     <para>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 <code>uima.</code> from the table below.</para>
     <informaltable frame="all" rowsep="1" colsep="1">
      <tgroup cols="3">
        <colspec colnum="1" colname="Title" colwidth="1*"/>
        <colspec colnum="2" colname="Description" colwidth="3*"/>
        <colspec colnum="3" colname="Version"  colwidth= "0.5*"/>

        <spanspec spanname="fullwidth" namest="Title" nameend="Version" align="center"/>

        <tbody>
          <row>
            <entry><emphasis role="bold">Title</emphasis></entry>
            <entry><emphasis role="bold">Property Name &amp; Description</emphasis></entry>
            <entry><emphasis role="bold">Since Version</emphasis></entry>
          </row>

          <!-- ******************************************************************************* -->
          <row>
            <entry><para>Allow duplicate addToIndexes for identical Feature Structures</para></entry>

            <entry><para><code>uima.allow_duplicate_add_to_indexes</code> (default is false)</para>

                   <para>See <ulink url="https://issues.apache.org/jira/browse/UIMA-4135">UIMA-4135</ulink>
                         and <ulink url="https://issues.apache.org/jira/browse/UIMA-3399">UIMA-3399</ulink>.
                         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.</para></entry>
            <entry><para>2.7.0</para></entry>
          </row>

          <!-- ******************************************************************************* -->
          <row>
            <entry><para>adding Annotation to wrong View</para></entry>

            <entry><para><code>uima.disable_enhanced_check_wrong_add_to_index</code></para>

                   <para>See <ulink url="https://issues.apache.org/jira/browse/UIMA-4099">UIMA-4099</ulink>.
                         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.</para></entry>
            <entry><para>2.7.0</para></entry>
          </row>

          <row>
            <entry spanname="fullwidth"><emphasis role="bold">Index protection properties</emphasis></entry>
          </row>
          <!-- ******************************************************************************* -->
          <row>
            <entry><para>Report Illegal Index-key Feature Updates</para></entry>

            <entry><para><code>uima.report_fs_update_corrupts_index</code> (default is not to report)</para>

                   <para>See <ulink url="https://issues.apache.org/jira/browse/UIMA-4135">UIMA-4135</ulink>.
                         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 <code>protectIndexes</code> (see CAS JavaDocs for CAS / JCas <code>protectIndexes</code> methods), if this
                         property is defined.</para>
                    <para>To scan the logs for these reports, search for instances of lines having the string
                          <code>While FS was in the index, the feature</code></para>

                    <para>Specifying this property overrides <code>uima.disable_auto_protect_indexes</code>.</para>

                    <para>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 <code>protectIndexes</code> 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).

                         </para></entry>

            <entry><para>2.7.0</para></entry>
          </row>

          <!-- ******************************************************************************* -->
          <row>
            <entry><para>Throw exception on illegal Index-key Feature Updates</para></entry>

            <entry><para><code>uima.exception_when_fs_update_corrupts_index</code> (default is false)</para>

                   <para>See <ulink url="https://issues.apache.org/jira/browse/UIMA-4150">UIMA-4150</ulink>.
                         Throws a UIMARuntimeException if an Indexed FS feature used as a key in one or more
                         indexes is updated, outside of an explicit <code>protectIndexes</code> 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</para>

                    <para>Specifying this property also forces <code>uima.report_fs_update_corrupts_index</code>
                          to true even if it was set to false.</para>

                    </entry>

            <entry><para>2.7.0</para></entry>
          </row>

          <!-- ******************************************************************************* -->
          <row>
            <entry><para>Disable the index corruption checking</para></entry>

            <entry><para><code>uima.disable_auto_protect_indexes</code></para>

                   <para>See <ulink url="https://issues.apache.org/jira/browse/UIMA-4135">UIMA-4135</ulink>.
                         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.</para>
                   <para>Note that this property is ignored if the <code>-Dexception_when_fs_update_corrupts_index</code>
                   or <code>-Dreport_fs_update_corrupts_index</code></para>
            </entry>

            <entry><para>2.7.0</para></entry>
          </row>

          <row>
            <entry spanname="fullwidth"><emphasis role="bold">Measurement / Tracing properties</emphasis></entry>
          </row>
          <!-- ******************************************************************************* -->

          <row>
            <entry><para>Trace Feature Structure Creation/Updating</para></entry>

            <entry><para><code>uima.trace_fs_creation_and_updating</code></para>
                   <para>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.
                   </para>

                   <para>This can generate a lot of output, and definitely slows down execution.</para>
             </entry>

             <entry><para>2.10.1</para></entry>
          </row>
          <!--   DISABLED FOR NOW
          <row>
            <entry><para>Measure index flattening optimization</para></entry>

            <entry><para><code>uima.measure.flatten_index</code></para>

                   <para>See <ulink url="https://issues.apache.org/jira/browse/UIMA-4357">UIMA-4357</ulink>.
                         This creates a short report to System.out when Java is shutdown.
                         The report has some statistics about the automatic management of
                         flattened index creation and use.</para>
            </entry>

            <entry><para>2.8.0</para></entry>
          </row>
           -->

        </tbody>
      </tgroup>
    </informaltable>

   </section>

 </chapter>
	<?xml version="1.0" encoding="UTF-8"?>
	<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
	"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
	<!ENTITY imgroot "images/references/ref.config/">
	<!ENTITY tp "ugr.ref.config.">
	<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >
	%uimaents;
	]>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->
	<chapter id="ugr.ref.config">
	<title>UIMA Setup and Configuration</title>
	<titleabbrev>Setup and Configuration</titleabbrev>

	<section id="ugr.ref.config.properties">
	<title>UIMA JVM Configuration Properties</title>

	<para> 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.
	</para>

	<para>
	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 <code>-Duima.disable_enhanced_check_wrong_add_to_index</code>.
	This would remove the enhanced
	checking for this, added in version 2.7.0 (the previously existing partial checking is
	still there, though).
	</para>
	</section>

	<section id="ugr.ref.config.protect-index">
	<title>Configuring index protection</title>

	<para>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.
	<itemizedlist>
	<listitem><para>At the beginning, run with automatic protection enabled (the default), but
	turn on explicit reporting (<code>-Duima.report_fs_update_corrupts_index</code>)</para></listitem>
	<listitem><para>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 <code>protectIndexes()</code>,
	which is described in
	<xref linkend="ugr.ref.cas.updating_indexed_feature_structures"/> (and also is similarly available with JCas).
	</para></listitem>
	<listitem><para>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
	<code>-Duima.disable_auto_protect_indexes</code>, and removing (if present)
	<code>-Duima.report_fs_update_corrupts_index</code>.</para></listitem>
	</itemizedlist>
	One additional JVM property, <code>-Duima.throw_exception_when_fs_update_corrupts_index</code>,
	is intended to be used in automated build / testing configurations. It causes the framework to throw
	a UIMARuntimeException if an update outside of a <code>protectIndexes</code> block occurs
	that could corrupt the indexes,
	rather than "recovering" this.
	</para>
	</section>

	<section id="ugr.ref.config.property-table">
	<title>Properties Table</title>

	<para>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 <code>uima.</code> from the table below.</para>
	<informaltable frame="all" rowsep="1" colsep="1">
	<tgroup cols="3">
	<colspec colnum="1" colname="Title" colwidth="1*"/>
	<colspec colnum="2" colname="Description" colwidth="3*"/>
	<colspec colnum="3" colname="Version" colwidth= "0.5*"/>

	<spanspec spanname="fullwidth" namest="Title" nameend="Version" align="center"/>

	<tbody>
	<row>
	<entry><emphasis role="bold">Title</emphasis></entry>
	<entry><emphasis role="bold">Property Name & Description</emphasis></entry>
	<entry><emphasis role="bold">Since Version</emphasis></entry>
	</row>

	<!-- ******************************************************************************* -->
	<row>
	<entry><para>Allow duplicate addToIndexes for identical Feature Structures</para></entry>

	<entry><para><code>uima.allow_duplicate_add_to_indexes</code> (default is false)</para>

	<para>See <ulink url="https://issues.apache.org/jira/browse/UIMA-4135">UIMA-4135</ulink>
	and <ulink url="https://issues.apache.org/jira/browse/UIMA-3399">UIMA-3399</ulink>.
	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.</para></entry>
	<entry><para>2.7.0</para></entry>
	</row>

	<!-- ******************************************************************************* -->
	<row>
	<entry><para>adding Annotation to wrong View</para></entry>

	<entry><para><code>uima.disable_enhanced_check_wrong_add_to_index</code></para>

	<para>See <ulink url="https://issues.apache.org/jira/browse/UIMA-4099">UIMA-4099</ulink>.
	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.</para></entry>
	<entry><para>2.7.0</para></entry>
	</row>

	<row>
	<entry spanname="fullwidth"><emphasis role="bold">Index protection properties</emphasis></entry>
	</row>
	<!-- ******************************************************************************* -->
	<row>
	<entry><para>Report Illegal Index-key Feature Updates</para></entry>

	<entry><para><code>uima.report_fs_update_corrupts_index</code> (default is not to report)</para>

	<para>See <ulink url="https://issues.apache.org/jira/browse/UIMA-4135">UIMA-4135</ulink>.
	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 <code>protectIndexes</code> (see CAS JavaDocs for CAS / JCas <code>protectIndexes</code> methods), if this
	property is defined.</para>
	<para>To scan the logs for these reports, search for instances of lines having the string
	<code>While FS was in the index, the feature</code></para>

	<para>Specifying this property overrides <code>uima.disable_auto_protect_indexes</code>.</para>

	<para>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 <code>protectIndexes</code> 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).

	</para></entry>

	<entry><para>2.7.0</para></entry>
	</row>

	<!-- ******************************************************************************* -->
	<row>
	<entry><para>Throw exception on illegal Index-key Feature Updates</para></entry>

	<entry><para><code>uima.exception_when_fs_update_corrupts_index</code> (default is false)</para>

	<para>See <ulink url="https://issues.apache.org/jira/browse/UIMA-4150">UIMA-4150</ulink>.
	Throws a UIMARuntimeException if an Indexed FS feature used as a key in one or more
	indexes is updated, outside of an explicit <code>protectIndexes</code> 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</para>

	<para>Specifying this property also forces <code>uima.report_fs_update_corrupts_index</code>
	to true even if it was set to false.</para>

	</entry>

	<entry><para>2.7.0</para></entry>
	</row>

	<!-- ******************************************************************************* -->
	<row>
	<entry><para>Disable the index corruption checking</para></entry>

	<entry><para><code>uima.disable_auto_protect_indexes</code></para>

	<para>See <ulink url="https://issues.apache.org/jira/browse/UIMA-4135">UIMA-4135</ulink>.
	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.</para>
	<para>Note that this property is ignored if the <code>-Dexception_when_fs_update_corrupts_index</code>
	or <code>-Dreport_fs_update_corrupts_index</code></para>
	</entry>

	<entry><para>2.7.0</para></entry>
	</row>

	<row>
	<entry spanname="fullwidth"><emphasis role="bold">Measurement / Tracing properties</emphasis></entry>
	</row>
	<!-- ******************************************************************************* -->

	<row>
	<entry><para>Trace Feature Structure Creation/Updating</para></entry>

	<entry><para><code>uima.trace_fs_creation_and_updating</code></para>
	<para>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.
	</para>

	<para>This can generate a lot of output, and definitely slows down execution.</para>
	</entry>

	<entry><para>2.10.1</para></entry>
	</row>
	<!-- DISABLED FOR NOW
	<row>
	<entry><para>Measure index flattening optimization</para></entry>

	<entry><para><code>uima.measure.flatten_index</code></para>

	<para>See <ulink url="https://issues.apache.org/jira/browse/UIMA-4357">UIMA-4357</ulink>.
	This creates a short report to System.out when Java is shutdown.
	The report has some statistics about the automatic management of
	flattened index creation and use.</para>
	</entry>

	<entry><para>2.8.0</para></entry>
	</row>
	-->

	</tbody>
	</tgroup>
	</informaltable>

	</section>

	</chapter>