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/07 23:08:08 UTC
svn commit: r483694 [4/10] - in /incubator/uima/uimaj/trunk/uima-docbooks:
./ lib/ src/docbook/ src/docbook/overview_and_setup/
src/docbook/references/ src/docbook/references/images/ref.javadocs/
src/docbook/tools/ src/docbook/tutorials_and_users_guide...
Modified: 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=diff&rev=483694&r1=483693&r2=483694
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.pear.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.pear.xml Thu Dec 7 14:08:05 2006
@@ -1,7 +1,7 @@
<?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 imgroot "../images/references/ref.pear/" >
<!ENTITY % uimaents SYSTEM "../entities.ent" >
%uimaents;
]>
@@ -24,548 +24,543 @@
under the License.
-->
<chapter id="ugr.ref.pear">
- <title></title>
- <section name="PEAR Reference"><a id="_crossRef259"> </a>
+ <title>PEAR Reference</title>
+
+ <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 <olink targetdoc="&uima_docs_tools;"
+ targetptr="ugr.tools.pear.packager"/> for more information about this
+ tool.</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="303" depth="394" 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>
+
+ <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>
-
-
-
-
-<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'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'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'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 <a class="crossrefText" href="Annotator_and_Analysis_Engine_Developers_Guide.htm#_crossRef7">4.1.4, <b>Creating the XML
-Descriptor</b></a>) and the <DESC> 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'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><OS>: This section is used to specify supported
-operating systems</listitem>
-
-
-<listitem><TOOLKITS>: This section is
-used to specify toolkits, such as JDK, needed by the component.</listitem>
-
-
-<listitem><SUBMITTED_COMPONENT>: This
-is the most important section in the InsD. It's used to specify required
-information about the component. See section 2.3.2 for detailed information
-about this section.</listitem>
-
-
-<listitem><INSTALLATION>: 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><? xml version=<quote>1.0</quote> encoding=<quote>UTF-8</quote>?>
-<!-- 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></programlisting>
-
-<programlisting> <!-- There are 2 types of variables that are used in the InsD:
+ <!-- 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 --></programlisting>
+ installing the given delegate component -->
-<programlisting> <!-- Specification of submitted component (TAE) -->
- <!-- 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. --></programlisting>
-
-<programlisting> <SUBMITTED_COMPONENT>
- <ID>submitted_component_id</ID>
- <NAME>Submitted component name</NAME>
- <DESC>$main_root/desc/ComponentDescriptor.xml</DESC></programlisting>
-
-<programlisting> <!-- 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 --></programlisting>
-
-<programlisting> <DEPLOYMENT>standard | service | network</DEPLOYMENT></programlisting>
-
-<programlisting> <!-- 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></programlisting>
-
-<programlisting> <ARGUMENT>
- <VALUE>1st_parameter_value</VALUE>
- <COMMENTS>1st parameter description</COMMENTS>
- </ARGUMENT></programlisting>
-
-<programlisting> <ARGUMENT>
- <VALUE>2nd_parameter_value</VALUE>
- <COMMENTS>2nd parameter description</COMMENTS>
- </ARGUMENT></programlisting>
-
-<programlisting> </SERVICE_COMMAND_ARGS></programlisting>
-
-<programlisting> <!-- Specifications for ©network© deployment option only --></programlisting>
-
-<programlisting> <NETWORK_PARAMETERS>
- <VNS_SPECS VNS_HOST=<quote>vns_host_IP</quote> VNS_PORT=<quote>vns_port_No</quote> />
- </NETWORK_PARAMETERS></programlisting>
+ <!-- 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>
-<programlisting> <!-- General specifications --></programlisting>
+ <!-- General specifications -->
-<programlisting> <COMMENTS>Main component description</COMMENTS></programlisting>
+ <COMMENTS>Main component description</COMMENTS>
-<programlisting> <COLLECTION_READER>
- <COLLECTION_ITERATOR_DESC>
+ <COLLECTION_READER>
+ <COLLECTION_ITERATOR_DESC>
$main_root/desc/CollIterDescriptor.xml
- </COLLECTION_ITERATOR_DESC></programlisting>
+ </COLLECTION_ITERATOR_DESC>
-<programlisting> <CAS_INITIALIZER_DESC>
+ <CAS_INITIALIZER_DESC>
$main_root/desc/CASInitializerDescriptor.xml
- </CAS_INITIALIZER_DESC>
- </COLLECTION_READER></programlisting>
+ </CAS_INITIALIZER_DESC>
+ </COLLECTION_READER>
-<programlisting> <CAS_CONSUMER>
- <DESC>$main_root/desc/CASConsumerDescriptor.xml</DESC>
- </CAS_CONSUMER></programlisting>
-
-<programlisting> </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 --></programlisting>
-
-<programlisting> <!-- DELEGATE_COMPONENT section. -->
- <DELEGATE_COMPONENT>
- <ID>first_delegate_component_id</ID>
- <NAME>Name of first required separate component</NAME>
- </DELEGATE_COMPONENT></programlisting>
-
-<programlisting> <DELEGATE_COMPONENT>
- <ID>second_delegate_component_id</ID>
- <NAME>Name of second required separate component</NAME>
- </DELEGATE_COMPONENT></programlisting>
-
-<programlisting> <!-- 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. --></programlisting>
-
-<programlisting> <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
+ <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></programlisting>
-
-<programlisting> <PROCESS>
- <ACTION>find_and_replace_path</ACTION>
- <PARAMETERS>
- <FILE>$main_root/desc/DelegateComponentDescriptor.xml</FILE>
- <FIND_STRING>
+ </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>
+ </FIND_STRING>
+ <REPLACE_WITH>
$first_delegate_component_id$root/resources/dict/
- </REPLACE_WITH>
- <COMMENTS>
- Specify actual dictionary location in the descriptor of the 1<sup>st
-</sup> delegate component
- </COMMENTS>
- </PARAMETERS>
- </PROCESS></programlisting>
+ </REPLACE_WITH>
+ <COMMENTS>
+ Specify actual dictionary location in the descriptor of the 1st
+ delegate component
+ </COMMENTS>
+ </PARAMETERS>
+ </PROCESS>
-<programlisting> <!-- Specifications of environment variables that should be set prior
+ <!-- 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. --></programlisting>
-
-<programlisting> <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></programlisting>
-
-<programlisting> </INSTALLATION>
-</COMPONENT_INSTALLATION_DESCRIPTOR></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's 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 <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'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><SUBMITTED_COMPONENT></programlisting>
-
-<programlisting> <ID>submitted_component_id</ID></programlisting>
-
-<programlisting> <NAME>Submitted component name</NAME></programlisting>
-
-<programlisting> <DESC>$main_root/desc/ComponentDescriptor.xml</DESC></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><DEPLOYMENT>standard</DEPLOYMENT> </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><DEPLOYMENT>service</DEPLOYMENT></programlisting>
-
-<programlisting><SERVICE_COMMAND>$main_root/bin/startService.bat</SERVICE_COMMAND></programlisting>
-
-<programlisting><SERVICE_WORKING_DIR>$main_root</SERVICE_WORKING_DIR></programlisting>
-
-<programlisting><SERVICE_COMMAND_ARGS></programlisting>
-
-<programlisting><ARGUMENT></programlisting>
-
-<programlisting><VALUE>1st_parameter_value</VALUE></programlisting>
-
-<programlisting><COMMENTS>1st parameter description</COMMENTS></programlisting>
-
-<programlisting></ARGUMENT></programlisting>
-
-<programlisting><ARGUMENT></programlisting>
-
-<programlisting><VALUE>2nd_parameter_value</VALUE></programlisting>
-
-<programlisting><COMMENTS>2nd parameter description</COMMENTS></programlisting>
-
-<programlisting></ARGUMENT></programlisting>
-
-<programlisting></SERVICE_COMMAND_ARGS></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'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:</para>
-
-<programlisting><DEPLOYMENT>network</DEPLOYMENT></programlisting>
-
-<programlisting><NETWORK_PARAMETERS></programlisting>
-
-<programlisting><VNS_SPECS VNS_HOST=<quote>vns_host_IP</quote> VNS_PORT=<quote>vns_port_No</quote> /></programlisting>
-
-<programlisting></NETWORK_PARAMETERS></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 <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:</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 <PARAMETERS>
-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 <PARAMETERS> sub-section.
-</listitem></itemizedlist>
-
-<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>
-
-<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>
+ <VAR_VALUE> values may use the $main_root or one of the
+ $component_id$root variables. -->
-<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>
+ <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>These macros are defined in the PEAR.properties file using the local values.
+ 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=<quote>vns_host_IP</quote> VNS_PORT=<quote>vns_port_No</quote> />
+</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></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>). The PEAR file must have a
+ <quote>.pear</quote> extension.</para>
+
+ </section>
+ <section id="ugr.ref.pear.installing">
+ <title>Installing a PEAR fiel</title>
+
+ <para>For information about the installation of a PEAR file and the PEAR Installer
+ tool, please see <olink targetdoc="&uima_docs_tools;"
+ targetptr="ugr.tools.pear.installer"/>.</para>
+ </section>
+ </section>
</chapter>
Modified: 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=diff&rev=483694&r1=483693&r2=483694
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.xmi.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.xmi.xml Thu Dec 7 14:08:05 2006
@@ -1,7 +1,6 @@
<?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;
]>
@@ -24,370 +23,341 @@
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 & 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 <XMI> and must include a
-version number and XML namespace attribute:</para>
-
-<programlisting><xmi:XMI xmi:version=<quote>2.0</quote> xmlns:xmi=<a href="http://www.omg.org/XMI">http://www.omg.org/XMI</a>>
+ <title>XMI CAS Serialization Reference</title>
+
+ <para>This is the specification for the mapping of the UIMA CAS into the XMI (XML Metadata
+ Interchange<footnote><para> For details on XMI see Grose et al. <emphasis>Mastering
+ XMI. Java Programming with XMI, XML, and UML. </emphasis>John Wiley & Sons, Inc.
+ 2002.</para></footnote> 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>
+
+ <section id="ugr.ref.xmi.xmi_tag">
+ <title>XMI Tag</title>
+
+ <para>The outermost tag is <XMI> and must include a version number and XML
+ namespace attribute:
+
+
+ <programlisting><xmi:XMI xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI">
<!-- CAS Contents here -->
-</xmi:XMI></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><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>>
+</xmi:XMI></programlisting></para>
+
+ <para>XML namespaces<footnote><para>http://www.w3.org/TR/xml-names11/</para>
+ </footnote> 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>
+
+ </section>
+
+ <section id="ugr.ref.xmi.feature_structures">
+ <title>Feature Structures</title>
+
+ <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)<footnote><para> For details on EMF and Ecore see Budinsky et
+ al. <emphasis>Eclipse Modeling Framework 2.0</emphasis>. Addison-Wesley.
+ 2006.</para></footnote> 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 <olink targetdoc="&uima_docs_tutorial_guides;"
+ targetptr="ugr.tug.xmi_emf"/>.</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:
+
+
+ <programlisting><xmi:XMI
+ xmi:version="2.0"
+ xmlns:xmi="http://www.omg.org/XMI"
+ xmlns:myproj="http:///org/myproj.ecore">
...
- <myproj:Foo xmi:id=<quote>1</quote>/>
+ <myproj:Foo xmi:id="1"/>
...
-</xmi:XMI></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
+</xmi:XMI></programlisting></para>
+
+ <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>
+ </section>
+
+ <section id="ugr.ref.xmi.primitive_features">
+ <title>Primitive Features</title>
+
+ <para>CAS features of primitive types (String, Boolean, Byte, Short, Integer, Long ,
+ Float, or Double) can be mapped either to XML attributes or XML elements. For example, a
+ CAS FeatureStructure of type org.myproj.Foo, with features:
+
+
+ <programlisting>begin = 14
end = 19
-myFeature = <quote>bar</quote></programlisting>
-
-<para>could be mapped to:</para>
-
-<programlisting><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>>
+myFeature = "bar"</programlisting>
+ could be mapped to:
+
+
+ <programlisting><xmi:XMI xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI"
+ xmlns:myproj="http:///org/myproj.ecore">
...
- <myproj:Foo xmi:id=<quote>1</quote> begin=<quote>14</quote> end=<quote>19</quote> myFeature=<quote>bar</quote>/>
+ <myproj:Foo xmi:id="1" begin="14" end="19" myFeature="bar"/>
...
</xmi:XMI></programlisting>
-
-<para>or equivalently:</para>
-
-<programlisting><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>>
+ or equivalently:
+
+
+ <programlisting><![CDATA[<xmi:XMI xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI"
+ xmlns:myproj="http:///org/myproj.ecore">
...
- <myproj:Foo xmi:id=</quote>1<quote>>
- <begin>14</begin>
- <end>19</end>
- <myFeature>bar</myFeature>
- </myproj:Foo>
+ <myproj:Foo xmi:id="1">
+ <begin>14</begin>
+ <end>19</end>
+ <myFeature>bar</myFeature>
+ </myproj:Foo>
...
-</xmi:XMI></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><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>>
+</xmi:XMI>]]></programlisting></para>
+
+ <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>
+
+ </section>
+
+ <section id="ugr.ref.xmi.reference_features">
+ <title>Reference Features</title>
+
+ <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:
+
+
+ <programlisting><![CDATA[<xmi:XMI xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI"
+ xmlns:myproj="http:///org/myproj.ecore">
...
- <myproj:Foo xmi:id=</quote>1<quote> begin=</quote>14<quote> end=</quote>19<quote> myFeature=</quote>bar<quote>/>
- <myproj:Baz xmi:id=</quote>2<quote> myFoo=</quote>1<quote>/>
+ <myproj:Foo xmi:id="1" begin="14" end="19" myFeature="bar"/>
+ <myproj:Baz xmi:id="2" myFoo="1"/>
...
-</xmi:XMI></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><myproj:Baz xmi:id=</quote>2<quote>>
- <myFoo href=</quote>#1<quote>/>
+</xmi:XMI>]]></programlisting></para>
+
+ <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><myproj:Baz xmi:id="2">
+ <myFoo href="#1"/>
<myproj.Baz></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><myproj:Baz xmi:id=</quote>3<quote> myIntArray=</quote>2 4 6<quote>/></programlisting>
-
-<para>or equivalently:</para>
-
-<programlisting><myproj:Baz xmi:id=</quote>3<quote>>
+
+ <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>
+
+ </section>
+
+ <section id="ugr.ref.xmi.array_and_list_features">
+ <title>Array and List Features</title>
+
+ <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 <olink targetdoc="&uima_docs_ref;"
+ targetptr="ugr.ref.xml.component_descriptor.type_system.features"/>.</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>
+
+ <section id="ugr.ref.xmi.array_and_list_features.as_multi_valued_properties">
+ <title>Arrays and Lists as Multi-Valued Properties</title>
+
+ <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:
+
+
+ <programlisting><myproj:Baz xmi:id="3" myIntArray="2 4 6"/></programlisting>
+ or equivalently:
+
+
+ <programlisting><myproj:Baz xmi:id="3">
<myIntArray>2</myIntArray>
<myIntArray>4</myIntArray>
<myIntArray>6</myIntArray>
</myproj:Baz></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's </quote>13<quote> and
-</quote>42<quote> could be serialized as:</para>
-
-<programlisting><myproj:Baz xmi:id=</quote>3<quote> myFsArray=</quote>13 42<quote>/></programlisting>
-
-<para>or:</para>
-
-<programlisting><myproj:Baz xmi:id=</quote>3<quote>>
- <myFsArray href=</quote>#13<quote>/>
- <myFsArray href=</quote>#42<quote>/>
+ </para>
+
+ <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's
+ <quote>13</quote> and <quote>42</quote> could be serialized as:
+
+
+ <programlisting><myproj:Baz xmi:id="3" myFsArray="13 42"/></programlisting>
+ or:
+
+
+ <programlisting><myproj:Baz xmi:id="3">
+ <myFsArray href="#13"/>
+ <myFsArray href="#42"/>
</myproj:Baz></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><myproj:Baz xmi:id=</quote>3<quote> myIntArray=</quote>4<quote>/></programlisting>
-
-<para>or:</para>
-
-<programlisting><myproj:Baz xmi:id=</quote>3<quote>>
- <myIntArray href=</quote>#4<quote>/>
+ </para>
+ </section>
+
+ <section id="ugr.ref.xmi.array_and_list_features.as_1st_class_objects">
+ <title>Arrays and Lists as First-Class Objects</title>
+
+ <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:
+
+
+ <programlisting><myproj:Baz xmi:id="3" myIntArray="4"/></programlisting>
+ or:
+
+
+ <programlisting><myproj:Baz xmi:id="3">
+ <myIntArray href="#4"/>
</myproj:Baz></programlisting>
-
-<para>with the array object serialized as:</para>
-
-<programlisting><cas:IntegerArray xmi:id=</quote>4<quote> elements=</quote>2 4 6<quote>/></programlisting>
-
-<para>or:</para>
-
-<programlisting><cas:IntegerArray xmi:id=</quote>4<quote>>
+ with the array object serialized as
+
+
+ <programlisting><cas:IntegerArray xmi:id="4" elements="2 4 6"/></programlisting>
+ or:
+
+
+ <programlisting><cas:IntegerArray xmi:id="4">
<elements>2</elements>
<elements>4</elements>
<elements>6</elements>
-</cas:IntegerArray></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><cas:NonEmptyIntegerList xmi:id=</quote>10<quote> head=</quote>2<quote> tail=</quote>11<quote>/>
-<cas:NonEmptyIntegerList xmi:id=</quote>11<quote> head=</quote>4<quote> tail=</quote>12<quote>/>
-<cas:NonEmptyIntegerList xmi:id=</quote>12<quote> head=</quote>6<quote> tail=</quote>13<quote>/>
-<cas:EmptyIntegerList xmi:id</quote>13<quote>/></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><cas:NULL xmi:id=</quote>0<quote>/>
-<myproj:Baz xmi:id=</quote>3<quote>>
- <myFsArray href=</quote>#13<quote>/>
- <myFsArray href=</quote>#0<quote>/>
- <myFsArray href=</quote>#42<quote>/>
-</myproj:Baz></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><?xml version=</quote>1.0<quote> encoding=</quote>ASCII<quote>?>
-<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>>
- <cas:Sofa xmi:id=</quote>1<quote> sofaNum=</quote>1<quote>
- text=</quote>the quick brown fox jumps over the lazy dog.<quote>/>
-</xmi:XMI></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><cas:View sofa=</quote>1<quote> members=</quote>3 7 21 39 61<quote>/></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"</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>
-
+</cas:IntegerArray></programlisting></para>
+
+ <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:
+
+
+ <programlisting><cas:NonEmptyIntegerList xmi:id=<quote>10</quote> head=<quote>2</quote> tail=<quote>11</quote>/>
+<cas:NonEmptyIntegerList xmi:id=<quote>11</quote> head=<quote>4</quote> tail=<quote>12</quote>/>
+<cas:NonEmptyIntegerList xmi:id=<quote>12</quote> head=<quote>6</quote> tail=<quote>13</quote>/>
+<cas:EmptyIntegerList xmi:id<quote>13</quote>/></programlisting></para>
+
+ <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>
+
+ </section>
+ </section>
+
+ <section id="ugr.ref.xmi.null_array_list_elements">
+ <title>Null Array/List Elements"</title>
+
+ <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:
+
+
+ <programlisting><cas:NULL xmi:id="0"/>
+<myproj:Baz xmi:id="3">
+ <myFsArray href="#13"/>
+ <myFsArray href="#0"/>
+ <myFsArray href="#42"/>
+</myproj:Baz></programlisting></para>
+
+ </section>
+
+ <section id="ugr.ref.xmi.sofas_views">
+ <title>Subjects of Analysis (Sofas) and Views</title>
+
+ <para>A UIMA CAS contain one or more subjects of analysis (Sofas). These are serialized no
+ differently from any other feature structure. For example:
+
+
+ <programlisting><?xml version="1.0"?>
+<xmi:XMI xmi:version="2.0" xmlns:xmi=http://www.omg.org/XMI
+ xmlns:cas="http:///uima/cas.ecore">
+ <cas:Sofa xmi:id="1" sofaNum="1"
+ text="the quick brown fox jumps over the lazy dog."/>
+</xmi:XMI></programlisting></para>
+
+ <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><cas:View sofa="1" members="3 7 21 39 61"/></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>
+ </section>
+
+ <section id="ugr.ref.xmi.linking_to_ecore_type_system">
+ <title>Linking an XMI Document to its Ecore Type System</title>
+
+ <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. http:///org/myproj.ecore) to the physical URI of the
+ .ecore file containing the type system for that namespace. For example:
+
+
+ <programlisting>xsi:schemaLocation=
+ "http:///org/myproj.ecore file:/c:/typesystems/myproj.ecore"</programlisting>
+ 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>
+ </section>
</chapter>