svn commit: r689984 - in /incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references: ref.cas.xml ref.jcas.xml

[sc...@apache.org]

Author: schor
Date: Thu Aug 28 14:08:43 2008
New Revision: 689984

URL: http://svn.apache.org/viewvc?rev=689984&view=rev
Log:
no Jira - some clarification and typo fixes (missing word) for JCas usage.

Modified:
    incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.cas.xml
    incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.jcas.xml

Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.cas.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.cas.xml?rev=689984&r1=689983&r2=689984&view=diff
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.cas.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.cas.xml Thu Aug 28 14:08:43 2008
@@ -39,8 +39,9 @@
   <para>Use of the CAS as described here is also recommended (or necessary) when components add
   to the definitions of types of other components.  This UIMA feature allows users to add features
   to a type that was already defined elsewhere.  When this feature is used in conjunction with the
-  JCas, it reliably leads problems with class loading.  This is because different JCas representations
-  of a single type are generated by the different components, and only one of them is loaded.  Note:
+  JCas, it can lead to problems with class loading.  This is because different JCas representations
+  of a single type are generated by the different components, and only one of them is loaded 
+  (unless you are using Pear descriptors).  Note:
   we do not recommend that you add features to pre-existing types.  A type should be defined in one
   place only, and then there is no problem with using the JCas.  However, if you do use this feature,
   do not use the JCas.  Similarly, if you distribute your components for inclusion in somebody else's

Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.jcas.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.jcas.xml?rev=689984&r1=689983&r2=689984&view=diff
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.jcas.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.jcas.xml Thu Aug 28 14:08:43 2008
@@ -170,7 +170,23 @@
     + ", size left mods: " + getlMods().size()
     + ", size right mods: " + getrMods().size();
 }</programlisting>
-    
+ 
+    <section id="ugr.ref.jcas.data_persistence">
+      <title>Persistence of additional data</title>
+      <para>If you add custom instance fields to JCas cover classes, these exist in the JCas cover object instance,
+        but not in the CAS itself. Each time a CAS object is referenced (by an iterator, or by following a Feature
+        Structure reference), a new JCas cover object instance may be created. If you need these values, you can (a)
+        make them CAS values if possible, or (b) hold a reference to the the particular JCas cover object instance in
+        your Java code. For some simple cases, setting the the performance tuning option JCAS_CACHE_ENABLE (see
+          <olink targetdoc="&uima_docs_tutorial_guides;" targetptr="tug.application.pto"/>)
+         to true
+        will cause the same JCas cover object that was previously used for a particular CAS Feature Structure to be
+        reused. However, this capability won't work when other factors interfere with the ability to reuse the same
+        object.  Pear isolation is an example of this.</para>
+      <para>Because of this, and because the JCas Cache holds on to the JCas cover objects beyond their useful life and
+        prevents them from being garbage collected, it is normally recommended running with the
+        JCAS_CACHE_ENABLE set to "false".</para>
+    </section>   
     <section id="ugr.ref.jcas.keeping_augmentations_when_regenerating">
       <title>Keeping hand-coded augmentations when regenerating</title>