You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by sc...@apache.org on 2017/01/13 23:09:20 UTC
svn commit: r1778690 - in
/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook:
uv3.migration.aids.xml uv3.migration.xml uv3.new_extended_apis.xml
uv3.performance.xml version_3_users_guide.xml
Author: schor
Date: Fri Jan 13 23:09:20 2017
New Revision: 1778690
URL: http://svn.apache.org/viewvc?rev=1778690&view=rev
Log:
[UIMA-5137] add migration aids docs, misc updates.
Added:
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.aids.xml
Modified:
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.xml
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.new_extended_apis.xml
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.performance.xml
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/version_3_users_guide.xml
Added: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.aids.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.aids.xml?rev=1778690&view=auto
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.aids.xml (added)
+++ uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.aids.xml Fri Jan 13 23:09:20 2017
@@ -0,0 +1,116 @@
+<?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/uv3.migration.aids/">
+<!ENTITY tp "uv3.migration.aids.">
+<!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="uv3.migration.aids">
+ <title>Migration aids</title>
+
+ <para>To aid migration, some features of UIMA V3 which might cause migration difficulties
+ can be disabled. Users may initially want to disable these, and get their pipelines working,
+ and then over time, re-enable these while fixing any issues that may come up, one feature
+ at a time.
+ </para>
+
+ <para>
+ Global JVM properties for UIMA V3 that control these are described in the table below.
+ </para>
+
+ <section id="uv3.migration.aids.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*"/>
+
+ <spanspec spanname="fullwidth" namest="Title" nameend="Description" align="center"/>
+
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">Title</emphasis></entry>
+ <entry><emphasis role="bold">Property Name & Description</emphasis></entry>
+ </row>
+
+ <!-- ******************************************************************************* -->
+ <row>
+ <entry><para>Disable Type System consolidation</para></entry>
+
+ <entry><para>uima.disable_typesystem_consolidation</para>
+
+ <para>Default: equal Type Systems are consolidated.</para>
+ <para>When type systems are committed, the resulting Type System (Java object)
+ is considered read-only, and is compared to already existing Type Systems.
+ Existing type systems, if found, are reused. Besides saving storage, this can
+ sometimes improve locality of reference, and therefore, performance.
+ Setting this property disables this consolidation.</para></entry>
+ </row>
+
+ <!-- ******************************************************************************* -->
+ <row>
+ <entry><para>Enable finding all Feature Structures by their int ID</para></entry>
+
+ <entry><para>uima.enable_id_to_feature_structure_map_for_all_fss</para>
+
+ <para>Default: normally created Feature Structures are not kept in a map.</para>
+ <para>In version 3, normally, Feature Structures are not added to the
+ map used by the Low Level CAS API to map from int ids to Feature Structures.
+ This has the benefit that no longer referenced Feature Structures may be
+ garbaged collected. This behavior may be overridden by this property.</para></entry>
+ </row>
+
+ <!-- ******************************************************************************* -->
+ <row>
+ <entry spanname="fullwidth"><emphasis role="bold">Trading off runtime checks for speed</emphasis></entry>
+ </row>
+
+ <row>
+ <entry><para>Disabling runtime feature validation</para></entry>
+
+ <entry><para>uima.uima.disable_runtime_feature_validation</para>
+
+ <para>Once code is running correctly, you may remove this check for performance
+ reasons by setting this property.</para></entry>
+ </row>
+
+ <row>
+ <entry><para>Disabling runtime feature <emphasis>value</emphasis> validation</para></entry>
+
+ <entry><para>uima.disable_runtime_feature_value_validation</para>
+
+ <para>Default: features being set into FS features which are FSs are checked for proper type subsumption.</para>
+ <para>Once code is running correctly, you may remove this check for performance
+ reasons by setting this property.</para></entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ </section>
+
+</chapter>
\ No newline at end of file
Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.xml?rev=1778690&r1=1778689&r2=1778690&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.xml (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.xml Fri Jan 13 23:09:20 2017
@@ -28,7 +28,14 @@ under the License.
<titleabbrev>Migrating JCas</titleabbrev>
<para>To migrate a UIMA application / pipeline to version 3, you need to replace the Version 2 JCas
- classes with version 3 classes. This is best done by running the migration tool, which is available
+ classes with version 3 classes.
+ </para>
+ <para>Some projects are built using Maven, and use the JCasGen Maven plugin as part of the build.
+ These builds, when switched to depend on version 3, will automatically generate the new JCas
+ class definitions, so nothing special need be done.
+ </para>
+
+ <para>If you have customized JCasGen classes, these can be migrated by running the migration tool, which is available
as a stand-alone command line tool (<code>runV3migrateJCas.sh or ...bat</code>), or
as an Eclipse launch configuration.</para>
Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.new_extended_apis.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.new_extended_apis.xml?rev=1778690&r1=1778689&r2=1778690&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.new_extended_apis.xml (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.new_extended_apis.xml Fri Jan 13 23:09:20 2017
@@ -90,6 +90,16 @@ public final static String _FeatName_sof
some index as a key, is automatically (under the covers) temporarily removing the Feature Structure from indexes,
doing the modification, and then adding it back.
</para>
+
+ <para>Similarly to version 2, iterator methods <code>moveToFirst, moveToLast, and moveTo(a_positioning_Feature_Structure)</code>
+ "reset" the iterator to be able to "see" the current state of the indexes. This corresponds to resetting the
+ concurrent modification detection sensing in version 2, when these methods are used.
+ </para>
+
+ <para>Note that the phrase <emphasis>Concurrent Modification</emphasis> is being used here in a single threading
+ context, to mean that within a single thread, while an iterator is active, some modifications are being done
+ to the indexes. UIMA does not support multi-threaded write access to the CAS; it does support multi-threaded
+ read access to a set of CAS Views, concurrent with one thread having write access (to different views).</para>
</section>
<section id="uv3.new_extended_apis.select">
Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.performance.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.performance.xml?rev=1778690&r1=1778689&r2=1778690&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.performance.xml (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.performance.xml Fri Jan 13 23:09:20 2017
@@ -35,6 +35,11 @@ under the License.
<para>A focus of the implementation has been to try to achieve much more locality of reference, including
the code itself. For example, many parts of the implementation were rewritten to eliminate duplicate
code. Many more objects were shared where feasible, with attention paid to multi-threading aspects.</para>
+
+ <para>This improvement reduces the memory cache "load" that the framework imposes, potentially permitting
+ more of the space to be used for other things, including user code.</para>
+
+ <para>The framework's use of Java 8 facilities such as method handles and lambdas may also result in some performance gains.</para>
</section>
<section id="uv3.performance.indexes">
@@ -58,12 +63,17 @@ under the License.
</listitem>
</itemizedlist>
</para>
+
</section>
-
+
<section id="uv3.performance.low_level_api">
<title>Low Level API performance</title>
- <para>
+ <para>Low level APIs in v2 have a slight performance advantage; in v3, they have a performance penalty. Furthermore,
+ low level Feature Structure creation and calling <code>my_feature_structure.getAddress()</code> both return an
+ <code>int</code> "handle" which can be used to retrieve the corresponding Feature Structure. To make this work,
+ these operations must update a map between <code>ints</code> and the Feature Structure object. This prevents
+ no-longer-used feature structures from being garbage collected (until the CAS is reset).
</para>
</section>
Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/version_3_users_guide.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/version_3_users_guide.xml?rev=1778690&r1=1778689&r2=1778690&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/version_3_users_guide.xml (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/version_3_users_guide.xml Fri Jan 13 23:09:20 2017
@@ -32,6 +32,7 @@ under the License.
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="uv3.custom_java_objects.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="uv3.migration.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="uv3.pears.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="uv3.migration.aids.xml"/>
<!-- xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="uv3.performance.xml"/-->
</book>