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 2006/12/03 22:46:51 UTC

svn commit: r481929 [2/4] - in /incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references: ./ ref.cas.xml ref.jcas.xml ref.pear.xml ref.xmi.xml ref.xml.component_descriptor.xml ref.xml.cpe_descriptor.xml reference.xml

Added: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.pear.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.pear.xml?view=auto&rev=481929
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.pear.xml (added)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.pear.xml Sun Dec  3 13:46:49 2006
@@ -0,0 +1,571 @@
+<?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/annotator_analysis_engine_files/" >
+<!ENTITY % uimaents SYSTEM "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></title>
+  <section name="PEAR Reference"><a id="_crossRef259"> </a>
+
+
+
+
+
+<para>A PEAR (Processing Engine ARchive) file is a standard
+package for UIMA (Unstructured Information Management Architecture)
+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, the PEAR Eclipse Plugin is available as a tool
+to create PEAR files for standard UIMA components. Please refer to <a class="crossrefText" href="PEAR_Packager.htm#_crossRef251">Chapter 14, <b>PEAR Packager
+User&apos;s Guide</b></a> for more information about this tool.</para>
+
+
+
+<subsection name="Packaging a UIMA component"><a id="_crossRef261"> </a>
+
+
+
+<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:</para>
+
+<itemizedlist><listitem><a class="crossrefText" href="PEAR_Reference.htm#_crossRef262">Creating
+the PEAR structure</a></listitem>
+
+
+<listitem><a class="crossrefText" href="PEAR_Reference.htm#_crossRef263">Populating
+the PEAR structure</a></listitem>
+
+
+<listitem><a class="crossrefText" href="PEAR_Reference.htm#_crossRef267">Creating
+the installation descriptor</a></listitem>
+
+
+<listitem><a class="crossrefText" href="PEAR_Reference.htm#_crossRef271">Packaging
+the PEAR structure into one file</a>
+</listitem></itemizedlist>
+
+
+
+<h3><a id="_crossRef262">Creating the PEAR structure</a></h3>
+
+<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:</para>
+
+<itemizedlist><listitem>Required Elements:
+
+
+<itemizedlist><listitem>The <b>metadata</b> folder which contains the PEAR installation
+descriptor and properties files.</listitem>
+
+
+<listitem>The installation descriptor (<b>metadata/install.xml</b>)  </listitem>
+
+
+<listitem>A UIMA analysis engine descriptor
+and its required code, delegates (if any), and resources
+</listitem></itemizedlist></listitem>
+
+
+<listitem>Optional Elements:
+
+
+<itemizedlist><listitem>The desc folder to contain
+descriptor files of analysis engines, delegates analysis engines (all levels),
+and other components (Collection Readers, CAS Consumers, etc).</listitem>
+
+
+<listitem>The src folder to contain the
+source code</listitem>
+
+
+<listitem>The bin folder to contain
+executables, scripts, class files, dlls, shared libraries, etc. </listitem>
+
+
+<listitem>The lib folder to contain jar
+files. </listitem>
+
+
+<listitem>The doc folder containing
+documentation materials, preferably accessible through an index.html.</listitem>
+
+
+<listitem>The data folder to contain data
+files (e.g. for testing).</listitem>
+
+
+<listitem>The conf folder to contain
+configuration files.</listitem>
+
+
+<listitem>The resources folder to contain
+other resources and dependencies.</listitem>
+
+
+<listitem>Other user-defined folders or
+files are allowed, but should be avoided.
+</listitem></itemizedlist>
+</listitem></itemizedlist>
+
+<para><img alt="" width="303" height="394"
+src="../UIMA_SDK_Guide_Ref/PEAR_Reference_files/image002.jpg"/></para>
+
+<a class="figCaption" id="_crossRef254">The PEAR Structure</a>
+
+<h3><a id="_crossRef263">Populating the PEAR structure</a></h3>
+
+<para>After creating the PEAR structure, the component&apos;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>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)
+</listitem></itemizedlist>
+
+<para>Currently there are three types of component packages
+depending on their deployment:</para>
+
+<h4><a id="_crossRef264">Standard type</a></h4>
+
+<para>A component package with the <b>standard</b> type must be
+a valid Analysis Engine, and all the required files to deploy it locally must
+be included in the PEAR package.</para>
+
+<h4><a id="_crossRef265">Service type</a></h4>
+
+<para>A component package with the <b>service </b>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>
+
+<h4><a id="_crossRef266">Network Type</a></h4>
+
+<para>A component package with the network type is not deployed
+locally but rather in the <quote>remote</quote> environment. It&apos;s accessed as a
+network AE (e.g. Vinci Service). The component owner has the responsibility to
+start the service and make sure it&apos;s up and running before it&apos;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 <a class="crossrefText" href="Annotator_and_Analysis_Engine_Developers_Guide.htm#_crossRef7">4.1.4, <b>Creating the XML
+Descriptor</b></a>) and the &lt;DESC&gt; tag in the installation
+descriptor must point to the network TAE descriptor. For more information about
+Network Analysis Engines, please refer to <emphasis>Section </emphasis><a class="crossrefText" href="Application_Developers_Guide.htm#_crossRef64">6.6, <b>Working with Analysis
+Engine and CAS Consumer Services</b></a>.</para>
+
+<h3><a id="_crossRef267">Creating the installation
+descriptor</a></h3>
+
+<para>The installation descriptor is an xml file called
+install.xml under the metadata folder of the PEAR structure. It&apos;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>&lt;OS&gt;:  This section is used to specify supported
+operating systems</listitem>
+
+
+<listitem>&lt;TOOLKITS&gt;: This section is
+used to specify toolkits, such as JDK, needed by the component.</listitem>
+
+
+<listitem>&lt;SUBMITTED_COMPONENT&gt;: This
+is the most important section in the InsD. It&apos;s used to specify required
+information about the component. See section 2.3.2 for detailed information
+about this section.</listitem>
+
+
+<listitem>&lt;INSTALLATION&gt;: This section
+is explained in section <a class="crossrefText" href="PEAR_Reference.htm#_crossRef272">29.1.5
+</a>.
+</listitem></itemizedlist>
+
+<h4><a id="_crossRef268">Documented template for the installation descriptor:</a></h4>
+
+<para>The following is <quote>documented template</quote> for the
+content of the installation descriptor install.xml:</para>
+
+<programlisting>&lt;? xml version=<quote>1.0</quote> encoding=<quote>UTF-8</quote>?&gt;
+&lt;!-- Installation Descriptor Template --&gt;
+&lt;COMPONENT_INSTALLATION_DESCRIPTOR&gt;
+  &lt;!-- Specifications of OS names, including version, etc. --&gt;
+  &lt;OS&gt;
+    &lt;NAME&gt;OS_Name_1&lt;/NAME&gt;
+    &lt;NAME&gt;OS_Name_2&lt;/NAME&gt;
+  &lt;/OS&gt;
+  &lt;!-- Specifications of required standard toolkits --&gt;
+  &lt;TOOLKITS&gt;
+    &lt;JDK_VERSION&gt;JDK_Version&lt;/JDK_VERSION&gt;
+  &lt;/TOOLKITS&gt;</programlisting>
+
+<programlisting>  &lt;!-- 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 --&gt;</programlisting>
+
+<programlisting>  &lt;!-- Specification of submitted component (TAE)             --&gt;
+  &lt;!-- Note: submitted_component_id is assigned by developer; --&gt;
+  &lt;!--       XML descriptor file name is set by developer.    --&gt;
+  &lt;!-- Important: ID element should be the first in the       --&gt;
+  &lt;!--            SUBMITTED_COMPONENT section.                --&gt;
+  &lt;!-- Submitted component may include optional specification --&gt;
+  &lt;!-- of Collection Reader that can be used for testing the  --&gt;
+  &lt;!-- submitted component.                                   --&gt;
+  &lt;!-- Submitted component may include optional specification --&gt;
+  &lt;!-- of CAS Consumer that can be used for testing the       --&gt;
+  &lt;!-- submitted component.                                   --&gt;</programlisting>
+
+<programlisting>  &lt;SUBMITTED_COMPONENT&gt;
+    &lt;ID&gt;submitted_component_id&lt;/ID&gt;
+    &lt;NAME&gt;Submitted component name&lt;/NAME&gt;
+    &lt;DESC&gt;$main_root/desc/ComponentDescriptor.xml&lt;/DESC&gt;</programlisting>
+
+<programlisting>    &lt;!-- deployment options:                                   --&gt;
+    &lt;!-- a) ©standard© is deploying AE locally                 --&gt;
+    &lt;!-- b) ©service©  is deploying AE locally as a service,   --&gt;
+    &lt;!--    using specified command (script)                   --&gt;
+    &lt;!-- c) ©network©  is deploying a pure network AE, which   --&gt;
+    &lt;!--    is running somewhere on the network                --&gt;</programlisting>
+
+<programlisting>    &lt;DEPLOYMENT&gt;standard | service | network&lt;/DEPLOYMENT&gt;</programlisting>
+
+<programlisting>    &lt;!-- Specifications for ©service© deployment option only   --&gt;
+    &lt;SERVICE_COMMAND&gt;$main_root/bin/startService.bat&lt;/SERVICE_COMMAND&gt;
+    &lt;SERVICE_WORKING_DIR&gt;$main_root&lt;/SERVICE_WORKING_DIR&gt;
+    &lt;SERVICE_COMMAND_ARGS&gt;</programlisting>
+
+<programlisting>      &lt;ARGUMENT&gt;
+        &lt;VALUE&gt;1st_parameter_value&lt;/VALUE&gt;
+        &lt;COMMENTS&gt;1st parameter description&lt;/COMMENTS&gt;
+      &lt;/ARGUMENT&gt;</programlisting>
+
+<programlisting>      &lt;ARGUMENT&gt;
+        &lt;VALUE&gt;2nd_parameter_value&lt;/VALUE&gt;
+        &lt;COMMENTS&gt;2nd parameter description&lt;/COMMENTS&gt;
+      &lt;/ARGUMENT&gt;</programlisting>
+
+<programlisting>    &lt;/SERVICE_COMMAND_ARGS&gt;</programlisting>
+
+<programlisting>    &lt;!-- Specifications for ©network© deployment option only   --&gt;</programlisting>
+
+<programlisting>    &lt;NETWORK_PARAMETERS&gt;
+      &lt;VNS_SPECS VNS_HOST=<quote>vns_host_IP</quote> VNS_PORT=<quote>vns_port_No</quote> /&gt;
+    &lt;/NETWORK_PARAMETERS&gt;</programlisting>
+
+<programlisting>    &lt;!-- General specifications                                --&gt;</programlisting>
+
+<programlisting>    &lt;COMMENTS&gt;Main component description&lt;/COMMENTS&gt;</programlisting>
+
+<programlisting>    &lt;COLLECTION_READER&gt;
+      &lt;COLLECTION_ITERATOR_DESC&gt;
+        $main_root/desc/CollIterDescriptor.xml
+      &lt;/COLLECTION_ITERATOR_DESC&gt;</programlisting>
+
+<programlisting>      &lt;CAS_INITIALIZER_DESC&gt;
+        $main_root/desc/CASInitializerDescriptor.xml
+      &lt;/CAS_INITIALIZER_DESC&gt;
+    &lt;/COLLECTION_READER&gt;</programlisting>
+
+<programlisting>    &lt;CAS_CONSUMER&gt;
+      &lt;DESC&gt;$main_root/desc/CASConsumerDescriptor.xml&lt;/DESC&gt;
+    &lt;/CAS_CONSUMER&gt;</programlisting>
+
+<programlisting>  &lt;/SUBMITTED_COMPONENT&gt;
+  &lt;!-- Specifications of the component installation process --&gt;
+  &lt;INSTALLATION&gt;
+    &lt;!-- List of delegate components that should be installed together --&gt;
+    &lt;!-- with the main submitted component (for aggregate components)  --&gt;
+    &lt;!-- Important: ID element should be the first in each             --&gt;</programlisting>
+
+<programlisting>    &lt;!--            DELEGATE_COMPONENT section.                        --&gt;
+    &lt;DELEGATE_COMPONENT&gt;
+      &lt;ID&gt;first_delegate_component_id&lt;/ID&gt;
+      &lt;NAME&gt;Name of first required separate component&lt;/NAME&gt;
+    &lt;/DELEGATE_COMPONENT&gt;</programlisting>
+
+<programlisting>    &lt;DELEGATE_COMPONENT&gt;
+      &lt;ID&gt;second_delegate_component_id&lt;/ID&gt;
+      &lt;NAME&gt;Name of second required separate component&lt;/NAME&gt;
+    &lt;/DELEGATE_COMPONENT&gt;</programlisting>
+
+<programlisting>    &lt;!-- Specifications of local path names that should be replaced --&gt;
+    &lt;!-- with real path names after the main component as well as   --&gt;
+    &lt;!-- all required delegate (library) components are installed.  --&gt;
+    &lt;!-- &lt;FILE&gt; and &lt;REPLACE_WITH&gt; values may use the $main_root or --&gt;
+    &lt;!-- one of the $component_id$root variables.                   --&gt;
+    &lt;!-- Important: ACTION element should be the first in each      --&gt;
+    &lt;!--            PROCESS section.                                --&gt;</programlisting>
+
+<programlisting>    &lt;PROCESS&gt;
+      &lt;ACTION&gt;find_and_replace_path&lt;/ACTION&gt;
+      &lt;PARAMETERS&gt;
+        &lt;FILE&gt;$main_root/desc/ComponentDescriptor.xml&lt;/FILE&gt;
+        &lt;FIND_STRING&gt;../resources/dict/&lt;/FIND_STRING&gt;
+        &lt;REPLACE_WITH&gt;$main_root/resources/dict/&lt;/REPLACE_WITH&gt;
+        &lt;COMMENTS&gt;Specify actual dictionary location in XML component
+          descriptor
+        &lt;/COMMENTS&gt;
+      &lt;/PARAMETERS&gt;
+    &lt;/PROCESS&gt;</programlisting>
+
+<programlisting>    &lt;PROCESS&gt;
+      &lt;ACTION&gt;find_and_replace_path&lt;/ACTION&gt;
+      &lt;PARAMETERS&gt;
+        &lt;FILE&gt;$main_root/desc/DelegateComponentDescriptor.xml&lt;/FILE&gt;
+        &lt;FIND_STRING&gt;
+local_root_directory_for_1st_delegate_component/resources/dict/
+        &lt;/FIND_STRING&gt;
+        &lt;REPLACE_WITH&gt;
+          $first_delegate_component_id$root/resources/dict/
+        &lt;/REPLACE_WITH&gt;
+        &lt;COMMENTS&gt;
+          Specify actual dictionary location in the descriptor of the 1<sup>st
+</sup>          delegate component
+        &lt;/COMMENTS&gt;
+      &lt;/PARAMETERS&gt;
+    &lt;/PROCESS&gt;</programlisting>
+
+<programlisting>    &lt;!-- Specifications of environment variables that should be set prior
+         to running the main component and all other reused components.
+         &lt;VAR_VALUE&gt; values may use the $main_root or one of the
+         $component_id$root variables. --&gt;</programlisting>
+
+<programlisting>    &lt;PROCESS&gt;
+      &lt;ACTION&gt;set_env_variable&lt;/ACTION&gt;
+      &lt;PARAMETERS&gt;
+        &lt;VAR_NAME&gt;env_variable_name&lt;/VAR_NAME&gt;
+        &lt;VAR_VALUE&gt;env_variable_value&lt;/VAR_VALUE&gt;
+        &lt;COMMENTS&gt;Set environment variable value&lt;/COMMENTS&gt;
+      &lt;/PARAMETERS&gt;
+    &lt;/PROCESS&gt;</programlisting>
+
+<programlisting>  &lt;/INSTALLATION&gt;
+&lt;/COMPONENT_INSTALLATION_DESCRIPTOR&gt;</programlisting>
+
+<h4><a id="_crossRef269">The SUBMITTED_COMPONENT section</a></h4>
+
+<para>The SUBMITTED_COMPONENT section of the installation
+descriptor (install.xml) is the most important. It&apos;s used to specify required
+information about the UIMA component. Before explaining the details, let&apos;s
+clarify the concept of component ID and <quote>macros</quote> used in the
+installation descriptor. The component ID element should be the <b>first
+element </b>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.
+ibm.uima.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>These macros should be defined in the PEAR.properties file
+using the local values. The tools and applications that use and deploy PEAR
+files should 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>$main_root, which represents the
+local absolute path of the main component root directory after deployment. </listitem>
+
+
+<listitem>$<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.
+</listitem></itemizedlist>
+
+<para>For example, if some part of a descriptor needed to have a
+path to the data subdirectory of the PEAR, you would 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&apos;s subdirectories, say <literal>resource/dict</literal>,
+you would write <literal>$my.comp.Dictionary$root/resources/dict</literal>.
+</para>
+
+<h4><emphasis>The ID, NAME, and DESC tags</emphasis></h4>
+
+<para>These tags are used to specify the component ID, Name, and
+descriptor path using the corresponding tags as follows:</para>
+
+<programlisting>&lt;SUBMITTED_COMPONENT&gt;</programlisting>
+
+<programlisting>  &lt;ID&gt;submitted_component_id&lt;/ID&gt;</programlisting>
+
+<programlisting>  &lt;NAME&gt;Submitted component name&lt;/NAME&gt;</programlisting>
+
+<programlisting>  &lt;DESC&gt;$main_root/desc/ComponentDescriptor.xml&lt;/DESC&gt;</programlisting>
+
+<h4><emphasis>Tags related to deployment types</emphasis></h4>
+
+<para>As mentioned before, there are currently three types of
+PEAR packages, depending on the following deployment types:</para>
+
+<para><b>Standard type</b></para>
+
+<para>A component package with the <b>standard</b> 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:</para>
+
+<programlisting>&lt;DEPLOYMENT&gt;standard&lt;/DEPLOYMENT&gt; </programlisting>
+
+<para><b>Service type</b></para>
+
+<para>A component package with the <b>service </b>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:</para>
+
+<programlisting>&lt;DEPLOYMENT&gt;service&lt;/DEPLOYMENT&gt;</programlisting>
+
+<programlisting>&lt;SERVICE_COMMAND&gt;$main_root/bin/startService.bat&lt;/SERVICE_COMMAND&gt;</programlisting>
+
+<programlisting>&lt;SERVICE_WORKING_DIR&gt;$main_root&lt;/SERVICE_WORKING_DIR&gt;</programlisting>
+
+<programlisting>&lt;SERVICE_COMMAND_ARGS&gt;</programlisting>
+
+<programlisting>&lt;ARGUMENT&gt;</programlisting>
+
+<programlisting>&lt;VALUE&gt;1st_parameter_value&lt;/VALUE&gt;</programlisting>
+
+<programlisting>&lt;COMMENTS&gt;1st parameter description&lt;/COMMENTS&gt;</programlisting>
+
+<programlisting>&lt;/ARGUMENT&gt;</programlisting>
+
+<programlisting>&lt;ARGUMENT&gt;</programlisting>
+
+<programlisting>&lt;VALUE&gt;2nd_parameter_value&lt;/VALUE&gt;</programlisting>
+
+<programlisting>&lt;COMMENTS&gt;2nd parameter description&lt;/COMMENTS&gt;</programlisting>
+
+<programlisting>&lt;/ARGUMENT&gt;</programlisting>
+
+<programlisting>&lt;/SERVICE_COMMAND_ARGS&gt;</programlisting>
+
+<para><b>Network Type</b></para>
+
+<para>A component package with the network type is not deployed
+locally, but rather in a <quote>remote</quote> environment. It&apos;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 &lt;DESC&gt; 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:</para>
+
+<programlisting>&lt;DEPLOYMENT&gt;network&lt;/DEPLOYMENT&gt;</programlisting>
+
+<programlisting>&lt;NETWORK_PARAMETERS&gt;</programlisting>
+
+<programlisting>&lt;VNS_SPECS VNS_HOST=<quote>vns_host_IP</quote> VNS_PORT=<quote>vns_port_No</quote> /&gt;</programlisting>
+
+<programlisting>&lt;/NETWORK_PARAMETERS&gt;</programlisting>
+
+<h4><emphasis>The Collection Reader and CAS Consumer tags</emphasis></h4>
+
+<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. See the template in section 2.3.1.</para>
+
+<h4><a id="_crossRef270">The INSTALLATION section</a></h4>
+
+<para>The &lt;INSTALLATION&gt; 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
+&lt;DELEGATE_COMPONENT&gt; sub-sections, as shown in the installation
+descriptor template above.</para>
+
+<para>Important: The ID element should be the first element in
+each &lt;DELEGATE_COMPONENT&gt; sub-section.</para>
+
+<para>The &lt;INSTALLATION&gt; section may specify the following
+operations:</para>
+
+<itemizedlist><listitem>Setting environment variables that
+are required to run the installed component.</listitem>
+
+
+<listitem>Note that you can use <quote>macros</quote>, like $main_root or
+$component_id$root in the VAR_VALUE element of the &lt;PARAMETERS&gt;
+sub-section.</listitem>
+
+
+<listitem>Finding and replacing string
+expressions in files.</listitem>
+
+
+<listitem>Note that you can use the <quote>macros</quote> in the FILE and
+REPLACE_WITH elements of the &lt;PARAMETERS&gt; sub-section.
+</listitem></itemizedlist>
+
+<para>Important: the ACTION element always should be the 1st element
+in each &lt;PROCESS&gt; 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
+&lt;INSTALLATION&gt; 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>
+
+<h3><a id="_crossRef271">Packaging the PEAR structure into
+one file</a></h3>
+
+<para>The last step of the PEAR process is to simply <b>zip</b>
+the content of the PEAR root folder (<b>not including the root folder itself</b>).
+The PEAR file must have a <quote>.pear</quote> extension.</para>
+
+<h3><a id="_crossRef272">Installing a PEAR file</a></h3>
+
+<para>For information about the installation of a PEAR file and
+the PEAR Installer tool, please refer to the <quote>PEAR Installer</quote>
+Chapter.</para>
+</chapter>
\ No newline at end of file

