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'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:
+ 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>
+
+<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>
+
+<programlisting> <!-- General specifications --></programlisting>
+
+<programlisting> <COMMENTS>Main component description</COMMENTS></programlisting>
+
+<programlisting> <COLLECTION_READER>
+ <COLLECTION_ITERATOR_DESC>
+ $main_root/desc/CollIterDescriptor.xml
+ </COLLECTION_ITERATOR_DESC></programlisting>
+
+<programlisting> <CAS_INITIALIZER_DESC>
+ $main_root/desc/CASInitializerDescriptor.xml
+ </CAS_INITIALIZER_DESC>
+ </COLLECTION_READER></programlisting>
+
+<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
+ descriptor
+ </COMMENTS>
+ </PARAMETERS>
+ </PROCESS></programlisting>
+
+<programlisting> <PROCESS>
+ <ACTION>find_and_replace_path</ACTION>
+ <PARAMETERS>
+ <FILE>$main_root/desc/DelegateComponentDescriptor.xml</FILE>
+ <FIND_STRING>
+local_root_directory_for_1st_delegate_component/resources/dict/
+ </FIND_STRING>
+ <REPLACE_WITH>
+ $first_delegate_component_id$root/resources/dict/
+ </REPLACE_WITH>
+ <COMMENTS>
+ Specify actual dictionary location in the descriptor of the 1<sup>st
+</sup> delegate component
+ </COMMENTS>
+ </PARAMETERS>
+ </PROCESS></programlisting>
+
+<programlisting> <!-- 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>
+
+<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 & 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>>
+ <!-- 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>>
+ ...
+ <myproj:Foo xmi:id=<quote>1</quote>/>
+ ...
+</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
+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>>
+ ...
+ <myproj:Foo xmi:id=<quote>1</quote> begin=<quote>14</quote> end=<quote>19</quote> myFeature=<quote>bar</quote>/>
+ ...
+</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>>
+ ...
+ <myproj:Foo xmi:id=</quote>1<quote>>
+ <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>>
+ ...
+ <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>/>
+ ...
+</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>/>
+<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>>
+ <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>/>
+</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>/>
+</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>>
+ <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>
+
+</chapter>
\ No newline at end of file