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

[tw...@apache.org]

Author: twgoetz
Date: Wed Feb  7 09:21:24 2007
New Revision: 504624

URL: http://svn.apache.org/viewvc?view=rev&rev=504624
Log:
No Jira: assorted CAS reference improvements.

Modified:
    incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.cas.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?view=diff&rev=504624&r1=504623&r2=504624
==============================================================================
--- 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 Wed Feb  7 09:21:24 2007
@@ -34,7 +34,19 @@
     objects in the CAS. This chapter describes an alternative interface to the CAS which
     allows discovery and specification of types and features at run time. It is recommended
     for use when the using code cannot know ahead of time the type system it will be dealing
-    with.</para>
+    with.</para>
+    
+  <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:
+  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
+  UIMA application, and you're not sure that they won't add features to your types, do not use the
+  JCas for the same reasons.
+  </para>
   
   <para>CASes passed to Annotator Components are either a base CAS or a regular CAS. Base CASes
     are only passed to Multi-View components - they are like regular CASes, but do not have user
@@ -53,10 +65,10 @@
   <section id="ugr.ref.cas.overview">
     <title>CAS Overview</title>
     
-    <para>There are three main parts to the CAS: the type system, data creation and
-      manipulation, and indexing. <footnote><para>A fourth part, the Subject of Analysis,
-      is discussed in <olink targetdoc="&uima_docs_tutorial_guides;"
-        targetptr="ugr.tug.aas"/>.</para></footnote> We will start with a brief
+    <para>There are three<footnote><para>A fourth part, the Subject of Analysis,
+      is discussed in <olink targetdoc="&uima_docs_tutorial_guides;"
+        targetptr="ugr.tug.aas"/>.</para></footnote> main parts to the CAS: the type system, data creation and
+      manipulation, and indexing.  We will start with a brief
       description of these components.</para>
     <section id="ugr.ref.cas.type_system">
       <title>The Type System</title>
@@ -74,7 +86,7 @@
         structures</quote> (not to be confused with <quote>features</quote>). Feature
         structures are similar to the many variants of record structures found in computer
         science.<footnote><para> The name <quote>feature structure</quote> comes from
-        terminology used in linguistics.</para></footnote>.</para>
+        terminology used in linguistics.</para></footnote></para>
       
       <para>Each CAS Type defines a supertype; it is a subtype of that supertype. This means
         that any features that the supertype defines are features of the subtype; in other