Added: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.xmi.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.xmi.xml?view=auto&rev=481929
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.xmi.xml (added)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.xmi.xml Sun Dec  3 13:46:49 2006
@@ -0,0 +1,393 @@
+<?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/annotator_analysis_engine_files/" >
+<!ENTITY % uimaents SYSTEM "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.xmi">
+  <title></title>
+  <section name="XMI CAS Serialization Reference"><a id="_crossRef386"> </a>
+
+
+
+<para>This is the specification for the mapping of the UIMA CAS
+into the XMI (XML Metadata Interchange<span class="footnote">
+
+For details on XMI see Grose et al. <emphasis>Mastering
+XMI.  Java Programming with XMI, XML, and
+UML. </emphasis>John Wiley &amp; Sons, Inc. 2002.
+
+</span>)
+format.  XMI is an OMG standard for
+expressing object graphs in XML.  The
+UIMA SDK provides support for XMI through the classes
+org.apache.uima.cas.impl.XmiCasSerializer and
+org.apache.uima.cas.impl.XmiCasDeserializer.</para>
+
+
+
+<subsection name="XMI Tag"><a id="_crossRef387"> </a>
+
+
+
+<para>The outermost tag is &lt;XMI&gt; and must include a
+version number and XML namespace attribute:</para>
+
+<programlisting>&lt;xmi:XMI xmi:version=<quote>2.0</quote> xmlns:xmi=<a href="http://www.omg.org/XMI">http://www.omg.org/XMI</a>&gt;
+  &lt;!-- CAS Contents here --&gt;
+&lt;/xmi:XMI&gt;</programlisting>
+
+<para>XML namespaces<span class="footnote">http://www.w3.org/TR/xml-names11/</span> are used throughout.  The <quote>xmi</quote> namespace prefix is used to identify elements and
+attributes that are defined by the XMI specification.  The XMI document will also define one
+namespace prefix for each CAS namespace, as described in the next section.</para>
+
+
+
+
+  </subsection>
+<subsection name="Feature Structures"><a id="_crossRef388"> </a>
+
+
+
+<para>UIMA Feature Structures are mapped to XML elements.  The name of the element is formed from the
+CAS type name, making use of XML namespaces as follows.</para>
+
+<para>The CAS type namespace is converted to an XML namespace
+URI by the following rule: replace all dots with slashes, prepend http:///, and
+append .ecore.</para>
+
+<para>This mapping was chosen because it is the default mapping
+used by the Eclipse Modeling Framework (EMF)<span class="footnote">
+For details on EMF and Ecore see Budinsky et al.  <emphasis>Eclipse
+Modeling Framework 2.0</emphasis>. Addison-Wesley. 2006.
+</span> to
+create namespace URIs from Java package names.  The use of the http scheme is a common convention, and does not imply
+any HTTP communication.  The .ecore
+suffix is due to the fact that the recommended type system definition for a
+namespace is an ECore model, see <b><a class="crossrefText" href="XMI_and_EMF_Interoperability.htm#_crossRef382">XMI
+and EMF Interoperability</a></b> <a class="crossrefPage" href="XMI_and_EMF_Interoperability.htm#_crossRef382"></a>.</para>
+
+<para>Consider the CAS type name
+<quote>org.myproj.Foo</quote>.   The CAS
+namespace (<quote>org.myorg.</quote>) is converted to the XML namespace URI is
+http:///org/myproj.ecore.</para>
+
+<para>The XML element name is then formed by concatenating the
+XML namespace prefix (which is an arbitrary token, but typically we use the
+last component of the CAS namespace) with the type name (excluding the
+namespace).</para>
+
+<para>So the example <quote>org.myproj.Foo</quote> FeatureStructure
+is written to XMI as:</para>
+
+<programlisting>&lt;xmi:XMI xmi:version=<quote>2.0</quote> xmlns:xmi=<quote><a href="http://www.omg.org/XMI">http://www.omg.org/XMI</a></quote>  xmlns:myproj=<quote>http:///org/myproj.ecore</quote>&gt;
+  ...
+  &lt;myproj:Foo xmi:id=<quote>1</quote>/&gt;
+  ...
+&lt;/xmi:XMI&gt;</programlisting>
+
+<para>The xmi:id attribute is only required if this object will
+be referred to from elsewhere in the XMI document.  If provided, the xmi:id must be unique for
+each feature.</para>
+
+<para>All namespace prefixes (e.g. <quote>myproj</quote>) in this
+example must be bound to URIs using the <quote>xmlns...</quote> attribute, as
+defined by the XML namespaces specification.</para>
+
+
+
+
+  </subsection>
+<subsection name="Primitive Features"><a id="_crossRef389"> </a>
+
+
+
+<para>CAS features of primitive types (currently String,
+Integer, or Float, but others are possible) can be mapped either to XML
+attributes or XML elements.  For example,
+a CAS FeatureStructure of type org.myproj.Foo, with features:</para>
+
+<programlisting>begin   = 14
+end     = 19
+myFeature = <quote>bar</quote></programlisting>
+
+<para>could be mapped to:</para>
+
+<programlisting>&lt;xmi:XMI xmi:version=<quote>2.0</quote> xmlns:xmi=<quote><a href="http://www.omg.org/XMI">http://www.omg.org/XMI</a></quote>
+  xmlns:myproj=<quote>http:///org/myproj.ecore</quote>&gt;
+  ...
+  &lt;myproj:Foo xmi:id=<quote>1</quote> begin=<quote>14</quote> end=<quote>19</quote> myFeature=<quote>bar</quote>/&gt;
+  ...
+&lt;/xmi:XMI&gt;</programlisting>
+
+<para>or equivalently:</para>
+
+<programlisting>&lt;xmi:XMI xmi:version=<quote>2.0</quote> xmlns:xmi=<quote><a href="http://www.omg.org/XMI">http://www.omg.org/XMI</a>
+  xmlns:myproj=</quote>http:///org/myproj.ecore<quote>&gt;
+  ...
+  &lt;myproj:Foo xmi:id=</quote>1<quote>&gt;
+    &lt;begin&gt;14&lt;/begin&gt;
+    &lt;end&gt;19&lt;/end&gt;
+    &lt;myFeature&gt;bar&lt;/myFeature&gt;
+  &lt;/myproj:Foo&gt;
+  ...
+&lt;/xmi:XMI&gt;</programlisting>
+
+<para>The attribute serialization is preferred for compactness,
+but either representation is allowable.  Mixing the two styles is allowed; some features can be represented as
+attributes and others as elements.</para>
+
+
+
+
+  </subsection>
+<subsection name="Reference Features"><a id="_crossRef390"> </a>
+
+
+
+<para>CAS features that are references to other feature
+structures (excluding arrays and lists, which are handled separately) are
+serialized as ID references.</para>
+
+<para>If we add to the previous CAS example a feature structure
+of type org.myproj.Baz, with feature </quote>myFoo<quote> that is a reference to
+the Foo object, the serialization would be:</para>
+
+<programlisting>&lt;xmi:XMI xmi:version=</quote>2.0<quote> xmlns:xmi=</quote><a href="http://www.omg.org/XMI"><literal>http://www.omg.org/XMI</literal></a><quote>
+  xmlns:myproj=</quote>http:///org/myproj.ecore<quote>&gt;
+  ...
+  &lt;myproj:Foo xmi:id=</quote>1<quote> begin=</quote>14<quote> end=</quote>19<quote> myFeature=</quote>bar<quote>/&gt;
+  &lt;myproj:Baz xmi:id=</quote>2<quote> myFoo=</quote>1<quote>/&gt;
+  ...
+&lt;/xmi:XMI&gt;</programlisting>
+
+<para>As with primitive-valued features, it is permitted to use
+an element rather than an attribute.  However, the syntax is slightly different:</para>
+
+<programlisting>&lt;myproj:Baz xmi:id=</quote>2<quote>&gt;
+   &lt;myFoo href=</quote>#1<quote>/&gt;
+&lt;myproj.Baz&gt;</programlisting>
+
+<para>Note that in the attribute representation, a reference
+feature is indistinguishable from an integer-valued feature, so the meaning
+cannot be determined without prior knowledge of the type system.  The element representation is unambiguous.</para>
+
+
+
+
+  </subsection>
+<subsection name="Array and List Features"><a id="_crossRef391"> </a>
+
+
+
+<para>For a CAS feature whose range type is one of the CAS array
+or list types, the XMI serialization depends on the setting of the
+</quote>multipleReferencesAllowed<quote> attribute for that feature in the UIMA
+Type System Description (see <b><a class="crossrefText" href="Component_Descriptor_Reference.htm#_crossRef124">Features</a></b> <a class="crossrefPage" href="Component_Descriptor_Reference.htm#_crossRef124"></a>.</para>
+
+<para>An array or list with multipleReferencesAllowed = false
+(the default) is serialized as a </quote>multi-valued<quote> property in XMI.  An array or list with
+multipleReferencesAllowed = true is serialized as a first-class object.  Details are described below.</para>
+
+<h3><a id="_crossRef392">Arrays and Lists as Multi-Valued
+Properties</a></h3>
+
+<para>In XMI, a multi-valued property is the most natural XMI
+representation for most cases.  Consider
+the example where the FeatureStructure of type org.myproj.Baz has a feature
+myIntArray whose value is the integer array {2,4,6}.  This can be mapped to:</para>
+
+<programlisting>&lt;myproj:Baz xmi:id=</quote>3<quote> myIntArray=</quote>2 4 6<quote>/&gt;</programlisting>
+
+<para>or equivalently:</para>
+
+<programlisting>&lt;myproj:Baz xmi:id=</quote>3<quote>&gt;
+  &lt;myIntArray&gt;2&lt;/myIntArray&gt;
+  &lt;myIntArray&gt;4&lt;/myIntArray&gt;
+  &lt;myIntArray&gt;6&lt;/myIntArray&gt;
+&lt;/myproj:Baz&gt;</programlisting>
+
+<para>Note that String arrays whose elements contain embedded
+spaces MUST use the latter mapping.</para>
+
+<para>FSArray or FSList features are serialized in a similar
+way.  For example an FSArray feature that
+contains references to the elements with xmi:id&apos;s </quote>13<quote> and
+</quote>42<quote> could be serialized as:</para>
+
+<programlisting>&lt;myproj:Baz xmi:id=</quote>3<quote> myFsArray=</quote>13 42<quote>/&gt;</programlisting>
+
+<para>or:</para>
+
+<programlisting>&lt;myproj:Baz xmi:id=</quote>3<quote>&gt;
+  &lt;myFsArray href=</quote>#13<quote>/&gt;
+  &lt;myFsArray href=</quote>#42<quote>/&gt;
+&lt;/myproj:Baz&gt;</programlisting>
+
+<h3><a id="_crossRef393">Arrays and Lists as First-Class
+Objects</a></h3>
+
+<para>The multi-valued-property representation described in the
+previous section does not allow multiple references to an array or list
+object.  Therefore, it cannot be used for
+features that are defined to allow multiple references (i.e. features for which
+multipleReferencesAllowed = true in the Type System Description).</para>
+
+<para>When multipleReferencesAllowed is set to true, array and
+list features are serialized as references, and the array or list objects are
+serialized as separate objects in the XMI. Consider again the example where the
+FeatureStructure of type org.myproj.Baz has a feature myIntArray whose value is
+the integer array {2,4,6}.  If myIntArray
+is defined with multipleReferencesAllowed=true, the serialization will be as
+follows:</para>
+
+<programlisting>&lt;myproj:Baz xmi:id=</quote>3<quote> myIntArray=</quote>4<quote>/&gt;</programlisting>
+
+<para>or:</para>
+
+<programlisting>&lt;myproj:Baz xmi:id=</quote>3<quote>&gt;
+  &lt;myIntArray href=</quote>#4<quote>/&gt;
+&lt;/myproj:Baz&gt;</programlisting>
+
+<para>with the array object serialized as:</para>
+
+<programlisting>&lt;cas:IntegerArray xmi:id=</quote>4<quote> elements=</quote>2 4 6<quote>/&gt;</programlisting>
+
+<para>or:</para>
+
+<programlisting>&lt;cas:IntegerArray xmi:id=</quote>4<quote>&gt;
+  &lt;elements&gt;2&lt;/elements&gt;
+  &lt;elements&gt;4&lt;/elements&gt;
+  &lt;elements&gt;6&lt;/elements&gt;
+&lt;/cas:IntegerArray&gt;</programlisting>
+
+<para>Note that in this case, the XML element name is formed
+from the CAS type name (e.g. </quote><literal>uima.cas.IntegerArray</literal><quote>)
+in the same way as for other FeatureStructures.  The elements of the array are serialized either as a space-separated
+attribute named </quote>elements<quote> or as a series of child elements named
+</quote>elements<quote>.</para>
+
+<para>List nodes are just standard FeatureStructures with
+</quote>head<quote> and </quote>tail<quote> features, and are serialized using the
+normal FeatureStructure serialization.  For example, an IntegerList with the values 2, 4, and 6 would be
+serialized as the four objects:</para>
+
+<programlisting>&lt;cas:NonEmptyIntegerList xmi:id=</quote>10<quote> head=</quote>2<quote> tail=</quote>11<quote>/&gt;
+&lt;cas:NonEmptyIntegerList xmi:id=</quote>11<quote> head=</quote>4<quote> tail=</quote>12<quote>/&gt;
+&lt;cas:NonEmptyIntegerList xmi:id=</quote>12<quote> head=</quote>6<quote> tail=</quote>13<quote>/&gt;
+&lt;cas:EmptyIntegerList xmi:id</quote>13<quote>/&gt;</programlisting>
+
+<para>This representation of arrays allows multiple references
+to an array of list.  It also allows a
+feature with range type TOP to refer to an array or list.  However, it is a very unnatural
+representation in XMI and does not support interoperability with other
+XMI-based systems, so we instead recommend using the multi-valued-property
+representation described in the previous section whenever it is possible.</para>
+
+
+
+
+  </subsection>
+<subsection name="Null Array/List Elements"><a id="_crossRef394"> </a>
+
+
+
+<para>In UIMA, an element of an FSArray or FSList may be
+null.  In XMI, multi-valued properties do
+not permit null values.  As a workaround
+for this, we will use a dummy instance of the special type cas:NULL, which has
+xmi:id 0.  For example, in the following
+example the </quote>myFsArray<quote> feature refers to an FSArray whose second
+element is null:</para>
+
+<programlisting>&lt;cas:NULL xmi:id=</quote>0<quote>/&gt;
+&lt;myproj:Baz xmi:id=</quote>3<quote>&gt;
+  &lt;myFsArray href=</quote>#13<quote>/&gt;
+  &lt;myFsArray href=</quote>#0<quote>/&gt;
+  &lt;myFsArray href=</quote>#42<quote>/&gt;
+&lt;/myproj:Baz&gt;</programlisting>
+
+
+
+
+  </subsection>
+<subsection name="Subjects of Analysis (Sofas) and Views"><a id="_crossRef395"> </a>
+
+
+
+<para>A UIMA CAS contain one or more
+subjects of analysis (Sofas).  These are
+serialized no differently from any other feature structure.  For example:</para>
+
+<programlisting>&lt;?xml version=</quote>1.0<quote> encoding=</quote>ASCII<quote>?&gt;
+&lt;xmi:XMI xmi:version=</quote>2.0<quote> xmlns:xmi=<a href="http://www.omg.org/XMI">http://www.omg.org/XMI</a>
+                           xmlns:cas=</quote>http:///uima/cas.ecore<quote>&gt;
+  &lt;cas:Sofa xmi:id=</quote>1<quote> sofaNum=</quote>1<quote>
+            text=</quote>the quick brown fox jumps over the lazy dog.<quote>/&gt;
+&lt;/xmi:XMI&gt;</programlisting>
+
+<para>Each Sofa defines a separate View.  Feature Structures in the CAS can be members
+of one or more views.  (A Feature
+Structure that is a member of a view is indexed in its IndexRepository, but
+that is an implementation detail.)</para>
+
+<para>In the XMI serialization, views will be represented as
+first-class objects.  Each View has an
+(optional) </quote>sofa<quote> feature, which references a sofa, and multi-valued
+reference to the members of the View.  For example:</para>
+
+<programlisting>&lt;cas:View sofa=</quote>1<quote> members=</quote>3 7 21 39 61<quote>/&gt;</programlisting>
+
+<para>Here the integers 3, 7, 21, 39, and 61 refer to the xmi:id
+fields of the objects that are members of this view.</para>
+
+<para>If the sofa feature is omitted, then this is interpreted
+as the </quote>base<quote> view, whose members pertain to the artifact as a whole
+rather than any individual Sofa.</para>
+
+
+
+
+  </subsection>
+<subsection name="Linking an XMI Document to its Ecore Type System"><a id="_crossRef396"> </a>
+
+
+
+<para>If the CAS Type System has been saved to an Ecore file
+(which is the subject of a different spec), it is possible to store a link from
+an XMI document to that Ecore type system.  This is done using an xsi:schemaLocation attribute on the root XMI
+element.</para>
+
+<para>The xsi:schemaLocation attribute is a space-separated list
+that represents a mapping from namespace URI (e.g. <a href="http://org/myproj.ecore">http:///org/myproj.ecore</a>)
+to the physical URI of the .ecore file containing the type system for that
+namespace.  For example:</para>
+
+<programlisting>xsi:schemaLocation=
+</quote>http:///org/myproj.ecore file:/c:/typesystems/myproj.ecore&quot;</programlisting>
+
+<para>would indicate that the definition for the org.myproj CAS
+types is contained in the file <literal>c:/typesystems/myproj.ecore</literal>.  You can specify a different mapping for each of your CAS namespaces, using a space separated
+list.  For details see Budinsky et
+al.  <emphasis>Eclipse Modeling Framework</emphasis>.</para>
+
+</chapter>
\ No newline at end of file