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 2010/05/06 16:01:57 UTC
svn commit: r941739 [2/5] - in
/uima/uimaj/branches/mavenAlign/uima-docbook-references: ./ src/
src/docbook/ src/docbook/images/ src/docbook/images/references/
src/docbook/images/references/ref.cas/
src/docbook/images/references/ref.javadocs/ src/docbo...
Added: uima/uimaj/branches/mavenAlign/uima-docbook-references/src/docbook/ref.jcas.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/mavenAlign/uima-docbook-references/src/docbook/ref.jcas.xml?rev=941739&view=auto
==============================================================================
--- uima/uimaj/branches/mavenAlign/uima-docbook-references/src/docbook/ref.jcas.xml (added)
+++ uima/uimaj/branches/mavenAlign/uima-docbook-references/src/docbook/ref.jcas.xml Thu May 6 14:01:56 2010
@@ -0,0 +1,660 @@
+<?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 % 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.jcas">
+ <title>JCas Reference</title>
+
+ <para>The CAS is a system for sharing data among annotators, consisting of data structures
+ (definable at run time), sets of indexes over these data, metadata describing these, subjects of
+ analysis, and a high
+ performance serialization/deserialization mechanism. JCas provides Java approach to
+ accessing CAS data, and is based on using generated, specific Java classes for each CAS
+ type.</para>
+
+ <para>Annotators process one CAS per call to their process method. During processing,
+ annotators can retrieve feature structures from the passed in CAS, add new ones, modify
+ existing ones, and use and update CAS indexes. Of course, an annotator can also use plain
+ Java Objects in addition; but the data in the CAS is what is shared among annotators within
+ an application.</para>
+
+ <para>All the facilities present in the APIs for the CAS are available when using the JCas
+ APIs; indeed, you can use the getCas() method to get the corresponding CAS object from a
+ JCas (and vice-versa). The JCas APIs often have helper methods that make using this
+ interface more convenient for Java developers.</para>
+
+ <para>The data in the CAS are typed objects having fields. JCas uses a set of generated Java
+ classes (each corresponding to a particular CAS type) with <quote>getter</quote> and
+ <quote>setter</quote> methods for the features, plus a constructor so new instances can
+ be made. The Java classes don't actually store the data in the class instance;
+ instead, the getters and setters forward to the underlying CAS data representation.
+ Because of this, applications which use the JCas interface can share data with annotators
+ using plain CAS (i.e., not using the JCas approach). </para>
+
+ <para>Users can modify the JCas generated
+ Java classes by adding fields to them; this allows arbitrary non-CAS data to also be
+ represented within the JCas objects, as well; however, the non-CAS data stored in the JCas
+ object instances cannot be shared with annotators using the plain CAS.</para>
+
+ <para>Data in the CAS initially has no corresponding JCas type instances; these are created
+ as needed at the first reference. This means, if your annotator is passed a large CAS having
+ millions of CAS feature structures, but you only reference a few of them, and no previously
+ created Java JCas object instances were created by upstream annotators, the only Java
+ objects that will be created will be those that correspond to the CAS feature structures
+ that you reference.</para>
+
+ <para>The JCas class Java source files are generated from XML type system descriptions. The
+ JCasGen utility does the work of generating the corresponding Java Class Model for the CAS
+ types. There are a variety of ways JCasGen can be run; these are described later. You
+ include the generated classes with your UIMA component, and you can publish these classes
+ for others who might want to use your type system.</para>
+
+ <para>The specification of the type system in XML can be written using a conventional text
+ editor, an XML editor, or using the Eclipse plug-in that supports editing UIMA
+ descriptors.</para>
+
+ <para>Changes to the type system are done by changing the XML and regenerating the
+ corresponding Java Class Models. Of course, once you've published your type system
+ for others to use, you should be careful that any changes you make don't adversely
+ impact the users. Additional features can be added to existing types without breaking
+ other code.</para>
+
+ <para>A separate Java class is generated for each type; this type implements the CAS
+ FeatureStructure interface, as well as having the special getters and setters for the
+ included features. In the current implementation, an additional helper class per type is
+ also generated. The generated Java classes have methods (getters and setters) for the
+ fields as defined in the XML type specification. Descriptor comments are reflected in the
+ generated Java code as Java-doc style comments.</para>
+
+
+ <section id="ugr.ref.jcas.name_spaces">
+ <title>Name Spaces</title>
+
+ <para>Full Type names consist of a <quote>namespace</quote> prefix dotted with a simple
+ name. Namespaces are used like packages to avoid collisions between types that are
+ defined by different people at different times. The namespace is used as the Java
+ package name for generated Java files.</para>
+
+ <para>Type names used in the CAS correspond to the generated Java classes directly. If the
+ CAS name is com.myCompany.myProject.ExampleClass, the generated Java class is in the
+ package com.myCompany.myProject, and the class is ExampleClass.</para>
+
+ <para>
+ An exception to this rule is the built-in types
+ starting with <literal>uima.cas </literal>and <literal>uima.tcas</literal>;
+ these names are mapped to Java packages named
+ <literal>org.apache.uima.jcas.cas</literal> and
+ <literal>org.apache.uima.jcas.tcas</literal>.</para>
+
+ </section>
+
+ <section id="ugr.ref.jcas.use_of_description">
+ <title>XML description element</title>
+ <titleabbrev>Use of XML Description</titleabbrev>
+
+ <para>Each XML type specification can have <description ...
+ > tags. The description for a type will be copied into the generated Java code, as a
+ Javadoc style comment for the class. When writing these descriptions in the XML type
+ specification file, you might want to use html tags, as allowed in Javadocs.</para>
+
+ <para>If you use the Component Description Editor, you can write the html tags normally,
+ for instance, <quote><h1>My Title</h1></quote>. The Component
+ Descriptor Editor will take care of coverting the actual descriptor source so that it
+ has the leading <quote><</quote> character written as <quote>&lt;</quote>,
+ to avoid confusing the XML type specification. For example, <p> would be written
+ in the source of the descriptor as &lt;p>. Any characters used in the Javadoc
+ comment must of course be from the character set allowed by the XML type specification.
+ These specifications often start with the line <?xml version=<quote>1.0</quote>
+ encoding=<quote>UTF-8</quote> ?>, which means you can use any of the UTF-8
+ characters.</para>
+
+ </section>
+
+ <section id="ugr.ref.jcas.mapping_built_ins">
+ <title>Mapping built-in CAS types to Java types</title>
+
+ <para>The built-in primitive CAS types map to Java types as follows:</para>
+
+
+ <programlisting>uima.cas.Boolean → boolean
+uima.cas.Byte → byte
+uima.cas.Short → short
+uima.cas.Integer → int
+uima.cas.Long → long
+uima.cas.Float → float
+uima.cas.Double → double
+uima.cas.String → String</programlisting>
+
+ </section>
+
+ <section id="ugr.ref.jcas.augmenting_generated_code">
+ <title>Augmenting the generated Java Code</title>
+
+ <para>The Java Class Models generated for each type can be augmented by the user. Typical
+ augmentations include adding additional (non-CAS) fields and methods, and import
+ statements that might be needed to support these. Commonly added methods include
+ additional constructors (having different parameter signatures), and
+ implementations of toString().</para>
+
+ <para>To augment the code, just edit the generated Java source code for the class named the
+ same as the CAS type. Here's an example of an additional method you might add; the
+ various getter methods are retrieving values from the instance:</para>
+
+
+ <programlisting>public String toString() { // for debugging
+ return "XsgParse "
+ + getslotName() + ": "
+ + getheadWord().getCoveredText()
+ + " seqNo: " + getseqNo()
+ + ", cAddr: " + id
+ + ", 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>
+
+ <para>If the type system specification changes, you have to re-run the JCasGen
+ generator. This will produce updated Java for the Class Models that capture the
+ changed specification. If you have previously augmented the source for these Java
+ Class Models, your changes must be merged with the newly (re)generated Java source
+ code for the Class Models. This can be done by hand, or you can run the version of JCasGen
+ that is integrated with Eclipse, and use automatic merging that is done using Eclipse's EMF
+ plug-in. You can obtain Eclipse and the needed EMF plug-in from <ulink
+ url="http://www.eclipse.org/"/>.</para>
+
+ <para>If you run the generator version that works without using Eclipse, it will not
+ merge Java source changes you may have previously made; if you want them retained,
+ you'll have to do the merging by hand.</para>
+
+ <para>The Java source merging will keep additional constructors, additional fields,
+ and any changes you may have made to the readObject method (see below). Merging will
+ <emphasis>not</emphasis> delete classes in the target corresponding to deleted CAS types, which no longer
+ are in the source – you should delete these by hand.</para>
+
+ <warning><para>The merging supports Java 1.4 syntactic constructs only.
+ JCasGen generates Java 1.4 code, so as long as any code you change here also sticks to
+ only Java 1.4 constructs, the merge will work. If you use Java 5 or later specific syntax or constructs, the merge
+ operation will likely fail to merge properly.</para></warning>
+ </section>
+
+ <section id="ugr.ref.jcas.additional_constructors">
+ <title>Additional Constructors</title>
+
+ <para>Any additional constructors that you add must include the JCas argument. The
+ first line of your constructor is required to be</para>
+
+
+ <programlisting>this(jcas); // run the standard constructor</programlisting>
+
+ <para>where jcas is the passed in JCas reference. If the type you're defining
+ extends <literal>uima.tcas.Annotation</literal>, JCasGen will automatically
+ add a constructor which takes 2 additional parameters – the begin and end Java
+ int values, and set the <literal>uima.tcas.Annotation</literal>
+ <literal>begin</literal> and <literal>end</literal> fields.</para>
+
+ <para>Here's an example: If you're defining a type MyType which has a
+ feature parent, you might make an additional constructor which has an additional
+ argument of parent:</para>
+
+
+ <programlisting>MyType(JCas jcas, MyType parent) {
+ this(jcas); // run the standard constructor
+ setParent(parent); // set the parent field from the parameter
+}</programlisting>
+
+ <section id="ugr.ref.jcas.using_readobject">
+ <title>Using readObject</title>
+
+ <para>Fields defined by augmenting the Java Class Model to include additional
+ fields represent data that exist for this class in Java, in a local JVM (Java Virtual
+ Machine), but do not exist in the CAS when it is passed to other environments (for
+ example, passing to a remote annotator).</para>
+
+ <para>A problem can arise when new instances are created, perhaps by the underlying
+ system when it iterates over an index, which is: how to insure that any additional
+ non-CAS fields are properly initialized. To allow for arbitrary initialization
+ at instance creation time, an initialization method in the Java Class Model,
+ called readObject is used. The generated default for this method is to do nothing,
+ but it is one of the methods that you can modify – to do whatever
+ initialization might be needed. It is called with 0 parameters, during the
+ constructor for the object, after the basic object fields have been set up. It can
+ refer to fields in the CAS using the getters and setters, and other fields in the Java
+ object instance being initialized.</para>
+
+ <para>A pre-existing CAS feature structure could exist if a CAS was being passed to
+ this annotator; in this case the JCas system calls the readObject method when
+ creating the corresponding Java instance for the first time for the CAS feature
+ structure. This can happen at two points: when a new object is being returned from an
+ iterator over a CAS index, or a getter method is getting a field for the first time
+ whose value is a feature structure.</para>
+
+ </section>
+ </section>
+
+ <section id="ugr.ref.jcas.modifying_generated_items">
+ <title>Modifying generated items</title>
+
+ <para>The following modifications, if made in generated items, will be preserved when
+ regenerating.</para>
+
+ <para>The public/private etc. flags associated with methods (getters and setters).
+ You can change the default (<quote>public</quote>) if needed.</para>
+
+ <para><quote>final</quote> or <quote>abstract</quote> can be added to the type
+ itself, with the usual semantics.</para>
+
+ </section>
+ </section>
+
+ <section id="ugr.ref.jcas.merging_types_from_other_specs">
+ <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>
+
+ <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. 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
+ class path to enable JCas.</para>
+
+ <para>However, it is possible that there may be multiple definitions of the same CAS type, each of which might
+ have different features defined. In this case, the UIMA framework will create a merged type by accumulating
+ 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
+ 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
+ classes.</para>
+
+ <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 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">
+ <title>Impact of Type Merging on Composability of Annotators</title>
+ <titleabbrev>Type Merging impacts on Composability</titleabbrev>
+
+ <para>The recommended approach in UIMA is to build and maintain type systems as separate components, which are
+ imported by Annotators. Using this approach, Type Merging does not occur because the Type System and its JCas
+ classes are centrally managed and shared by the annotators.</para>
+
+ <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, unless your component is used as a PEAR file.</para>
+
+ <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
+ separately from other .jar files for your annotator, so that they can be more easily excluded.) And, if you
+ have done hand-modifications to your JCas classes, the person assembling your annotator will need to
+ properly merge those changes. These issues significantly complicate the task of combining annotators, and
+ will cause your annotator not to be as easily reusable as other UIMA annotators. </para>
+
+ </section>
+
+ <section id="ugr.ref.jcas.documentannotation_issues">
+ <title>Adding Features to DocumentAnnotation</title>
+
+ <para>There is one built-in type, <literal>uima.tcas.DocumentAnnotation</literal>,
+ to which applications can add additional features. (All other built-in types
+ are "feature-final" and you cannot add additional features to them.) Frequently,
+ additional features are added to <literal>uima.tcas.DocumentAnnotation</literal>
+ to provide a place to store document-level metadata.</para>
+
+ <para>For the same reasons mentioned in the previous section, adding features to
+ DocumentAnnotation is not recommended if you are using JCas. Instead, it is recommended
+ that you define your own type for storing your document-level metadata. You can create
+ an instance of this type and add it to the indexes in the usual way. You can then
+ retrieve this instance using the iterator returned from the method<literal>getAllIndexedFS(type)</literal>
+ on an instance of a JFSIndexRepository object.
+ (As of UIMA v2.1, you do not have to declare a custom index in your descriptor to
+ get this to work).</para>
+
+ <para>If you do choose to add features to DocumentAnnotation, there are additional issues to
+ be aware of. The UIMA SDK provides the JCas cover class for the built-in definition of
+ DocumentAnnotation, in the separate jar file <literal>uima-document-annotation.jar</literal>.
+ If you add additional features to DocumentAnnotation, you must remove this jar file
+ from your classpath, because you will not want to use the default JCas cover class.
+ You will need to re-run JCasGen as described in <xref
+ linkend="ugr.ref.jcas.merging_types.jcasgen_support"/>. JCasGen will generate a new cover
+ class for DocumentAnnotation, which you must place in your classpath in lieu of the version
+ in <literal>uima-document-annotation.jar</literal>.</para>
+
+ <para>Also, this is the reason why the method <literal>JCas.getDocumentAnnotationFs()</literal> returns
+ type <literal>TOP</literal>, rather than type <literal>DocumentAnnotation</literal>. Because the
+ <literal>DocumentAnnotation</literal> class can be replaced by users, it is not part of
+ <literal>uima-core.jar</literal> and so the core UIMA framework cannot have any references
+ to it. In your code, you may <quote>cast</quote> the result of <literal>JCas.getDocumentAnnotationFs()</literal>
+ to type <literal>DocumentAnnotation</literal>, which must be available on the classpath either via
+ <literal>uima-document-annotation.jar</literal> or by including a custom version that you have generated using JCasGen.</para>
+ </section>
+
+ </section>
+
+ <section id="ugr.ref.jcas.using_within_an_annotator">
+ <title>Using JCas within an Annotator</title>
+
+ <para>To use JCas within an annotator, you must include the generated Java classes output
+ from JCasGen in the class path.</para>
+
+ <para>An annotator written using JCas is built by defining a class for the annotator that
+ extends JCasAnnotator_ImplBase. The process method for this annotator is
+ written</para>
+
+ <programlisting>public void process(JCas jcas)
+ throws AnalysisEngineProcessException {
+ ... // body of annotator goes here
+}</programlisting>
+
+ <para>The process method is passed the JCas instance to use as a parameter.</para>
+
+ <para>The JCas reference is used throughout the annotator to refer to the particular JCas
+ instance being worked on. In pooled or multi-threaded implementations, there will be a
+ separate JCas for each thread being (simultaneously) worked on.</para>
+
+ <para>You can do several kinds of operations using the JCas APIs: create new feature
+ structures (instances of CAS types) (using the new operator), access existing feature
+ structures passed to your annotator in the JCas (for example, by using the next method of
+ an iterator over the feature structures), get and set the fields of a particular
+ instance of a feature structure, and add and remove feature structure instances from
+ the CAS indexes. To support iteration, there are also functions to get and use indexes
+ and iterators over the instances in a JCas.</para>
+
+ <section id="ugr.ref.jcas.new_instances">
+ <title>Creating new instances using the Java <quote>new</quote> operator</title>
+ <titleabbrev>Creating new instances</titleabbrev>
+
+ <para>The new operator creates new instances of JCas types. It takes at least one
+ parameter, the JCas instance in which the type is to be created. For example, if there
+ was a type Meeting defined, you can create a new instance of it using:
+
+ <programlisting>Meeting m = new Meeting(jcas);</programlisting></para>
+
+ <para>Other variations of constructors can be added in custom code; the single
+ parameter version is the one automatically generated by JCasGen. For types that are
+ subtypes of Annotation, JCasGen also generates an additional constructor with
+ additional <quote>begin</quote> and <quote>end</quote> arguments.</para>
+
+ </section>
+ <section id="ugr.ref.jcas.getters_and_setters">
+ <title>Getters and Setters</title>
+
+ <para>If the CAS type Meeting had fields location and time, you could get or set these by
+ using getter or setter methods. These methods have names formed by splicing together
+ the word <quote>get</quote> or <quote>set</quote> followed by the field name, with
+ the first letter of the field name capitalized. For instance
+
+ <programlisting>getLocation()</programlisting></para>
+
+ <para>The getter forms take no parameters and return the value of the field; the setter
+ forms take one parameter, the value to set into the field, and return void.</para>
+
+ <para>There are built-in CAS types for arrays of integers, strings, floats, and
+ feature structures. For fields whose values are these types of arrays, there is an
+ alternate form of getters and setters that take an additional parameter, written as
+ the first parameter, which is the index in the array of an item to get or set.</para>
+
+ </section>
+
+ <section id="ugr.ref.jcas.obtaining_refs_to_indexes">
+ <title>Obtaining references to Indexes</title>
+
+ <para>The only way to access instances (not otherwise referenced from other
+ instances) passed in to your annotator in its JCas is to use an iterator over some
+ index. Indexes in the CAS are specified in the annotator descriptor. Indexes have a
+ name; text annotators have a built-in, standard index over all annotations.</para>
+
+ <para>To get an index, first get the JFSIndexRepository from the JCas using the method
+ jcas.getJFSIndexRepository(). Here are the calls to get indexes:</para>
+
+
+ <programlisting>JFSIndexRepository ir = jcas.getJFSIndexRepository();
+
+ir.getIndex(name-of-index) // get the index by its name, a string
+ir.getIndex(name-of-index, Foo.type) // filtered by specific type
+
+ir.getAnnotationIndex() // get AnnotationIndex
+ir.getAnnotationIndex(Foo.type) // filtered by specific type</programlisting>
+
+ <para>For convenience, the getAnnotationIndex method is available directly on the JCas object
+ instance; the implementation merely forwards to the associated index repository.</para>
+
+ <para>Filtering types have to be a subtype of the type specified for this index in its
+ index specification. They can be written as either Foo.type or if you have an instance
+ of Foo, you can write</para>
+
+ <programlisting>fooInstance.jcasType.casType. </programlisting>
+
+ <para>Foo is (of course) an example of the name of the type.</para>
+
+ </section>
+ <section id="ugr.ref.jcas.adding_removing_instances_to_indexes">
+ <title>Adding (and removing) instances to (from) indexes</title>
+ <titleabbrev>Updating Indexes</titleabbrev>
+
+ <para>CAS indexes are maintained automatically by the CAS. But you must add any
+ instances of feature structures you want the index to find, to the indexes by using the
+ call:</para>
+
+ <programlisting>myInstance.addToIndexes();</programlisting>
+
+ <para>Do this after setting all features in the instance <emphasis role="bold-italic">which could be used in indexing</emphasis>, for example, in
+ determining the sorting order. After indexing, do not change the values of these
+ particular features because the indexes will not be updated. If you need to change the
+ values, you must first remove the instance from the CAS indexes, change the values,
+ and then add the instance back. To remove an instance from the indexes, use the method:
+
+ <programlisting>myInstance.removeFromIndexes();</programlisting></para>
+ <note><para>It's OK to change feature values which are not used in determining
+ sort ordering (or set membership), without removing and re-adding back to the index.
+ </para></note>
+
+ <para>When writing a Multi-View component, you may need to index instances in multiple
+ CAS views. The methods above use the indexes associated with the current JCas object.
+ There is a variation of the <literal>addToIndexes / removeFromIndexes</literal> methods which
+ takes one argument: a reference to a JCas object holding the view in which you want to
+ index this instance.
+ <programlisting>myInstance.addToIndexes(anotherJCas)
+myInstance.removeFromIndexes(anotherJCas)</programlisting>
+ </para>
+
+ <para>
+ You can also explicitly add instances to other views using the addFsToIndexes method on
+ other JCas (or CAS) objects. For instance, if you had 2 other CAS views (myView1 and
+ myView2), in which you wanted to index myInstance, you could write:</para>
+
+ <programlisting>myInstance.addToIndexes(); //addToIndexes 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">
+ <title>Using Iterators</title>
+
+ <para>Once you have an index obtained from the JCas, you can get an iterator from the
+ index; here is an example:</para>
+
+
+ <programlisting>FSIndexRepository ir = jcas.getFSIndexRepository();
+FSIndex myIndex = ir.getIndex("myIndexName");
+FSIterator myIterator = myIndex.iterator();
+
+JFSIndexRepository ir = jcas.getJFSIndexRepository();
+FSIndex myIndex = ir.getIndex("myIndexName", Foo.type); // filtered
+FSIterator myIterator = myIndex.iterator();</programlisting>
+
+ <para>Iterators work like normal Java iterators, but are augmented to support
+ additional capabilities. Iterators are described in the CAS Reference, <olink
+ targetdoc="&uima_docs_ref;"
+ targetptr="ugr.ref.cas.indexes_and_iterators"/>.</para>
+
+ </section>
+
+ <section id="ugr.ref.jcas.class_loaders">
+ <title>Class Loaders in UIMA</title>
+
+ <para>The basic concept of a UIMA application includes assembling engines into a flow.
+ The application made up of these Engines are run within the UIMA Framework, either by
+ the Collection Processing Manager, or by using more basic UIMA Framework
+ APIs.</para>
+
+ <para>The UIMA Framework exists within a JVM (Java Virtual Machine). A JVM has the
+ capability to load multiple applications, in a way where each one is isolated from the
+ others, by using a separate class loader for each application. For instance, one set
+ of UIMA Framework Classes could be shared by multiple sets of application - specific
+ classes, even if these application-specific classes had the same names but were
+ different versions.</para>
+
+ <section id="ugr.ref.jcas.class_loaders.optional">
+ <title>Use of Class Loaders is optional</title>
+
+ <para>The UIMA framework will use a specific ClassLoader, based on how
+ ResourceManager instances are used. Specific ClassLoaders are only created if
+ you specify an ExtensionClassPath as part of the ResourceManager. If you do not
+ need to support multiple applications within one UIMA framework within a JVM,
+ don't specify an ExtensionClassPath; in this case, the classloader used
+ will be the one used to load the UIMA framework - usually the overall application
+ class loader.</para>
+
+ <para>Of course, you should not run multiple UIMA applications together, in this
+ way, if they have different class definitions for the same class name. This
+ includes the JCas <quote>cover</quote> classes. This case might arise, for
+ instance, if both applications extended
+ <literal>uima.tcas.DocumentAnnotation</literal> in differing,
+ incompatible ways. Each application would need its own definition of this class,
+ but only one could be loaded (unless you specify ExtensionClassPath in the
+ ResourceManager which will cause the UIMA application to load its private
+ versions of its classes, from its classpath).</para>
+ </section>
+ </section>
+
+ <section id="ugr.ref.jcas.accessing_jcas_objects_outside_uima_components">
+ <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.
+ 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 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>
+
+ <section id="ugr.ref.jcas.setting_up_classpath">
+ <title>Setting up Classpath for JCas</title>
+
+ <para>The JCas Java classes generated by JCasGen are typically compiled and put into a JAR
+ file, which, in turn, is put into the application's class path.</para>
+
+ <para>This JAR file must be generated from the application's merged type system.
+ 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>
+
+</chapter>
\ No newline at end of file
Added: uima/uimaj/branches/mavenAlign/uima-docbook-references/src/docbook/ref.pear.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/mavenAlign/uima-docbook-references/src/docbook/ref.pear.xml?rev=941739&view=auto
==============================================================================
--- uima/uimaj/branches/mavenAlign/uima-docbook-references/src/docbook/ref.pear.xml (added)
+++ uima/uimaj/branches/mavenAlign/uima-docbook-references/src/docbook/ref.pear.xml Thu May 6 14:01:56 2010
@@ -0,0 +1,981 @@
+<?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.pear/" >
+<!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.pear">
+ <title>PEAR Reference</title>
+
+ <para>
+ A PEAR (Processing Engine ARchive) file is a standard package
+ for UIMA components. This chapter describes the PEAR 1.0 structure and
+ specification.
+ </para>
+
+ <para>
+ The PEAR package can be used for distribution and reuse by other
+ components or applications. It also allows applications and
+ tools to manage UIMA components automatically for verification,
+ deployment, invocation, testing, etc.
+ </para>
+
+ <para>
+ Currently, there is an Eclipse plugin and a command line tool
+ available to create PEAR packages for standard UIMA components.
+ Please refer to
+ <olink targetdoc="&uima_docs_tools;"
+ targetptr="ugr.tools.pear.packager" />
+ for more information about these tools.
+ </para>
+
+ <para>
+ PEARs distributed to new targets can be installed at those targets.
+ UIMA includes a tool for installing PEARs; see
+ <olink targetdoc="&uima_docs_tools;"
+ targetptr="ugr.tools.pear.installer"/> for
+ more information about installing PEARs.
+ </para>
+
+ <para>
+ An installed PEAR can be used as a component within a UIMA pipeline,
+ by specifying the pear descriptor that is created when
+ installing the pear. See
+ <olink targetdoc="&uima_docs_ref;"
+ targetptr="ugr.ref.pear.specifier"/>.
+ </para>
+
+ <section id="ugr.ref.pear.packaging_a_component">
+ <title>Packaging a UIMA component</title>
+
+ <para>
+ For the purpose of describing the process of creating a PEAR
+ file and its internal structure, this section describes the
+ steps used to package a UIMA component as a valid PEAR file.
+ The PEAR packaging process consists of the following steps:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <xref
+ linkend="ugr.ref.pear.creating_pear_structure" />
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <xref
+ linkend="ugr.ref.pear.populating_pear_structure" />
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <xref
+ linkend="ugr.ref.pear.creating_installation_descriptor" />
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <xref
+ linkend="ugr.ref.pear.packaging_into_1_file" />
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <section id="ugr.ref.pear.creating_pear_structure">
+ <title>Creating the PEAR structure</title>
+
+ <para>
+ The first step in the PEAR creation process is to create
+ a PEAR structure. The PEAR structure is a structured
+ tree of folders and files, including the following
+ elements:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Required Elements:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ The
+ <emphasis role="bold">
+ metadata
+ </emphasis>
+ folder which contains the PEAR
+ installation descriptor and
+ properties files.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The installation descriptor (
+ <emphasis role="bold">
+ metadata/install.xml
+ </emphasis>
+ )
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A UIMA analysis engine
+ descriptor and its required
+ code, delegates (if any), and
+ resources
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Optional Elements:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ The desc folder to contain
+ descriptor files of analysis
+ engines, delegates analysis
+ engines (all levels), and other
+ components (Collection Readers,
+ CAS Consumers, etc).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The src folder to contain the
+ source code
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The bin folder to contain
+ executables, scripts, class
+ files, dlls, shared libraries,
+ etc.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The lib folder to contain jar
+ files.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The doc folder containing
+ documentation materials,
+ preferably accessible through an
+ index.html.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The data folder to contain data
+ files (e.g. for testing).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The conf folder to contain
+ configuration files.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The resources folder to contain
+ other resources and
+ dependencies.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Other user-defined folders or
+ files are allowed, but should be
+ avoided.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <figure id="ugr.ref.pear.fig.pear_structure">
+ <title>The PEAR Structure</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="3in" format="JPG"
+ fileref="&imgroot;image002.jpg" />
+ </imageobject>
+ <textobject>
+ <phrase>diagram of the PEAR structure</phrase>
+ </textobject>
+ </mediaobject>
+ </figure>
+
+ </section>
+ <section id="ugr.ref.pear.populating_pear_structure">
+ <title>Populating the PEAR structure</title>
+
+ <para>
+ After creating the PEAR structure, the component's
+ descriptor files, code files, resources files, and any
+ other files and folders are copied into the
+ corresponding folders of the PEAR structure. The
+ developer should make sure that the code would work with
+ this layout of files and folders, and that there are no
+ broken links. Although it is strongly discouraged, the
+ optional elements of the PEAR structure can be replaced
+ by other user defined files and folder, if required for
+ the component to work properly.
+ </para>
+ <note>
+ <para>
+ The PEAR structure must be self-contained. For
+ example, this means that the component must run
+ properly independently from the PEAR root folder
+ location. If the developer needs to use an absolute
+ path in configuration or descriptor files, then
+ he/she should put these files in the
+ <quote>conf</quote>
+ or
+ <quote>desc</quote>
+ and replace the path of the PEAR root folder with
+ the string
+ <quote>$main_root</quote>
+ . The tools that deploy and use PEAR files should
+ localize the files in the
+ <quote>conf</quote>
+ and
+ <quote>desc</quote>
+ folders by replacing the string
+ <quote>$main_root</quote>
+ with the local absolute path of the PEAR root
+ folder. The
+ <quote>$main_root</quote>
+ macro can also be used in the Installation
+ descriptor (install.xml)
+ </para>
+ </note>
+
+ <para>
+ Currently there are three types of component packages
+ depending on their deployment:
+ </para>
+
+ <section id="ugr.ref.pear.package_type.standard">
+ <title>Standard Type</title>
+
+ <para>
+ A component package with the
+ <emphasis role="bold">standard</emphasis>
+ type must be a valid Analysis Engine, and all the
+ required files to deploy it locally must be included
+ in the PEAR package.
+ </para>
+
+ </section>
+ <section id="ugr.ref.pear.package_type.service">
+ <title>Service Type</title>
+
+ <para>
+ A component package with the
+ <emphasis role="bold">service</emphasis>
+ type must be deployable locally as a supported UIMA
+ service (e.g. Vinci). In this case, all the required
+ files to deploy it locally must be included in the
+ PEAR package.
+ </para>
+
+ </section>
+ <section id="ugr.ref.pear.package_type.network">
+ <title>Network Type</title>
+
+ <para>
+ A component package with the network type is not
+ deployed locally but rather in the
+ <quote>remote</quote>
+ environment. It's accessed as a network AE
+ (e.g. Vinci Service). The component owner has the
+ responsibility to start the service and make sure
+ it's up and running before it's used by
+ others (like a webmaster that makes sure the web
+ site is up and running). In this case, the PEAR
+ package does not have to contain files required for
+ deployment, but must contain the network AE
+ descriptor (see
+ <olink targetdoc="&uima_docs_tutorial_guides;"
+ targetptr="ugr.tug.aae.creating_xml_descriptor" />
+ ) and the <DESC> tag in the installation
+ descriptor must point to the network AE descriptor.
+ For more information about Network Analysis Engines,
+ please refer to
+ <olink targetdoc="&uima_docs_tutorial_guides;"
+ targetptr="ugr.tug.application.remote_services" />
+ .
+ </para>
+
+ </section>
+ </section>
+
+ <section id="ugr.ref.pear.creating_installation_descriptor">
+ <title>Creating the installation descriptor</title>
+
+ <para>
+ The installation descriptor is an xml file called
+ install.xml under the metadata folder of the PEAR
+ structure. It's also called InsD. The InsD XML file
+ should be created in the UTF-8 file encoding. The InsD
+ should contain the following sections:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <OS>: This section is used to specify
+ supported operating systems
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <TOOLKITS>: This section is used to
+ specify toolkits, such as JDK, needed by the
+ component.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <SUBMITTED_COMPONENT>: This is the most
+ important section in the Installation
+ Descriptor. It's used to specify required
+ information about the component. See
+ <xref
+ linkend="ugr.ref.pear.installation_descriptor" />
+ for detailed information about this section.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <INSTALLATION>: This section is explained
+ in section
+ <xref linkend="ugr.ref.pear.installing" />
+ .
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ </section>
+
+ <section id="ugr.ref.pear.installation_descriptor">
+ <title>
+ Documented template for the installation descriptor:
+ </title>
+ <titleabbrev>Installation Descriptor: template</titleabbrev>
+
+ <para>
+ The following is a sample
+ <quote>documented template</quote>
+ which describes content of the installation descriptor
+ install.xml:
+ </para>
+
+
+ <programlisting><![CDATA[<? xml version="1.0" encoding="UTF-8"?>
+<!-- Installation Descriptor Template -->
+<COMPONENT_INSTALLATION_DESCRIPTOR>
+ <!-- Specifications of OS names, including version, etc. -->
+ <OS>
+ <NAME>OS_Name_1</NAME>
+ <NAME>OS_Name_2</NAME>
+ </OS>
+ <!-- Specifications of required standard toolkits -->
+ <TOOLKITS>
+ <JDK_VERSION>JDK_Version</JDK_VERSION>
+ </TOOLKITS>
+
+ <!-- There are 2 types of variables that are used in the InsD:
+ a) $main_root , which will be substituted with the real path to the
+ main component root directory after installing the
+ main (submitted) component
+ b) $component_id$root, which will be substituted with the real path
+ to the root directory of a given delegate component after
+ installing the given delegate component -->
+
+ <!-- Specification of submitted component (AE) -->
+ <!-- Note: submitted_component_id is assigned by developer; -->
+ <!-- XML descriptor file name is set by developer. -->
+ <!-- Important: ID element should be the first in the -->
+ <!-- SUBMITTED_COMPONENT section. -->
+ <!-- Submitted component may include optional specification -->
+ <!-- of Collection Reader that can be used for testing the -->
+ <!-- submitted component. -->
+ <!-- Submitted component may include optional specification -->
+ <!-- of CAS Consumer that can be used for testing the -->
+ <!-- submitted component. -->
+
+ <SUBMITTED_COMPONENT>
+ <ID>submitted_component_id</ID>
+ <NAME>Submitted component name</NAME>
+ <DESC>$main_root/desc/ComponentDescriptor.xml</DESC>
+
+ <!-- deployment options: -->
+ <!-- a) "standard" is deploying AE locally -->
+ <!-- b) "service" is deploying AE locally as a service, -->
+ <!-- using specified command (script) -->
+ <!-- c) "network" is deploying a pure network AE, which -->
+ <!-- is running somewhere on the network -->
+
+ <DEPLOYMENT>standard | service | network</DEPLOYMENT>
+
+ <!-- Specifications for "service" deployment option only -->
+ <SERVICE_COMMAND>$main_root/bin/startService.bat</SERVICE_COMMAND>
+ <SERVICE_WORKING_DIR>$main_root</SERVICE_WORKING_DIR>
+ <SERVICE_COMMAND_ARGS>
+
+ <ARGUMENT>
+ <VALUE>1st_parameter_value</VALUE>
+ <COMMENTS>1st parameter description</COMMENTS>
+ </ARGUMENT>
+
+ <ARGUMENT>
+ <VALUE>2nd_parameter_value</VALUE>
+ <COMMENTS>2nd parameter description</COMMENTS>
+ </ARGUMENT>
+
+ </SERVICE_COMMAND_ARGS>
+
+ <!-- Specifications for "network" deployment option only -->
+
+ <NETWORK_PARAMETERS>
+ <VNS_SPECS VNS_HOST="vns_host_IP" VNS_PORT="vns_port_No" />
+ </NETWORK_PARAMETERS>
+
+ <!-- General specifications -->
+
+ <COMMENTS>Main component description</COMMENTS>
+
+ <COLLECTION_READER>
+ <COLLECTION_ITERATOR_DESC>
+ $main_root/desc/CollIterDescriptor.xml
+ </COLLECTION_ITERATOR_DESC>
+
+ <CAS_INITIALIZER_DESC>
+ $main_root/desc/CASInitializerDescriptor.xml
+ </CAS_INITIALIZER_DESC>
+ </COLLECTION_READER>
+
+ <CAS_CONSUMER>
+ <DESC>$main_root/desc/CASConsumerDescriptor.xml</DESC>
+ </CAS_CONSUMER>
+
+ </SUBMITTED_COMPONENT>
+ <!-- Specifications of the component installation process -->
+ <INSTALLATION>
+ <!-- List of delegate components that should be installed together -->
+ <!-- with the main submitted component (for aggregate components) -->
+ <!-- Important: ID element should be the first in each -->
+
+ <!-- DELEGATE_COMPONENT section. -->
+ <DELEGATE_COMPONENT>
+ <ID>first_delegate_component_id</ID>
+ <NAME>Name of first required separate component</NAME>
+ </DELEGATE_COMPONENT>
+
+ <DELEGATE_COMPONENT>
+ <ID>second_delegate_component_id</ID>
+ <NAME>Name of second required separate component</NAME>
+ </DELEGATE_COMPONENT>
+
+ <!-- Specifications of local path names that should be replaced -->
+ <!-- with real path names after the main component as well as -->
+ <!-- all required delegate (library) components are installed. -->
+ <!-- <FILE> and <REPLACE_WITH> values may use the $main_root or -->
+ <!-- one of the $component_id$root variables. -->
+ <!-- Important: ACTION element should be the first in each -->
+ <!-- PROCESS section. -->
+
+ <PROCESS>
+ <ACTION>find_and_replace_path</ACTION>
+ <PARAMETERS>
+ <FILE>$main_root/desc/ComponentDescriptor.xml</FILE>
+ <FIND_STRING>../resources/dict/</FIND_STRING>
+ <REPLACE_WITH>$main_root/resources/dict/</REPLACE_WITH>
+ <COMMENTS>Specify actual dictionary location in XML component
+ descriptor
+ </COMMENTS>
+ </PARAMETERS>
+ </PROCESS>
+
+ <PROCESS>
+ <ACTION>find_and_replace_path</ACTION>
+ <PARAMETERS>
+ <FILE>$main_root/desc/DelegateComponentDescriptor.xml</FILE>
+ <FIND_STRING>
+local_root_directory_for_1st_delegate_component/resources/dict/
+ </FIND_STRING>
+ <REPLACE_WITH>
+ $first_delegate_component_id$root/resources/dict/
+ </REPLACE_WITH>
+ <COMMENTS>
+ Specify actual dictionary location in the descriptor of the 1st
+ delegate component
+ </COMMENTS>
+ </PARAMETERS>
+ </PROCESS>
+
+ <!-- Specifications of environment variables that should be set prior
+ to running the main component and all other reused components.
+ <VAR_VALUE> values may use the $main_root or one of the
+ $component_id$root variables. -->
+
+ <PROCESS>
+ <ACTION>set_env_variable</ACTION>
+ <PARAMETERS>
+ <VAR_NAME>env_variable_name</VAR_NAME>
+ <VAR_VALUE>env_variable_value</VAR_VALUE>
+ <COMMENTS>Set environment variable value</COMMENTS>
+ </PARAMETERS>
+ </PROCESS>
+
+ </INSTALLATION>
+</COMPONENT_INSTALLATION_DESCRIPTOR>]]></programlisting>
+
+ <section id="ugr.ref.pear.installation_descriptor.submitted_component">
+ <title>The SUBMITTED_COMPONENT section</title>
+
+ <para>The SUBMITTED_COMPONENT section of the installation descriptor
+ (install.xml) is used to specify required information about the UIMA component.
+ Before explaining the details, let's clarify the concept of component ID and
+ <quote>macros</quote> used in the installation descriptor. The component ID
+ element should be the <emphasis role="bold">first element </emphasis>in the
+ SUBMITTED_COMPONENT section.</para>
+
+ <para>The component id is a string that uniquely identifies the component. It should
+ use the JAVA naming convention (e.g.
+ com.company_name.project_name.etc.mycomponent).</para>
+
+ <para>Macros are variables such as $main_root, used to represent a string such as the
+ full path of a certain directory.</para>
+
+ <para>The values of these macros are defined by the PEAR installation process, when the
+ PEAR is installed, and represent the values local to that particular installation.
+ The values are stored in the <literal>metadata/PEAR.properties</literal> file that is
+ generated during PEAR installation.
+ The tools and applications that use and deploy PEAR files replace these macros with
+ the corresponding values in the local environment as part of the deployment
+ process in the files included in the conf and desc folders.</para>
+
+ <para>Currently, there are two types of macros:</para>
+
+ <itemizedlist>
+
+ <listitem><para>$main_root, which represents the local absolute
+ path of the main component root directory after deployment. </para></listitem>
+
+ <listitem><para>$<emphasis>component_id</emphasis>$root, which
+ represents the local absolute path to the root directory of the component which
+ has <emphasis>component_id </emphasis> as component ID. This component could
+ be, for instance, a delegate component. </para></listitem></itemizedlist>
+
+ <para>For example, if some part of a descriptor needs to have a path to the data
+ subdirectory of the PEAR, you write <literal>$main_root/data</literal>. If
+ your PEAR refers to a delegate component having the ID
+ <quote><literal>my.comp.Dictionary</literal></quote>, and you need to
+ specify a path to one of this component's subdirectories, e.g.
+ <literal>resource/dict</literal>, you write
+ <literal>$my.comp.Dictionary$root/resources/dict</literal>. </para>
+
+ </section>
+ <section id="ugr.ref.pear.installation_descriptor.id_name_desc">
+ <title>The ID, NAME, and DESC tags</title>
+
+ <para>These tags are used to specify the component ID, Name, and descriptor path
+ using the corresponding tags as follows:
+
+
+ <programlisting><![CDATA[<SUBMITTED_COMPONENT>
+ <ID>submitted_component_id</ID>
+ <NAME>Submitted component name</NAME>
+ <DESC>$main_root/desc/ComponentDescriptor.xml</DESC>]]></programlisting></para>
+
+ </section>
+ <section id="ugr.ref.pear.installation_descriptor.deployment_type">
+ <title>Tags related to deployment types</title>
+
+ <para>As mentioned before, there are currently three types of PEAR packages,
+ depending on the following deployment types</para>
+ <section
+ id="ugr.ref.pear.installation_descriptor.deployment_type.standard">
+ <title>Standard Type</title>
+
+ <para>A component package with the <emphasis role="bold">standard</emphasis>
+ type must be a valid UIMA Analysis Engine, and all the required files to deploy it
+ must be included in the PEAR package. This deployment type should be specified as
+ follows:
+
+
+ <programlisting><![CDATA[<DEPLOYMENT>standard</DEPLOYMENT>]]></programlisting></para>
+ </section>
+ <section
+ id="ugr.ref.pear.installation_descriptor.deployment_type.service">
+ <title>Service Type</title>
+
+ <para>A component package with the <emphasis role="bold">service</emphasis>
+ type must be deployable locally as a supported UIMA service (e.g. Vinci). The
+ installation descriptor must include the path for the executable or script to
+ start the service including its arguments, and the working directory from where
+ to launch it, following this template:
+
+
+ <programlisting><![CDATA[<DEPLOYMENT>service</DEPLOYMENT>
+<SERVICE_COMMAND>$main_root/bin/startService.bat</SERVICE_COMMAND>
+<SERVICE_WORKING_DIR>$main_root</SERVICE_WORKING_DIR>
+<SERVICE_COMMAND_ARGS>
+ <ARGUMENT>
+ <VALUE>1st_parameter_value</VALUE>
+ <COMMENTS>1st parameter description</COMMENTS>
+ </ARGUMENT>
+ <ARGUMENT>
+ <VALUE>2nd_parameter_value</VALUE>
+ <COMMENTS>2nd parameter description</COMMENTS>
+ </ARGUMENT>
+</SERVICE_COMMAND_ARGS>]]></programlisting></para>
+
+ </section>
+ <section
+ id="ugr.ref.pear.installation_descriptor.deployment_type.network">
+ <title>Network Type</title>
+
+ <para>A component package with the network type is not deployed locally, but
+ rather in a <quote>remote</quote> environment. It's accessed as a
+ network AE (e.g. Vinci Service). In this case, the PEAR package does not have to
+ contain files required for deployment, but must contain the network AE
+ descriptor. The <DESC> tag in the installation descriptor (See section
+ 2.3.2.1) must point to the network AE descriptor. Here is a template in the case of
+ Vinci services:
+
+
+ <programlisting><![CDATA[<DEPLOYMENT>network</DEPLOYMENT>
+<NETWORK_PARAMETERS>
+ <VNS_SPECS VNS_HOST="vns_host_IP" VNS_PORT="vns_port_No" />
+</NETWORK_PARAMETERS>]]></programlisting></para>
+ </section>
+ </section>
+ <section
+ id="ugr.ref.pear.installation_descriptor.collection_reader_cas_consumer">
+ <title>The Collection Reader and CAS Consumer tags</title>
+
+ <para>These sections of the installation descriptor are used by any specific
+ Collection Reader or CAS Consumer to be used with the packaged analysis
+ engine.</para>
+
+ </section>
+ <section id="ugr.ref.pear.installation_descriptor.installation">
+ <title>The INSTALLATION section</title>
+
+ <para>The <INSTALLATION> section specifies the external dependencies of
+ the component and the operations that should be performed during the PEAR package
+ installation.</para>
+
+ <para>The component dependencies are specified in the
+ <DELEGATE_COMPONENT> sub-sections, as shown in the installation
+ descriptor template above.</para>
+
+ <para>Important: The ID element should be the first element in each
+ <DELEGATE_COMPONENT> sub-section.</para>
+
+ <para>The <INSTALLATION> section may specify the following operations:
+
+ <itemizedlist><listitem><para>Setting environment variables that are
+ required to run the installed component.
+ </para>
+ <para>This is also how you specify additional classpaths
+ for a Java component - by specifying the setting of an environmental variable
+ named CLASSPATH. The <literal>buildComponentClasspath</literal> method
+ of the PackageBrowser class builds a classpath string from what it finds in
+ the CLASSPATH specification here, plus adds a classpath entry for all
+ Jars in the <literal>lib</literal> directory. Because of this, there is no need
+ to specify Class Path entries for Jars in the lib directory, when using
+ the Eclipse plugin pear packager or the Maven Pear Packager.</para>
+
+ <blockquote><para>When specifying the value of the CLASSPATH environment
+ variable, use the semicolon ";" as the separator character, regardless of the
+ target Operating System conventions. This delimiter will be replaced with
+ the right one for the Operating System during PEAR installation.</para>
+ </blockquote>
+
+ <para>If your component needs to set the UIMA datapath you must specify the necessary
+ datapath setting using an environment variable with the key <literal>uima.datapath</literal>.
+ When such a key is specified the <literal>getComponentDataPath</literal> method of the
+ PackageBrowser class will return the specified datapath settings for your component.
+ </para>
+
+ <warning><para>Do not put UIMA Framework Jars into the lib directory of your
+ PEAR; doing so will cause system failures due to class loading issues.</para></warning>
+ </listitem>
+ <listitem><para>Note that you can use <quote>macros</quote>, like
+ $main_root or $component_id$root in the VAR_VALUE element of the
+ <PARAMETERS> sub-section.</para></listitem>
+
+ <listitem><para>Finding and replacing string expressions in files.</para>
+ </listitem>
+
+ <listitem><para>Note that you can use the <quote>macros</quote> in the FILE
+ and REPLACE_WITH elements of the <PARAMETERS> sub-section. </para>
+ </listitem></itemizedlist></para>
+
+ <para>Important: the ACTION element always should be the 1st element in each
+ <PROCESS> sub-section.</para>
+
+ <para>By default, the PEAR Installer will try to process every file in the desc and
+ conf directories of the PEAR package in order to find the <quote>macros</quote>
+ and replace them with actual path expressions. In addition to this, the installer
+ will process the files specified in the
+ <INSTALLATION> section.</para>
+
+ <para>Important: all XML files which are going to be processed should be created
+ using UTF-8 or UTF-16 file encoding. All other text files which are going to be
+ processed should be created using the ASCII file encoding.</para>
+ </section>
+ </section>
+
+ <section id="ugr.ref.pear.packaging_into_1_file">
+ <title>Packaging the PEAR structure into one file</title>
+
+ <para>The last step of the PEAR process is to simply <emphasis role="bold">
+ zip</emphasis> the content of the PEAR root folder (<emphasis role="bold">not
+ including the root folder itself</emphasis>) to a PEAR file with the extension <quote>.pear</quote>.</para>
+
+ <para>To do this you can either use the PEAR packaging tools that are described in <quote><olink targetdoc="&uima_docs_tools;"
+ targetptr="ugr.tools.pear.packager"/></quote> or you can use the PEAR packaging API that is shown below.</para>
+
+ <para>
+ To use the PEAR packaging API you first have to create the necessary information for the PEAR package:
+ <programlisting> //define PEAR data
+ String componentID = "AnnotComponentID";
+ String mainComponentDesc = "desc/mainComponentDescriptor.xml";
+ String classpath ="$main_root/bin;";
+ String datapath ="$main_root/resources;";
+ String mainComponentRoot = "/home/user/develop/myAnnot";
+ String targetDir = "/home/user/develop";
+ Properties annotatorProperties = new Properties();
+ annotatorProperties.setProperty("sysProperty1", "value1");</programlisting>
+
+ To create a complete PEAR package in one step call:
+ <programlisting>PackageCreator.generatePearPackage(
+ componentID, mainComponentDesc, classpath, datapath,
+ mainComponentRoot, targetDir, annotatorProperties);</programlisting>
+ The created PEAR package has the file name <componentID>.pear and is located in the <targetDir>.
+ </para>
+ <para>
+ To create just the PEAR installation descriptor in the main component root directory call:
+ <programlisting>PackageCreator.createInstallDescriptor(componentID, mainComponentDesc,
+ classpath, datapath, mainComponentRoot, annotatorProperties);</programlisting>
+
+ To package a PEAR file with an existing installation descriptor call:
+ <programlisting>PackageCreator.createPearPackage(componentID, mainComponentRoot,
+ targetDir);</programlisting>
+ The created PEAR package has the file name <componentID>.pear and is located in the <targetDir>.
+ </para>
+
+ </section>
+ </section>
+ <section id="ugr.ref.pear.installing">
+ <title>Installing a PEAR package</title>
+
+ <para>The installation of a PEAR package can be done using
+ the PEAR installer tool (see <olink targetdoc="&uima_docs_tools;"
+ targetptr="ugr.tools.pear.installer"/>, or by an application using
+ the PEAR APIs, directly. </para>
+
+ <para>During the PEAR installation the PEAR file is extracted to the installation directory and the PEAR macros
+ in the descriptors are updated with the corresponding path. At the end of the installation the PEAR verification
+ is called to check if the installed PEAR package can be started successfully. The PEAR verification use the classpath,
+ datapath and the system property settings of the PEAR package to verify the PEAR content. Necessary Java library
+ path settings for native libararies, PATH variable settings or system environment variables cannot be recognized
+ automatically and the use must take care of that manually.</para>
+
+ <note><para>By default the PEAR packages are not installed directly to the specified installation directory. For each PEAR
+ a subdirectory with the name of the PEAR's ID is created where the PEAR package is installed to. If the PEAR installation
+ directory already exists, the old content is automatically deleted before the new content is installed.</para></note>
+
+ <section id="ugr.ref.pear.installing_pear_using_API">
+ <title>Installing a PEAR file using the PEAR APIs</title>
+
+ <para>The example below shows how to use the PEAR APIs to install a
+ PEAR package and access the installed PEAR package data. For more details about the PackageBrowser API,
+ please refer to the Javadocs for the org.apache.uima.pear.tools package.
+
+ <programlisting>File installDir = new File("/home/user/uimaApp/installedPears");
+File pearFile = new File("/home/user/uimaApp/testpear.pear");
+boolean doVerification = true;
+
+try {
+ // install PEAR package
+ PackageBrowser instPear = PackageInstaller.installPackage(
+ installDir, pearFile, doVerification);
+
+ // retrieve installed PEAR data
+ // PEAR package classpath
+ String classpath = instPear.buildComponentClassPath();
+ // PEAR package datapath
+ String datapath = instPear.getComponentDataPath();
+ // PEAR package main component descriptor
+ String mainComponentDescriptor = instPear
+ .getInstallationDescriptor().getMainComponentDesc();
+ // PEAR package component ID
+ String mainComponentID = instPear
+ .getInstallationDescriptor().getMainComponentId();
+ // PEAR package pear descriptor
+ String pearDescPath = instPear.getComponentPearDescPath();
+
+ // print out settings
+ System.out.println("PEAR package class path: " + classpath);
+ System.out.println("PEAR package datapath: " + datapath);
+ System.out.println("PEAR package mainComponentDescriptor: "
+ + mainComponentDescriptor);
+ System.out.println("PEAR package mainComponentID: "
+ + mainComponentID);
+ System.out.println("PEAR package specifier path: " + pearDescPath);
+
+ } catch (PackageInstallerException ex) {
+ // catch PackageInstallerException - PEAR installation failed
+ ex.printStackTrace();
+ System.out.println("PEAR installation failed");
+ } catch (IOException ex) {
+ ex.printStackTrace();
+ System.out.println("Error retrieving installed PEAR settings");
+ }</programlisting></para>
+
+ <para>
+ To run a PEAR package after it was installed using the PEAR API see the example below. It use the
+ generated PEAR specifier that was automatically created during the PEAR installation.
+ For more details about the APIs please refer to the Javadocs.
+
+
+ <programlisting>File installDir = new File("/home/user/uimaApp/installedPears");
+File pearFile = new File("/home/user/uimaApp/testpear.pear");
+boolean doVerification = true;
+
+try {
+
+ // Install PEAR package
+ PackageBrowser instPear = PackageInstaller.installPackage(
+ installDir, pearFile, doVerification);
+
+ // Create a default resouce manager
+ ResourceManager rsrcMgr = UIMAFramework.newDefaultResourceManager();
+
+ // Create analysis engine from the installed PEAR package using
+ // the created PEAR specifier
+ XMLInputSource in =
+ new XMLInputSource(instPear.getComponentPearDescPath());
+ ResourceSpecifier specifier =
+ UIMAFramework.getXMLParser().parseResourceSpecifier(in);
+ AnalysisEngine ae =
+ UIMAFramework.produceAnalysisEngine(specifier, rsrcMgr, null);
+
+ // Create a CAS with a sample document text
+ CAS cas = ae.newCAS();
+ cas.setDocumentText("Sample text to process");
+ cas.setDocumentLanguage("en");
+
+ // Process the sample document
+ ae.process(cas);
+ } catch (Exception ex) {
+ ex.printStackTrace();
+ }</programlisting></para>
+
+ </section>
+
+ </section>
+
+ <section id="ugr.ref.pear.specifier">
+ <title>PEAR package descriptor</title>
+
+ <para>
+ To run an installed PEAR package directly in the UIMA framework the <literal>pearSpecifier</literal>
+ XML descriptor can be used. Typically during the PEAR installation such an specifier is automatically generated
+ and contains all the necessary information to run the installed PEAR package. Settings for system environment
+ variables, system PATH settings or Java library path settings cannot be recognized
+ automatically and must be set manually when the JVM is started.
+ </para>
+
+ <note><para>The PEAR may contain specifications for "environment variables" and their settings.
+ When such a PEAR is run
+ directly in the UIMA framework, those settings (except for Classpath and Data Path) are converted
+ to Java System properties, and set to the specified values. Java cannot set true environmental variables;
+ if such a setting is needed, the application would need to arrange to do this prior to invoking Java.</para>
+
+ <para>The Classpath and Data Path settings are used by UIMA to configure a special Resource Manager
+ that is used when code from this PEAR is being run.</para></note>
+
+ <para>
+ The generated PEAR descriptor
+ is located in the component root directory of the installed PEAR package and has a filename like
+ <componentID>_pear.xml.
+ </para>
+ <para>
+ The PEAR package descriptor looks like:
+ </para>
+ <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<pearSpecifier xmlns="http://uima.apache.org/resourceSpecifier">
+ <pearPath>/home/user/uimaApp/installedPears/testpear</pearPath>
+</pearSpecifier>]]></programlisting>
+ <para>
+ The <literal>pearPath</literal> setting in the descriptor must point to the component root directory
+ of the installed PEAR package.
+ </para>
+ <note>
+ <!--para> should now be possible (11/2008)
+ When a PEAR descriptor is used within an aggregate AE as primitive AE, it is not possible to
+ override the PEAR AE configuration parameter settings with the aggregate AE descriptor.
+ </para-->
+ <para>
+ It is not possible to share resources between PEAR Analysis Engines that are instantiated using the PEAR
+ descriptor. The PEAR runtime created for each PEAR descriptor has its own specific ResourceManager
+ (unless exactly the same Classpath and Data Path are being used).
+ </para>
+ </note>
+ </section>
+
+</chapter>
\ No newline at end of file