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 2007/07/10 23:00:55 UTC
svn commit: r555076 - in
/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook: ./
overview_and_setup/ references/ tools/
Author: schor
Date: Tue Jul 10 14:00:54 2007
New Revision: 555076
URL: http://svn.apache.org/viewvc?view=rev&rev=555076
Log:
No Jira - misc updates to docs, incl spelling corrections, plus
adding more info on JCas class loader switching, and more
info on JCas style addToIndexes() re: which view is implied.
Modified:
incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/common_book_info.xml
incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/overview_and_setup/faqs.xml
incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/overview_and_setup/overview_and_setup.xml
incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/overview_and_setup/project_overview.xml
incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.javadocs.xml
incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.jcas.xml
incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.xml.cpe_descriptor.xml
incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.cde.xml
Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/common_book_info.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/common_book_info.xml?view=diff&rev=555076&r1=555075&r2=555076
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/common_book_info.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/common_book_info.xml Tue Jul 10 14:00:54 2007
@@ -26,7 +26,7 @@
<productname>UIMA</productname>
<authorgroup>
- <corpauthor>Authors: The Apache UIMA Development Community</corpauthor>
+ <corpauthor>Written and maintained by the Apache UIMA Development Community</corpauthor>
</authorgroup>
<!--
Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/overview_and_setup/faqs.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/overview_and_setup/faqs.xml?view=diff&rev=555076&r1=555075&r2=555076
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/overview_and_setup/faqs.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/overview_and_setup/faqs.xml Tue Jul 10 14:00:54 2007
@@ -223,7 +223,7 @@
see all the CASes being processed. If false, then that component will see all of the
CASes being processed. In this case, it can accumulate state information among all
the CASes. Typically, Analysis Engines in the main analysis pipeline are marked
- multipleDeploymentAllowed = true. The CAS Consumer comonent, on the other hand,
+ multipleDeploymentAllowed = true. The CAS Consumer component, on the other hand,
defaults to having this property set to false, and is typically associated with
some resource like a database or search engine that aggregates analysis results
across an entire collection.</para>
@@ -375,9 +375,10 @@
<varlistentry id="ugr.faqs.levels_required">
<term><emphasis role="bold">What Java level and OS are required for the UIMA SDK?</emphasis></term>
<listitem><para>The UIMA SDK requires a Java 1.4 level (or later); it will not run on a
- 1.3 (or earlier levels). It has been tested with IBM Java SDK v1.4.2, and Java 5.0. It has been
+ 1.3 (or earlier levels). It has been tested with IBM Java SDK v1.4.2, Java 5 and Java 6.
+ It has been
tested on Windows 2000, Windows XP and Linux Intel 32bit platforms, and MacOSX. Other
- platforms and JDK implementations, including Java 6, will likely work, but have
+ platforms and JDK implementations will likely work, but have
not been as significantly tested.</para></listitem>
</varlistentry>
<varlistentry id="ugr.faqs.building_apps_on_top_of_uima">
Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/overview_and_setup/overview_and_setup.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/overview_and_setup/overview_and_setup.xml?view=diff&rev=555076&r1=555075&r2=555076
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/overview_and_setup/overview_and_setup.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/overview_and_setup/overview_and_setup.xml Tue Jul 10 14:00:54 2007
@@ -23,7 +23,7 @@
under the License.
-->
<book lang="en">
- <title>Overview & Setup</title>
+ <title>UIMA Overview & SDK Setup</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../common_book_info.xml"/>
<toc/>
Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/overview_and_setup/project_overview.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/overview_and_setup/project_overview.xml?view=diff&rev=555076&r1=555075&r2=555076
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/overview_and_setup/project_overview.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/overview_and_setup/project_overview.xml Tue Jul 10 14:00:54 2007
@@ -36,7 +36,7 @@
<para>The <emphasis>Apache UIMA</emphasis> framework is an Apache licensed, open source implementation of the
UIMA Architecture, and provides a run-time environment in which developers can plug in
and run their UIMA component implementations and with which they can build and deploy UIM applications. The
- framework is not specific to any IDE or platform.</para>
+ framework itself is not specific to any IDE or platform.</para>
<para>It includes an all-Java implementation of the
UIMA framework for the development, description, composition and deployment of UIMA components and
@@ -101,7 +101,7 @@
</itemizedlist> </para>
<para>
- The first 2 parts make up the book <quote>overview_and_setup</quote>; the last 3 have individual
+ The first 2 parts make up this book; the last 3 have individual
books. The books are provided both as
(somewhat large) html files, viewable in browsers, and also as PDF files.
The documentation is fully hyperlinked, with tables of contents. The PDF versions are set up to
@@ -404,7 +404,7 @@
</listitem>
<listitem>
<para> Set up Apache UIMA in your Eclipse environment. To do this, follow the instructions in <xref
- linkend="ugr.project_overview_setup"/>. </para>
+ linkend="ugr.ovv.eclipse_setup"/>. </para>
</listitem>
<listitem>
<para> Develop sample UIMA annotators, run them and explore the results. Read <olink
Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.javadocs.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.javadocs.xml?view=diff&rev=555076&r1=555075&r2=555076
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.javadocs.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.javadocs.xml Tue Jul 10 14:00:54 2007
@@ -56,7 +56,8 @@
OpenExternalJavaDoc, or open the Javadoc view (Window → Show View → Other
→ Java → Javadoc).</para>
- <para>In a similar manner, you can attach the source for the UIMA framework. The source is, of course, available from
- the Apache UIMA website (<ulink url="http://incubator.apache.org/uima"/>).</para>
+ <para>In a similar manner, you can attach the source for the UIMA framework. The source corresponding to particular
+ releases is available from the Apache UIMA web site (<ulink url="http://incubator.apache.org/uima"/>) on the
+ downloads page.</para>
</chapter>
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?view=diff&rev=555076&r1=555075&r2=555076
==============================================================================
--- 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 Tue Jul 10 14:00:54 2007
@@ -109,7 +109,7 @@
</section>
<section id="ugr.ref.jcas.use_of_description">
- <title>The XML description element is copied into generated Java code</title>
+ <title>XML description element</title>
<titleabbrev>Use of XML Description</titleabbrev>
<para>Each XML type specification can have <description ...
@@ -264,8 +264,9 @@
</section>
<section id="ugr.ref.jcas.merging_types_from_other_specs">
- <title>Merging types from different type system specifications</title>
+ <title>Merging types</title>
<titleabbrev>Merging Types</titleabbrev>
+ <para>Type definitions are merged by the framework from all the components being run together.</para>
<section id="ugr.ref.jcas.merging_types.aggregates_and_cpes">
<title>Aggregate AEs and CPEs as sources of types</title>
@@ -273,7 +274,8 @@
<para>When running aggregate AEs (Analysis Engines), or a set of AEs in a collection processing engine, the
UIMA framework will build a merged type system (Note: this <quote>merge</quote> is merging types, not to be
confused with merging Java source code, discussed above). This merged type system has all the types of every
- component used in the application.</para>
+ component used in the application. In addition, application code can use UIMA Framework APIs to read and merge
+ type descriptions, manually.</para>
<para>In most cases, each type system can have its own Java Class Models generated individually, perhaps at an
earlier time, and the resulting class files (or .jar files containing these class files) can be put in the
@@ -284,14 +286,17 @@
all the defined features for a particular type into that type's type definition. However, the JCas
classes for these types are not automatically merged, which can create some issues for JCas users, as
discussed in the next section.</para>
+
</section>
<section id="ugr.ref.jcas.merging_types.jcasgen_support">
<title>JCasGen support for type merging</title>
<para>When there are multiple definitions of the same CAS type with different features defined, then JCasGen
- must be re-run on the merged type system. Directions for running JCasGen can be found in <olink
- targetdoc="&uima_docs_tools;" targetptr="ugr.tools.jcasgen"/>. This must be done by the person who
+ can be re-run on the merged type system, to create one set of JCas Class definitions for the merged types,
+ which can then be shared by all the components.
+ Directions for running JCasGen can be found in <olink
+ targetdoc="&uima_docs_tools;" targetptr="ugr.tools.jcasgen"/>. This is typically done by the person who
is assembling the Aggregate Analysis Engine or Collection Processing Engine. The resulting merged Java
Class Model will then contain get and set methods for the complete set of features. These Java classes must
then be made available in the class path, <emphasis>replacing</emphasis> the pre-merge versions of the
@@ -300,11 +305,16 @@
<para>If hand-modifications were done to the pre-merge versions of the classes, these must be applied to the
merged versions, as described in section <xref
linkend="ugr.ref.jcas.keeping_augmentations_when_regenerating"/>, above. If just one of the
- pre-merge versions had hand-modifications, the source for this hand-modified version must be put into the
- file system where the generated output will go, and the -merge option must be used. If
+ pre-merge versions had hand-modifications, the source for this hand-modified version can be put into the
+ file system where the generated output will go, and the -merge option for JCasGen will automatically
+ merge the hand-modifications with the generated code. If
<emphasis>both</emphasis> pre-merged versions had hand-modifications, then these modifications must
be manually merged.</para>
+ <para>An alternative to this is packaging the components as individual PEAR files, each with their own
+ version of the JCas generated Classes. The Framework (as of release 2.2) can run PEAR files using the
+ pear file descriptor, and supply each component with its particular version of the JCas generated class.</para>
+
</section>
<section id="ugr.ref.jcas.impact_of_type_merging_on_composability">
@@ -317,9 +327,10 @@
<para>If you do choose to create a JCas Annotator that relies on Type Merging (meaning that your annotator
redefines a Type that is already in use elsewhere, and adds its own features), this can negatively impact the
- reusability of your annotator.</para>
+ reusability of your annotator, unless your component is used as a PEAR file.</para>
- <para>Whenever anyone wants to combine your annotator with another annotator that uses a different version of
+ <para>If not using PEAR file packaging isolation capability, whenever
+ anyone wants to combine your annotator with another annotator that uses a different version of
the same Type, they will need to be aware of all of the issues described in the previous section. They will need
to have the know-how to re-run JCasGen and appropriately set up their classpath to include the merged Java
classes and to not include the pre-merge classes. (To enable this, you should package these classes
@@ -504,6 +515,24 @@
<programlisting>myInstance.addToIndexes(); // index in the JCas used with the new operator
myView1.addFsToIndexes(myInstance); // index myInstance in myView1
myView2.addFsToIndexes(myInstance); // index myInstance in myView2</programlisting>
+
+ <para>
+ The rules for determining which index to use with a particular JCas object are designed to
+ behave the way most would think they should; if you need specific behavior, you can always
+ explicitly designate which view the index adding and removing operations should work on.
+ </para>
+
+ <para>
+ The rules are:
+ If the instance is a subtype of AnnotationBase, then the view is the view associated with the
+ annotation as specified in the feature holding the view reference in AnnotationBase.
+ Otherwise, if the instance was created using the "new" operator, then the view is the view passed to the
+ instance's constructor.
+ Otherwise, if the instance was created by getting a feature value from some other instance, whose range
+ type is a feature structure, then the view is the same as the referring instance.
+ Otherwise, if the instance was created by any of the Feature Structure Iterator operations over some index,
+ then it is the view associated with the index.
+ </para>
</section>
<section id="ugr.ref.jcas.using_iterators">
@@ -570,18 +599,14 @@
<title>Issues accessing JCas objects outside of UIMA Engine Components</title>
<para>If you are using the ExtensionClassPaths, the JCas cover classes are loaded
- under a class loader created by the ResourceManager part of the UIMA Framework.
+ under a class loader created by the ResourceManager part of the UIMA Framework.
If you reference the same JCas
classes outside of any UIMA component, for instance, in top level application code,
- the JCas classes used by that top level application code must be loaded under the same
- class loader, in order to avoid class cast exceptions. Currently, there is no
- supported way to do this if you are using ExtensionClassPaths.</para>
-
- <para>The workaround is to do all the JCas processing inside a UIMA component (no
- processing using JCas outside of the UIMA pipeline), or to put the JCas classes only in
- the main classpath for the UIMA Framework, and insure they are not findable in the
- ExtensionClassPaths. This latter approach of course limits you to one set of JCas
- class definitions per UIMA framework.</para>
+ the JCas classes used by that top level application code also must be in the class path
+ for the application code.</para>
+
+ <para>Alternatively, you could do all the JCas processing inside a UIMA component (and do no
+ processing using JCas outside of the UIMA pipeline).</para>
</section>
</section>
@@ -596,6 +621,19 @@
This is most conveniently done by opening the top level descriptor used by the
application in the Component Descriptor Editor tool, and pressing the Run-JCasGen
button on the Type System Definition page.</para>
+
+ </section>
+
+ <section id="ugr.ref.jcas.pear_support">
+ <title>PEAR isolation</title>
+ <para>
+ As of version 2.2, the framework supports component descriptors which are PEAR descriptors.
+ These descriptors define components plus include information on the class path needed to
+ run them. The framework uses the class path information to set up a localized class path, just
+ for code running within the PEAR context. This allows PEAR files requiring different
+ versions of common code to work well together, even if the class names in the different versions
+ have the same names.
+ </para>
</section>
Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.xml.cpe_descriptor.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.xml.cpe_descriptor.xml?view=diff&rev=555076&r1=555075&r2=555076
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.xml.cpe_descriptor.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.xml.cpe_descriptor.xml Tue Jul 10 14:00:54 2007
@@ -178,13 +178,13 @@
<section id="&tp;imports">
<title>Imports</title>
- <para>As of version 2.2, a CPE Descriptor can use the same <literal>import</literal> mecanism
+ <para>As of version 2.2, a CPE Descriptor can use the same <literal>import</literal> mechanism
as other component descriptors. This allows referring to component
descriptors using either relative paths (resolved relative to the location of the CPE descriptor)
or the classpath/datapath. For details see <olink targetdoc="&uima_docs_ref;"
targetptr="ugr.ref.xml.component_descriptor"/>.</para>
- <para>The follwing older syntax is still supported, but not recommended:
+ <para>The follwing older syntax is still supported, but <emphasis>not recommended</emphasis>:
<programlisting><![CDATA[<descriptor>
<include href="[URL or File]"/>
Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.cde.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.cde.xml?view=diff&rev=555076&r1=555075&r2=555076
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.cde.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.cde.xml Tue Jul 10 14:00:54 2007
@@ -29,8 +29,8 @@
<para>The Component Descriptor Editor is an Eclipse plug-in that provides a forms-based
interface for creating and editing UIMA XML descriptors. It supports most of the
- descriptor formats, except the Collection Processing Engine descriptor and
- some remote deployment descriptors.</para>
+ descriptor formats, except the Collection Processing Engine descriptor, the PEAR
+ package descriptor and some remote deployment descriptors.</para>
<section id="ugr.tools.cde.launching">
<title>Launching the Component Descriptor Editor</title>
@@ -1353,9 +1353,13 @@
requires additional information, other than what is available in just the importable
part. For instance, when you create or edit an Indexes import, the facility for adding
new indexes needs the type information, which is not present in this part when it is
- edited alone. To overcome this, when you edit these descriptors, you will be asked to
+ edited alone. </para>
+
+ <para>To overcome this, when you edit these descriptors, you will be asked to
specify a context descriptor, usually a descriptor which would import the part being
- edited, which would have the additional information needed. Various methods are used
+ edited, which would have the additional information needed. </para>
+
+ <para>Various methods are used
to guess what the context descriptor should be - and if the guess is correct, you can just
press the Enter key to confirm. The last successful context file is remembered and will
be suggested as the context file to use at the next edit session</para>