You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by re...@apache.org on 2023/08/04 17:04:51 UTC
[uima-uimaj] 01/04: Issue #331: Convert remaining documentation to asciidoc
This is an automated email from the ASF dual-hosted git repository.
rec pushed a commit to branch refactoring/331-Convert-remaining-documentation-to-asciidoc
in repository https://gitbox.apache.org/repos/asf/uima-uimaj.git
commit dc50e5f9af26196e0788ac7244ba0bdb90d0a590
Author: Richard Eckart de Castilho <re...@apache.org>
AuthorDate: Fri Aug 4 18:16:50 2023 +0200
Issue #331: Convert remaining documentation to asciidoc
- Convert everything to Asciidoc
- Set up asciidoctor build
- Remove old docbook documentation
---
aggregate-uimaj-docbooks/pom.xml | 73 -
.../src/main/resources/d/index.html | 87 -
aggregate-uimaj/pom.xml | 5 +-
pom.xml | 1 -
uima-doc-v3-users-guide/pom.xml | 1 -
.../src/docs/asciidoc/version_3_users_guide.adoc | 2 +-
uima-docbook-overview-and-setup/pom.xml | 50 -
.../src/docbook/conceptual_overview.xml | 989 -------
.../src/docbook/eclipse_setup.xml | 431 ---
.../src/docbook/faqs.xml | 411 ---
.../src/docbook/glossary.xml | 582 ----
.../src/docbook/known_issues.xml | 68 -
.../src/docbook/overview_and_setup.xml | 34 -
.../src/docbook/project_overview.xml | 731 -----
uima-docbook-references/pom.xml | 50 -
uima-docbook-references/src/docbook/ref.cas.xml | 1228 ---------
.../src/docbook/ref.compress.xml | 212 --
uima-docbook-references/src/docbook/ref.config.xml | 292 --
.../src/docbook/ref.javadocs.xml | 89 -
uima-docbook-references/src/docbook/ref.jcas.xml | 677 -----
uima-docbook-references/src/docbook/ref.json.xml | 682 -----
uima-docbook-references/src/docbook/ref.pear.xml | 1016 -------
.../src/docbook/ref.resources.xml | 186 --
uima-docbook-references/src/docbook/ref.xmi.xml | 381 ---
.../src/docbook/ref.xml.component_descriptor.xml | 2520 ------------------
.../src/docbook/ref.xml.cpe_descriptor.xml | 1375 ----------
uima-docbook-references/src/docbook/references.xml | 39 -
uima-docbook-tools/pom.xml | 50 -
.../src/docbook/tools.annotation_viewer.xml | 79 -
uima-docbook-tools/src/docbook/tools.caseditor.xml | 639 -----
uima-docbook-tools/src/docbook/tools.cde.xml | 1450 ----------
uima-docbook-tools/src/docbook/tools.cpe.xml | 216 --
uima-docbook-tools/src/docbook/tools.cvd.xml | 941 -------
.../src/docbook/tools.doc_analyzer.xml | 338 ---
.../src/docbook/tools.eclipse_launcher.xml | 96 -
uima-docbook-tools/src/docbook/tools.jcasgen.xml | 251 --
.../src/docbook/tools.pear.installer.xml | 119 -
.../src/docbook/tools.pear.merger.xml | 164 --
.../src/docbook/tools.pear.packager.maven.xml | 387 ---
.../src/docbook/tools.pear.packager.xml | 389 ---
uima-docbook-tools/src/docbook/tools.xml | 41 -
uima-docbook-tutorials-and-users-guides/pom.xml | 50 -
.../docbook/annotator_analysis_engine_guide.xml | 2797 --------------------
.../src/docbook/tug.aas.xml | 283 --
.../src/docbook/tug.application.xml | 1859 -------------
.../src/docbook/tug.cas_multiplier.xml | 847 ------
.../src/docbook/tug.configuration.xml | 119 -
.../src/docbook/tug.cpe.xml | 1344 ----------
.../src/docbook/tug.fc.xml | 396 ---
.../src/docbook/tug.multi_views.xml | 660 -----
.../src/docbook/tug.type_mapping.xml | 140 -
.../src/docbook/tug.xmi_emf.xml | 186 --
.../src/docbook/tutorials_and_users_guides.xml | 37 -
.../pom.xml | 147 +-
.../src/docs/asciidoc/oas.adoc | 31 +-
.../src/docs/asciidoc/oas/common_book_info.adoc | 42 +
.../src/docs/asciidoc/oas/conceptual_overview.adoc | 579 ++++
.../src/docs/asciidoc/oas/eclipse_setup.adoc | 199 ++
.../src/docs/asciidoc/oas/faqs.adoc | 205 ++
.../src/docs/asciidoc/oas/glossary.adoc | 205 ++
.../conceptual_overview_files/image002.png | Bin
.../conceptual_overview_files/image004.png | Bin
.../conceptual_overview_files/image006.png | Bin
.../conceptual_overview_files/image008.png | Bin
.../conceptual_overview_files/image010.png | Bin
.../conceptual_overview_files/image012.png | Bin
.../conceptual_overview_files/image014.png | Bin
.../eclipse_setup_files/image002.jpg | Bin
.../eclipse_setup_files/image004.jpg | Bin
.../src/docs/asciidoc/oas/known_issues.adoc | 30 +
.../src/docs/asciidoc/oas/project_overview.adoc | 415 +++
.../src/docs/asciidoc/ref.adoc | 31 +-
.../src/docs/asciidoc/ref/common_book_info.adoc | 42 +
.../docs/asciidoc/ref}/image-source/diagrams.pptx | Bin
.../ref}/images/references/ref.cas/image001.png | Bin
.../images/references/ref.javadocs/image002.jpg | Bin
.../images/references/ref.json/FScollections.png | Bin
.../images/references/ref.json/big_picture2.png | Bin
.../images/references/ref.json/image_source.odg | Bin
.../ref}/images/references/ref.json/multi.view.png | Bin
.../references/ref.json/two.fs.collections.png | Bin
.../images/references/ref.json/types_and_refs.png | Bin
.../ref}/images/references/ref.pear/image002.jpg | Bin
.../ref.resources/res_resource_kinds.png | Bin
.../references/ref.xml.cpe_descriptor/image002.png | Bin
.../src/docs/asciidoc/ref/ref.cas.adoc | 860 ++++++
.../src/docs/asciidoc/ref/ref.compress.adoc | 149 ++
.../src/docs/asciidoc/ref/ref.config.adoc | 179 ++
.../src/docs/asciidoc/ref/ref.javadocs.adoc | 61 +
.../src/docs/asciidoc/ref/ref.jcas.adoc | 463 ++++
.../src/docs/asciidoc/ref/ref.json.adoc | 436 +++
.../src/docs/asciidoc/ref/ref.pear.adoc | 645 +++++
.../src/docs/asciidoc/ref/ref.resources.adoc | 112 +
.../src/docs/asciidoc/ref/ref.xmi.adoc | 354 +++
.../asciidoc/ref/ref.xml.component_descriptor.adoc | 1772 +++++++++++++
.../docs/asciidoc/ref/ref.xml.cpe_descriptor.adoc | 922 +++++++
.../src/docs/asciidoc/tools.adoc | 31 +-
.../src/docs/asciidoc/tools/common_book_info.adoc | 42 +
.../tools/tools.annotation_viewer/image002.jpg | Bin
.../images/tools/tools.caseditor/CasEditor.png | Bin
.../images/tools/tools.caseditor/EditView.png | Bin
.../tools}/images/tools/tools.caseditor/Editor.png | Bin
.../tools/tools.caseditor/EditorAllTypes.png | Bin
.../images/tools/tools.caseditor/EditorOneType.png | Bin
.../tools}/images/tools/tools.caseditor/FSView.png | Bin
.../images/tools/tools.caseditor/ModeMenu.png | Bin
.../images/tools/tools.caseditor/Outline.png | Bin
.../tools/tools.caseditor/ProvideTypeSystem.png | Bin
.../images/tools/tools.caseditor/ShiftEnter.png | Bin
.../tools/tools.caseditor/ShowAnnotationsMenu.png | Bin
.../tools/tools.caseditor/Style-Background.png | Bin
.../images/tools/tools.caseditor/Style-Box.png | Bin
.../images/tools/tools.caseditor/Style-Bracket.png | Bin
.../tools/tools.caseditor/Style-Squiggles.png | Bin
.../tools/tools.caseditor/Style-TextColor.png | Bin
.../images/tools/tools.caseditor/Style-Token.png | Bin
.../tools/tools.caseditor/Style-Underline.png | Bin
.../tools/tools.caseditor/StyleProperties.png | Bin
.../images/tools/tools.caseditor/StyleView.png | Bin
.../images/tools/tools.caseditor/StyleView2.png | Bin
.../images/tools/tools.cde/delegate-chooser.jpg | Bin
.../tools}/images/tools/tools.cde/image002.jpg | Bin
.../tools}/images/tools/tools.cde/image004.jpg | Bin
.../tools}/images/tools/tools.cde/image006.jpg | Bin
.../tools}/images/tools/tools.cde/image008.jpg | Bin
.../tools}/images/tools/tools.cde/image010.jpg | Bin
.../tools}/images/tools/tools.cde/image012.jpg | Bin
.../tools}/images/tools/tools.cde/image014.jpg | Bin
.../tools}/images/tools/tools.cde/image014v2.jpg | Bin
.../tools}/images/tools/tools.cde/image016.jpg | Bin
.../tools}/images/tools/tools.cde/image018.jpg | Bin
.../tools}/images/tools/tools.cde/image020.jpg | Bin
.../tools}/images/tools/tools.cde/image022.jpg | Bin
.../tools}/images/tools/tools.cde/image024.jpg | Bin
.../tools}/images/tools/tools.cde/image025.jpg | Bin
.../tools}/images/tools/tools.cde/image026.jpg | Bin
.../tools}/images/tools/tools.cde/image028.jpg | Bin
.../tools}/images/tools/tools.cde/image030.jpg | Bin
.../tools}/images/tools/tools.cde/image032.jpg | Bin
.../tools}/images/tools/tools.cde/image034.jpg | Bin
.../tools}/images/tools/tools.cde/image036.jpg | Bin
.../tools}/images/tools/tools.cde/image038.jpg | Bin
.../tools}/images/tools/tools.cde/image040.jpg | Bin
.../tools}/images/tools/tools.cde/image042.jpg | Bin
.../tools}/images/tools/tools.cde/image044.jpg | Bin
.../tools}/images/tools/tools.cde/image046.jpg | Bin
.../tools}/images/tools/tools.cde/image048.jpg | Bin
.../tools}/images/tools/tools.cde/image050.jpg | Bin
.../tools}/images/tools/tools.cde/image052.jpg | Bin
.../tools}/images/tools/tools.cde/image054.jpg | Bin
.../tools}/images/tools/tools.cde/image056.jpg | Bin
.../tools}/images/tools/tools.cde/image058.jpg | Bin
.../tools}/images/tools/tools.cde/image060.jpg | Bin
.../tools}/images/tools/tools.cde/image062.jpg | Bin
.../tools}/images/tools/tools.cde/image064.jpg | Bin
.../tools}/images/tools/tools.cde/image066.jpg | Bin
.../tools}/images/tools/tools.cde/image068.jpg | Bin
.../tools}/images/tools/tools.cde/image070.jpg | Bin
.../tools}/images/tools/tools.cde/image072.jpg | Bin
.../images/tools/tools.cde/import-by-location.jpg | Bin
.../images/tools/tools.cde/import-by-name.jpg | Bin
.../images/tools/tools.cde/import-chooser.jpg | Bin
.../tools}/images/tools/tools.cde/limitJCasGen.jpg | Bin
.../images/tools/tools.cde/limitJCasGenType.jpg | Bin
.../tools}/images/tools/tools.cpe/image002.jpg | Bin
.../tools}/images/tools/tools.cpe/image004.jpg | Bin
.../images/tools/tools.cvd/AnnotationViewer.jpg | Bin
.../images/tools/tools.cvd/ChangeCodePage.jpg | Bin
.../images/tools/tools.cvd/CustomizeColors.jpg | Bin
.../tools}/images/tools/tools.cvd/EditMenu.jpg | Bin
.../tools}/images/tools/tools.cvd/ErrorExample.jpg | Bin
.../tools}/images/tools/tools.cvd/FileMenu.jpg | Bin
.../tools}/images/tools/tools.cvd/LogView.jpg | Bin
.../tools}/images/tools/tools.cvd/Main1.jpg | Bin
.../tools}/images/tools/tools.cvd/Main2.jpg | Bin
.../tools}/images/tools/tools.cvd/Main3.jpg | Bin
.../tools}/images/tools/tools.cvd/Main4.jpg | Bin
.../tools}/images/tools/tools.cvd/RunMenu.jpg | Bin
.../tools}/images/tools/tools.cvd/StatusBar.jpg | Bin
.../images/tools/tools.cvd/TypeSystemViewer.jpg | Bin
.../images/tools/tools.cvd/eclipse-cvd-launch.jpg | Bin
.../tools/tools.doc_analyzer/DocAnalyzerScr1.png | Bin
.../images/tools/tools.doc_analyzer/image002.jpg | Bin
.../images/tools/tools.doc_analyzer/image004.jpg | Bin
.../images/tools/tools.doc_analyzer/image006.jpg | Bin
.../images/tools/tools.doc_analyzer/image006v2.png | Bin
.../tools/tools.doc_analyzer/image007-1v2.png | Bin
.../tools/tools.doc_analyzer/image007-2v2.png | Bin
.../tools/tools.doc_analyzer/image007-3v2.png | Bin
.../images/tools/tools.doc_analyzer/image007.jpg | Bin
.../images/tools/tools.doc_analyzer/image008.jpg | Bin
.../images/tools/tools.doc_analyzer/image010.jpg | Bin
.../tools/tools.eclipse_launcher/image01.png | Bin
.../tools}/images/tools/tools.jcasgen/image002.jpg | Bin
.../tools}/images/tools/tools.jcasgen/image004.jpg | Bin
.../images/tools/tools.pear.installer/image002.jpg | Bin
.../images/tools/tools.pear.packager/image001.jpg | Bin
.../images/tools/tools.pear.packager/image002.jpg | Bin
.../images/tools/tools.pear.packager/image004.jpg | Bin
.../images/tools/tools.pear.packager/image005.jpg | Bin
.../images/tools/tools.pear.packager/image006.jpg | Bin
.../images/tools/tools.pear.packager/image008.jpg | Bin
.../images/tools/tools.pear.packager/image010.jpg | Bin
.../asciidoc/tools/tools.annotation_viewer.adoc | 43 +
.../src/docs/asciidoc/tools/tools.caseditor.adoc | 373 +++
.../src/docs/asciidoc/tools/tools.cde.adoc | 797 ++++++
.../src/docs/asciidoc/tools/tools.cpe.adoc | 136 +
.../src/docs/asciidoc/tools/tools.cvd.adoc | 452 ++++
.../docs/asciidoc/tools/tools.doc_analyzer.adoc | 172 ++
.../asciidoc/tools/tools.eclipse_launcher.adoc | 56 +
.../src/docs/asciidoc/tools/tools.jcasgen.adoc | 168 ++
.../docs/asciidoc/tools/tools.pear.installer.adoc | 64 +
.../src/docs/asciidoc/tools/tools.pear.merger.adoc | 90 +
.../docs/asciidoc/tools/tools.pear.packager.adoc | 210 ++
.../asciidoc/tools/tools.pear.packager.maven.adoc | 260 ++
.../src/docs/asciidoc/tug.adoc | 31 +-
.../tug/annotator_analysis_engine_guide.adoc | 1810 +++++++++++++
.../src/docs/asciidoc/tug/common_book_info.adoc | 42 +
.../tug.aae/image002.jpg | Bin
.../tug.aae/image004.jpg | Bin
.../tug.aae/image006.jpg | Bin
.../tug.aae/image008.jpg | Bin
.../tug.aae/image010.jpg | Bin
.../tug.aae/image012.jpg | Bin
.../tug.aae/image014.jpg | Bin
.../tug.aae/image016.jpg | Bin
.../tug.aae/image018.jpg | Bin
.../tug.aae/image020.jpg | Bin
.../tug.aae/image022.jpg | Bin
.../tug.aae/image024.png | Bin
.../tug.aae/image026.jpg | Bin
.../tug.aae/image028.jpg | Bin
.../tug.aae/image030.jpg | Bin
.../tug.aae/image032.jpg | Bin
.../tug.aae/image034.png | Bin
.../tug.aae/image036.jpg | Bin
.../tug.aae/image038.jpg | Bin
.../tug.aae/image040.png | Bin
.../tug.aae/image042.png | Bin
.../tug.aae/image044.jpg | Bin
.../tug.aae/image046.jpg | Bin
.../tug.aae/image048.jpg | Bin
.../tug.aae/image050.jpg | Bin
.../tug.application/image002.jpg | Bin
.../tug.application/image004.jpg | Bin
.../tug.application/image006.jpg | Bin
.../tug.cas_multiplier/image002.jpg | Bin
.../tug.cpe/image002.png | Bin
.../tug.cpe/image004.jpg | Bin
.../tug.cpe/image006.jpg | Bin
.../tug.cpe/image008.jpg | Bin
.../tug.cpe/image010.jpg | Bin
.../tug.cpe/image012.jpg | Bin
.../tug.cpe/image014.jpg | Bin
.../tug.cpe/image018.png | Bin
.../tug.cpe/image020.png | Bin
.../tug.cpe/image023.png | Bin
.../tug.cpe/image026.png | Bin
.../tutorials_and_users_guides/tug.fc/image002.jpg | Bin
.../tutorials_and_users_guides/tug.fc/image004.jpg | Bin
.../tutorials_and_users_guides/tug.fc/image006.jpg | Bin
.../src/docs/asciidoc/tug/tug.aas.adoc | 190 ++
.../src/docs/asciidoc/tug/tug.application.adoc | 1380 ++++++++++
.../src/docs/asciidoc/tug/tug.cas_multiplier.adoc | 682 +++++
.../src/docs/asciidoc/tug/tug.cpe.adoc | 909 +++++++
.../src/docs/asciidoc/tug/tug.fc.adoc | 294 ++
.../src/docs/asciidoc/tug/tug.multi_views.adoc | 548 ++++
.../src/docs/asciidoc/tug/tug.type_mapping.adoc | 90 +
.../src/docs/asciidoc/tug/tug.xmi_emf.adoc | 130 +
269 files changed, 16786 insertions(+), 26183 deletions(-)
diff --git a/aggregate-uimaj-docbooks/pom.xml b/aggregate-uimaj-docbooks/pom.xml
deleted file mode 100644
index 33ce82329..000000000
--- a/aggregate-uimaj-docbooks/pom.xml
+++ /dev/null
@@ -1,73 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- 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.
--->
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
- <modelVersion>4.0.0</modelVersion>
-
- <parent>
- <groupId>org.apache.uima</groupId>
- <artifactId>uimaj-parent</artifactId>
- <version>3.5.0-SNAPSHOT</version>
- <relativePath>../uimaj-parent/pom.xml</relativePath>
- </parent>
-
- <artifactId>aggregate-uimaj-docbooks</artifactId>
- <packaging>pom</packaging>
- <name>Apache UIMA Aggregate: ${project.artifactId}</name>
- <url>${uimaWebsiteUrl}</url>
-
- <build>
- <plugins>
- <plugin>
- <artifactId>maven-resources-plugin</artifactId>
- <executions>
- <execution>
- <goals>
- <goal>copy-resources</goal>
- </goals>
- <phase>process-resources</phase>
- <configuration>
- <outputDirectory>${project.build.directory}</outputDirectory>
- <resources>
- <resource>
- <filtering>true</filtering>
- <directory>src/main/resources</directory>
- <includes>
- <include>**/*.*</include>
- </includes>
- </resource>
- </resources>
- </configuration>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
-
- <modules>
- <!-- Legacy Docbook -->
- <module>../uima-docbook-overview-and-setup</module>
- <module>../uima-docbook-references</module>
- <module>../uima-docbook-tools</module>
- <module>../uima-docbook-tutorials-and-users-guides</module>
- <!-- Converted to Asciidoc -->
- <module>../uima-doc-v3-users-guide</module>
- <module>../uima-doc-v3-maintainers-guide</module>
- </modules>
-</project>
\ No newline at end of file
diff --git a/aggregate-uimaj-docbooks/src/main/resources/d/index.html b/aggregate-uimaj-docbooks/src/main/resources/d/index.html
deleted file mode 100644
index f32015848..000000000
--- a/aggregate-uimaj-docbooks/src/main/resources/d/index.html
+++ /dev/null
@@ -1,87 +0,0 @@
-
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<title>Apache UIMA Documentation Overview</title>
-<link rel="stylesheet" href="css/stylesheet-html.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.70.0">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084"
- alink="#0000FF">
-<div class="book" lang="en" id="d0e2">
-<div class="titlepage">
-<div>
-<div>
-<h1 class="title"><a name="d0e2"></a>UIMA Documentation Overview</h1>
-</div>
-<div>
-<div class="authorgroup">
-<p>Authors: The Apache UIMA Development Community</p>
-</div>
-</div>
-<div>
-<p class="releaseinfo">Version ${project.version}</p>
-</div>
-<div>
-<p class="copyright">Copyright © 2006, ${buildYear} The Apache Software
-Foundation</p>
-</div>
-<div>
-<p class="copyright">Copyright © 2004, 2006 International
-Business Machines Corporation</p>
-</div>
-<div>
-<div class="legalnotice"><a name="d0e15"></a>
-<p><b>License and Disclaimer. </b>The ASF licenses this
-documentation to you under the Apache License, Version 2.0 (the
-"License"); you may not use this documentation except in compliance with
-the License. You may obtain a copy of the License at</p>
-<div class="blockquote">
-<blockquote class="blockquote"><a
- href="http://www.apache.org/licenses/LICENSE-2.0" target="_top">http://www.apache.org/licenses/LICENSE-2.0</a></blockquote>
-</div>
-<p>Unless required by applicable law or agreed to in writing, this
-documentation and its contents are distributed under the License 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.</p>
-<p></p>
-<p><b>Trademarks. </b>All terms mentioned in the text that are
-known to be trademarks or service marks have been appropriately
-capitalized. Use of such terms in this book should not be regarded as
-affecting the validity of the the trademark or service mark.</p>
-</div>
-</div>
-<div>
-<p class="pubdate">
-${buildMonth}, ${buildYear}
-</p>
-</div>
-</div>
-<hr>
-</div>
-
-<h3>Books in the UIMA Documentation</h3>
-
-<p>
- The UIMA documentation is available in both PDF and HTML formats. It is
- divided into four books.
-</p>
-<dl>
-<dt><span class="chapter"><a href="overview_and_setup.html">1. Overview & Setup</a></span></dt>
- <dd>This includes overview material, a general guide to all the rest of the documentation,
- and some setup instructions if you are using the Eclipse IDE.</dd>
-<dt><span class="chapter"><a href="tutorials_and_users_guides.html">2. UIMA Tutorial and Developers' Guides</a></span></dt>
- <dd>This is a set of tutorial chapters and some general overview guides to the major features and capabilities of UIMA.</dd>
-<dt><span class="chapter"><a href="tools.html">3. UIMA Tools Guide and Reference</a></span></dt>
- <dd>UIMA comes with a set of tools, which are described in this book.</dd>
-<dt><span class="chapter"><a href="references.html">4. UIMA References</a></span></dt>
- <dd>Reference materials, covering the XML descriptors, the major APIs, the data interchange formats,
- and the component packaging.</dd>
-</dl>
-
-<h3>Release Notes</h3>
-<p>Click <a href="RELEASE_NOTES.html">RELEASE_NOTES.html</a> for the ${project.version} Apache UIMA JAVA SDK
-release notes.</p>
-
-</html>
diff --git a/aggregate-uimaj/pom.xml b/aggregate-uimaj/pom.xml
index f09129c6a..4f0ae3ae8 100644
--- a/aggregate-uimaj/pom.xml
+++ b/aggregate-uimaj/pom.xml
@@ -43,8 +43,9 @@
<module>../uimaj-component-test-util</module>
<module>../jVinci</module>
<module>../aggregate-uimaj-eclipse-plugins</module>
- <module>../aggregate-uimaj-docbooks</module>
- <!--module>distr-superPom</module-->
+ <module>../uimaj-documentation</module>
+ <module>../uima-doc-v3-users-guide</module>
+ <module>../uima-doc-v3-maintainers-guide</module>
<module>../uimaj-document-annotation</module>
<module>../PearPackagingMavenPlugin</module>
<module>../jcasgen-maven-plugin</module>
diff --git a/pom.xml b/pom.xml
index 14a88d680..1324556ae 100644
--- a/pom.xml
+++ b/pom.xml
@@ -286,7 +286,6 @@
<exclude>jVinci/**</exclude>
<exclude>PearPackagingMavenPlugin/**</exclude>
<exclude>jcasgen-maven-plugin/**</exclude>
- <exclude>uima-docbook-*/**</exclude>
<exclude>uima-doc-*/**</exclude>
<exclude>uimaj-adapter-*/**</exclude>
<exclude>uimaj-bom/**</exclude>
diff --git a/uima-doc-v3-users-guide/pom.xml b/uima-doc-v3-users-guide/pom.xml
index f7782fc0e..81fb22437 100644
--- a/uima-doc-v3-users-guide/pom.xml
+++ b/uima-doc-v3-users-guide/pom.xml
@@ -76,7 +76,6 @@
<docinfo1>true</docinfo1>
<project-version>${project.version}</project-version>
<revnumber>${project.version}</revnumber>
- <product-name>Apache UIMA Version 3 User's Guide</product-name>
<product-website-url>https://uima.apache.org</product-website-url>
<icons>font</icons>
</attributes>
diff --git a/uima-doc-v3-users-guide/src/docs/asciidoc/version_3_users_guide.adoc b/uima-doc-v3-users-guide/src/docs/asciidoc/version_3_users_guide.adoc
index 253ad045f..7cf192385 100644
--- a/uima-doc-v3-users-guide/src/docs/asciidoc/version_3_users_guide.adoc
+++ b/uima-doc-v3-users-guide/src/docs/asciidoc/version_3_users_guide.adoc
@@ -15,7 +15,7 @@
// specific language governing permissions and limitations
// under the License.
-= Apache UIMA™
+= Apache UIMA™ - UIMA 3 User's Guide
:Author: Apache UIMA™ Development Community
:toc-title: UIMA 3 User's Guide
diff --git a/uima-docbook-overview-and-setup/pom.xml b/uima-docbook-overview-and-setup/pom.xml
deleted file mode 100644
index 2d7f4ec59..000000000
--- a/uima-docbook-overview-and-setup/pom.xml
+++ /dev/null
@@ -1,50 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- 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.
--->
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
- <modelVersion>4.0.0</modelVersion>
-
- <parent>
- <groupId>org.apache.uima</groupId>
- <artifactId>uimaj-parent</artifactId>
- <version>3.5.0-SNAPSHOT</version>
- <relativePath>../uimaj-parent/pom.xml</relativePath>
- </parent>
-
- <artifactId>uima-docbook-overview-and-setup</artifactId>
- <packaging>pom</packaging>
- <name>Apache UIMA SDK Documentation - overview and setup</name>
- <url>${uimaWebsiteUrl}</url>
-
- <properties>
- <!-- next property is the name of the top file under src/docbook without trailing .xml -->
- <bookNameRoot>overview_and_setup</bookNameRoot>
- </properties>
-
- <repositories>
- <repository>
- <id>apache.snapshots</id>
- <name>Apache Snapshot Repository</name>
- <url>https://repository.apache.org/snapshots</url>
- <releases>
- <enabled>false</enabled>
- </releases>
- </repository>
- </repositories>
-</project>
\ No newline at end of file
diff --git a/uima-docbook-overview-and-setup/src/docbook/conceptual_overview.xml b/uima-docbook-overview-and-setup/src/docbook/conceptual_overview.xml
deleted file mode 100644
index 5501fdf9e..000000000
--- a/uima-docbook-overview-and-setup/src/docbook/conceptual_overview.xml
+++ /dev/null
@@ -1,989 +0,0 @@
-<?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 key_concepts "Key UIMA Concepts Introduced in this Section:">
-<!ENTITY imgroot "images/overview-and-setup/conceptual_overview_files/" >
-<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >
-%uimaents;
-]>
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-<chapter id="ugr.ovv.conceptual">
- <title>UIMA Conceptual Overview</title>
-
- <para>UIMA is an open, industrial-strength, scaleable and extensible platform for
- creating, integrating and deploying unstructured information management solutions
- from powerful text or multi-modal analysis and search components. </para>
-
- <para>The Apache UIMA project is an implementation of the Java UIMA framework available
- under the Apache License, providing a common foundation for industry and academia to
- collaborate and accelerate the world-wide development of technologies critical for
- discovering vital knowledge present in the fastest growing sources of information
- today.</para>
-
- <para>This chapter presents an introduction to many essential UIMA concepts. It is meant to
- provide a broad overview to give the reader a quick sense of UIMA's basic
- architectural philosophy and the UIMA SDK's capabilities. </para>
-
- <para>This chapter provides a general orientation to UIMA and makes liberal reference to
- the other chapters in the UIMA SDK documentation set, where the reader may find detailed
- treatments of key concepts and development practices. It may be useful to refer to <olink
- targetdoc="&uima_docs_overview;" targetptr="ugr.glossary"/>, to become familiar
- with the terminology in this overview.</para>
-
- <section id="ugr.ovv.conceptual.uima_introduction">
- <title>UIMA Introduction</title>
- <figure id="ugr.ovv.conceptual.fig.bridge">
- <title>UIMA helps you build the bridge between the unstructured and structured
- worlds</title>
- <mediaobject>
- <imageobject>
- <imagedata width="5.5in" format="PNG" fileref="&imgroot;image002.png"/>
- </imageobject>
- <textobject><phrase>Picture of a bridge between unstructured information
- artifacts and structured metadata about those artifacts</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
- <para> Unstructured information represents the largest, most current and fastest
- growing source of information available to businesses and governments. The web is just
- the tip of the iceberg. Consider the mounds of information hosted in the enterprise and
- around the world and across different media including text, voice and video. The
- high-value content in these vast collections of unstructured information is,
- unfortunately, buried in lots of noise. Searching for what you need or doing
- sophisticated data mining over unstructured information sources presents new
- challenges. </para>
-
- <para>An unstructured information management (UIM) application may be generally
- characterized as a software system that analyzes large volumes of unstructured
- information (text, audio, video, images, etc.) to discover, organize and deliver
- relevant knowledge to the client or application end-user. An example is an application
- that processes millions of medical abstracts to discover critical drug interactions.
- Another example is an application that processes tens of millions of documents to
- discover key evidence indicating probable competitive threats. </para>
-
- <para>First and foremost, the unstructured data must be analyzed to interpret, detect
- and locate concepts of interest, for example, named entities like persons,
- organizations, locations, facilities, products etc., that are not explicitly tagged
- or annotated in the original artifact. More challenging analytics may detect things
- like opinions, complaints, threats or facts. And then there are relations, for
- example, located in, finances, supports, purchases, repairs etc. The list of concepts
- important for applications to discover in unstructured content is large, varied and
- often domain specific.
- Many different component analytics may solve different parts of the overall analysis task.
- These component analytics must interoperate and must be easily combined to facilitate
- the development of UIM applications.</para>
-
- <para>The result of analysis are used to populate structured forms so that conventional
- data processing and search technologies
- like search engines, database engines or OLAP
- (On-Line Analytical Processing, or Data Mining) engines
- can efficiently deliver the newly discovered content in response to the client requests
- or queries.</para>
-
- <para>In analyzing unstructured content, UIM applications make use of a variety of
- analysis technologies including:</para>
-
- <itemizedlist spacing="compact">
- <listitem><para>Statistical and rule-based Natural Language Processing
- (NLP)</para>
- </listitem>
- <listitem><para>Information Retrieval (IR)</para>
- </listitem>
- <listitem><para>Machine learning</para>
- </listitem>
- <listitem><para>Ontologies</para>
- </listitem>
- <listitem><para>Automated reasoning and</para>
- </listitem>
- <listitem><para>Knowledge Sources (e.g., CYC, WordNet, FrameNet, etc.)</para>
- </listitem>
-
- </itemizedlist>
-
- <para>Specific analysis capabilities using these technologies are developed
- independently using different techniques, interfaces and platforms.
- </para>
-
- <para>The bridge from the unstructured world to the structured world is built through the
- composition and deployment of these analysis capabilities. This integration is often
- a costly challenge. </para>
-
- <para>The Unstructured Information Management Architecture (UIMA) is an architecture
- and software framework that helps you build that bridge. It supports creating,
- discovering, composing and deploying a broad range of analysis capabilities and
- linking them to structured information services.</para>
-
- <para>UIMA allows development teams to match the right skills with the right parts of a
- solution and helps enable rapid integration across technologies and platforms using a
- variety of different deployment options. These ranging from tightly-coupled
- deployments for high-performance, single-machine, embedded solutions to parallel
- and fully distributed deployments for highly flexible and scaleable
- solutions.</para>
-
- </section>
-
- <section id="ugr.ovv.conceptual.architecture_framework_sdk">
- <title>The Architecture, the Framework and the SDK</title>
- <para>UIMA is a software architecture which specifies component interfaces, data
- representations, design patterns and development roles for creating, describing,
- discovering, composing and deploying multi-modal analysis capabilities.</para>
-
- <para>The <emphasis role="bold">UIMA framework</emphasis> provides a run-time
- environment in which developers can plug in their UIMA component implementations and
- with which they can build and deploy UIM applications. The framework is not specific to
- any IDE or platform. Apache hosts a Java and (soon) a C++ implementation of the UIMA
- Framework.</para>
-
- <para>The <emphasis role="bold">UIMA Software Development Kit (SDK)</emphasis>
- includes the UIMA framework, plus tools and utilities for using UIMA. Some of the
- tooling supports an Eclipse-based ( <ulink url="http://www.eclipse.org/"/>)
- development environment. </para>
-
- </section>
-
- <section id="ugr.ovv.conceptual.analysis_basics">
- <title>Analysis Basics</title>
- <note><title>&key_concepts;</title><para>Analysis Engine, Document, Annotator, Annotator
- Developer, Type, Type System, Feature, Annotation, CAS, Sofa, JCas, UIMA
- Context.</para>
- </note>
-
- <section id="ugr.ovv.conceptual.aes_annotators_and_analysis_results">
- <title>Analysis Engines, Annotators & Results</title>
- <figure id="ugr.ovv.conceptual.metadata_in_cas">
- <title>Objects represented in the Common Analysis Structure (CAS)</title>
- <mediaobject>
- <imageobject role="html">
- <imagedata format="PNG" width="594px" align="center" fileref="&imgroot;image004.png"/>
- </imageobject>
- <imageobject role="fo">
- <imagedata format="PNG" width="5.5in" align="center" fileref="&imgroot;image004.png"/>
- </imageobject>
- <textobject><phrase>Picture of some text, with a hierarchy of discovered
- metadata about words in the text, including some image of a person as metadata
- about that name.</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
- <para>UIMA is an architecture in which basic building blocks called Analysis Engines
- (AEs) are composed to analyze a document and infer and record descriptive attributes
- about the document as a whole, and/or about regions therein. This descriptive
- information, produced by AEs is referred to generally as <emphasis role="bold">
- analysis results</emphasis>. Analysis results typically represent meta-data
- about the document content. One way to think about AEs is as software agents that
- automatically discover and record meta-data about original content.</para>
-
- <para>UIMA supports the analysis of different modalities including text, audio and
- video. The majority of examples we provide are for text. We use the term <emphasis
- role="bold">document, </emphasis>therefore, to generally refer to any unit of
- content that an AE may process, whether it is a text document or a segment of audio, for
- example. See the <olink targetdoc="&uima_docs_tutorial_guides;"/>
- <olink targetdoc="&uima_docs_tutorial_guides;"
- targetptr="ugr.tug.mvs"/> for more information on multimodal processing
- in UIMA.</para>
-
- <para>Analysis results include different statements about the content of a document.
- For example, the following is an assertion about the topic of a document:</para>
-
-
- <programlisting>(1) The Topic of document D102 is "CEOs and Golf".</programlisting>
-
- <para>Analysis results may include statements describing regions more granular than
- the entire document. We use the term <emphasis role="bold">span</emphasis> to
- refer to a sequence of characters in a text document. Consider that a document with the
- identifier D102 contains a span, <quote>Fred Centers</quote> starting at
- character position 101. An AE that can detect persons in text may represent the
- following statement as an analysis result:</para>
-
-
- <programlisting>(2) The span from position 101 to 112 in document D102 denotes a Person</programlisting>
-
- <para>In both statements 1 and 2 above there is a special pre-defined term or what we call
- in UIMA a <emphasis role="bold">Type</emphasis>. They are
- <emphasis>Topic</emphasis> and <emphasis>Person</emphasis> respectively.
- UIMA types characterize the kinds of results that an AE may create – more on
- types later.</para>
-
- <para>Other analysis results may relate two statements. For example, an AE might
- record in its results that two spans are both referring to the same person:</para>
-
-
- <programlisting>(3) The Person denoted by span 101 to 112 and
- the Person denoted by span 141 to 143 in document D102
- refer to the same Entity.</programlisting>
-
- <para>The above statements are some examples of the kinds of results that AEs may record
- to describe the content of the documents they analyze. These are not meant to indicate
- the form or syntax with which these results are captured in UIMA – more on that
- later in this overview.</para>
-
- <para>The UIMA framework treats Analysis engines as pluggable, composible,
- discoverable, managed objects. At the heart of AEs are the analysis algorithms that
- do all the work to analyze documents and record analysis results. </para>
-
- <para>UIMA provides a basic component type intended to house the core analysis
- algorithms running inside AEs. Instances of this component are called <emphasis
- role="bold">Annotators</emphasis>. The analysis algorithm developer's
- primary concern therefore is the development of annotators. The UIMA framework
- provides the necessary methods for taking annotators and creating analysis
- engines.</para>
-
- <para>In UIMA the person who codes analysis algorithms takes on the role of the
- <emphasis role="bold">Annotator Developer</emphasis>. <olink
- targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.aae"/>
- in <olink targetdoc="&uima_docs_tutorial_guides;"/> will take the reader
- through the details involved in creating UIMA annotators and analysis
- engines.</para>
-
- <para>At the most primitive level an AE wraps an annotator adding the necessary APIs and
- infrastructure for the composition and deployment of annotators within the UIMA
- framework. The simplest AE contains exactly one annotator at its core. Complex AEs
- may contain a collection of other AEs each potentially containing within them other
- AEs. </para>
- </section>
-
- <section id="ugr.ovv.conceptual.representing_results_in_cas">
- <title>Representing Analysis Results in the CAS</title>
-
- <para>How annotators represent and share their results is an important part of the UIMA
- architecture. UIMA defines a <emphasis role="bold">Common Analysis Structure
- (CAS)</emphasis> precisely for these purposes.</para>
-
- <para>The CAS is an object-based data structure that allows the representation of
- objects, properties and values. Object types may be related to each other in a
- single-inheritance hierarchy. The CAS logically (if not physically) contains the
- document being analyzed. Analysis developers share and record their analysis
- results in terms of an object model within the CAS. <footnote><para> We have plans to
- extend the representational capabilities of the CAS and align its semantics with the
- semantics of the OMG's Essential Meta-Object Facility (EMOF) and with the
- semantics of the Eclipse Modeling Framework's ( <ulink
- url="http://www.eclipse.org/emf/"/>) Ecore semantics and XMI-based
- representation.</para> </footnote> </para>
-
- <para>The UIMA framework includes an implementation and interfaces to the CAS. For a
- more detailed description of the CAS and its interfaces see <olink
- targetdoc="&uima_docs_ref;"/> <olink
- targetdoc="&uima_docs_ref;" targetptr="ugr.ref.cas"/>.</para>
-
- <para>A CAS that logically contains statement 2 (repeated here for your
- convenience)</para>
-
-
- <programlisting>(2) The span from position 101 to 112 in document D102 denotes a Person</programlisting>
-
- <para>would include objects of the Person type. For each person found in the body of a
- document, the AE would create a Person object in the CAS and link it to the span of text
- where the person was mentioned in the document.</para>
-
- <para>While the CAS is a general purpose data structure, UIMA defines a
- few basic types and affords the developer the ability to extend these to define an
- arbitrarily rich <emphasis role="bold">Type System</emphasis>. You can think of a
- type system as an object schema for the CAS.</para>
-
- <para>A type system defines the various types of objects that may be discovered in
- documents by AE's that subscribe to that type system.</para>
-
- <para>As suggested above, Person may be defined as a type. Types have properties or
- <emphasis role="bold">features</emphasis>. So for example,
- <emphasis>Age</emphasis> and <emphasis>Occupation</emphasis> may be defined as
- features of the Person type.</para>
-
- <para>Other types might be <emphasis>Organization, Company, Bank, Facility, Money,
- Size, Price, Phone Number, Phone Call, Relation, Network Packet, Product, Noun
- Phrase, Verb, Color, Parse Node, Feature Weight Array</emphasis> etc.</para>
-
- <para>There are no limits to the different types that may be defined in a type system. A
- type system is domain and application specific.</para>
-
- <para>Types in a UIMA type system may be organized into a taxonomy. For example,
- <emphasis>Company</emphasis> may be defined as a subtype of
- <emphasis>Organization</emphasis>. <emphasis>NounPhrase</emphasis> may be a
- subtype of a <emphasis>ParseNode</emphasis>.</para>
-
- <section id="ugr.ovv.conceptual.annotation_type">
- <title>The Annotation Type</title>
-
- <para>A general and common type used in artifact analysis and from which additional
- types are often derived is the <emphasis role="bold">annotation</emphasis>
- type. </para>
-
- <para>The annotation type is used to annotate or label regions of an artifact. Common
- artifacts are text documents, but they can be other things, such as audio streams.
- The annotation type for text includes two features, namely
- <emphasis>begin</emphasis> and <emphasis>end</emphasis>. Values of these
- features represent integer offsets in the artifact and delimit a span. Any
- particular annotation object identifies the span it annotates with the
- <emphasis>begin</emphasis> and <emphasis>end</emphasis> features.</para>
-
- <para>The key idea here is that the annotation type is used to identify and label or
- <quote>annotate</quote> a specific region of an artifact.</para>
-
- <para>Consider that the Person type is defined as a subtype of annotation. An
- annotator, for example, can create a Person annotation to record the discovery of a
- mention of a person between position 141 and 143 in document D102. The annotator can
- create another person annotation to record the detection of a mention of a person in
- the span between positions 101 and 112. </para>
- </section>
- <section id="ugr.ovv.conceptual.not_just_annotations">
- <title>Not Just Annotations</title>
-
- <para>While the annotation type is a useful type for annotating regions of a
- document, annotations are not the only kind of types in a CAS. A CAS is a general
- representation scheme and may store arbitrary data structures to represent the
- analysis of documents.</para>
-
- <para>As an example, consider statement 3 above (repeated here for your
- convenience).</para>
-
-
- <programlisting>(3) The Person denoted by span 101 to 112 and
- the Person denoted by span 141 to 143 in document D102
- refer to the same Entity.</programlisting>
-
- <para>This statement mentions two person annotations in the CAS; the first, call it
- P1 delimiting the span from 101 to 112 and the other, call it P2, delimiting the span
- from 141 to 143. Statement 3 asserts explicitly that these two spans refer to the
- same entity. This means that while there are two expressions in the text
- represented by the annotations P1 and P2, each refers to one and the same person.
- </para>
-
- <para>The Entity type may be introduced into a type system to capture this kind of
- information. The Entity type is not an annotation. It is intended to represent an
- object in the domain which may be referred to by different expressions (or
- mentions) occurring multiple times within a document (or across documents within
- a collection of documents). The Entity type has a feature named
- <emphasis>occurrences. </emphasis>This feature is used to point to all the
- annotations believed to label mentions of the same entity.</para>
-
- <para>Consider that the spans annotated by P1 and P2 were <quote>Fred
- Center</quote> and <quote>He</quote> respectively. The annotator might create
- a new Entity object called
- <code>FredCenter</code>. To represent the relationship in statement 3 above,
- the annotator may link FredCenter to both P1 and P2 by making them values of its
- <emphasis>occurrences</emphasis> feature.</para>
-
- <para> <xref linkend="ugr.ovv.conceptual.metadata_in_cas"/> also
- illustrates that an entity may be linked to annotations referring to regions of
- image documents as well. To do this the annotation type would have to be extended
- with the appropriate features to point to regions of an image.</para>
- </section>
-
- <section id="ugr.ovv.conceptual.multiple_views_within_a_cas">
- <title>Multiple Views within a CAS</title>
-
- <para>UIMA supports the simultaneous analysis of multiple views of a document. This
- support comes in handy for processing multiple forms of the artifact, for example, the audio
- and the closed captioned views of a single speech stream, or the tagged and detagged
- views of an HTML document.</para>
-
- <para>AEs analyze one or more views of a document. Each view contains a specific
- <emphasis role="bold">subject of analysis(Sofa)</emphasis>, plus a set of
- indexes holding metadata indexed by that view. The CAS, overall, holds one or more
- CAS Views, plus the descriptive objects that represent the analysis results for
- each. </para>
-
- <para>Another common example of using CAS Views is for different translations of a
- document. Each translation may be represented with a different CAS View. Each
- translation may be described by a different set of analysis results. For more
- details on CAS Views and Sofas see <olink
- targetdoc="&uima_docs_tutorial_guides;"/> <olink
- targetdoc="&uima_docs_tutorial_guides;"
- targetptr="ugr.tug.mvs"/> and <olink
- targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.aas"/>. </para>
- </section>
- </section>
-
- <section id="ugr.ovv.conceptual.interacting_with_cas_and_external_resources">
- <title>Interacting with the CAS and External Resources</title>
- <titleabbrev>Using CASes and External Resources</titleabbrev>
-
- <para>The two main interfaces that a UIMA component developer interacts with are the
- CAS and the UIMA Context.</para>
-
- <para>UIMA provides an efficient implementation of the CAS with multiple programming
- interfaces. Through these interfaces, the annotator developer interacts with the
- document and reads and writes analysis results. The CAS interfaces provide a suite of
- access methods that allow the developer to obtain indexed iterators to the different
- objects in the CAS. See <olink targetdoc="&uima_docs_ref;"/> <olink targetdoc="&uima_docs_ref;"
- targetptr="ugr.ref.cas"/>. While many objects may exist in a CAS, the annotator
- developer can obtain a specialized iterator to all Person objects associated with a
- particular view, for example.</para>
-
- <para>For Java annotator developers, UIMA provides the JCas. This interface provides
- the Java developer with a natural interface to CAS objects. Each type declared in the
- type system appears as a Java Class; the UIMA framework renders the Person type as a
- Person class in Java. As the analysis algorithm detects mentions of persons in the
- documents, it can create Person objects in the CAS. For more details on how to interact
- with the CAS using this interface, refer to <olink targetdoc="&uima_docs_ref;"
- /> <olink targetdoc="&uima_docs_ref;"
- targetptr="ugr.ref.jcas"/>.</para>
-
- <para>The component developer, in addition to interacting with the CAS, can access
- external resources through the framework's resource manager interface
- called the <emphasis role="bold">UIMA Context</emphasis>. This interface, among
- other things, can ensure that different annotators working together in an aggregate
- flow may share the same instance of an external file or remote resource accessed
- via its URL, for example. For details on using
- the UIMA Context see <olink targetdoc="&uima_docs_tutorial_guides;"
- /> <olink targetdoc="&uima_docs_tutorial_guides;"
- targetptr="ugr.tug.aae"/>.</para>
-
- </section>
- <section id="ugr.ovv.conceptual.component_descriptors">
- <title>Component Descriptors</title>
- <para>UIMA defines interfaces for a small set of core components that users of the
- framework provide implmentations for. Annotators and Analysis Engines are two of
- the basic building blocks specified by the architecture. Developers implement them
- to build and compose analysis capabilities and ultimately applications.</para>
-
- <para>There are others components in addition to these, which we will learn about
- later, but for every component specified in UIMA there are two parts required for its
- implementation:</para>
-
- <orderedlist spacing="compact">
- <listitem><para>the declarative part and</para></listitem>
- <listitem><para>the code part.</para></listitem>
- </orderedlist>
-
- <para>The declarative part contains metadata describing the component, its
- identity, structure and behavior and is called the <emphasis role="bold">
- Component Descriptor</emphasis>. Component descriptors are represented in XML.
- The code part implements the algorithm. The code part may be a program in Java.</para>
-
- <para>As a developer using the UIMA SDK, to implement a UIMA component it is always the
- case that you will provide two things: the code part and the Component Descriptor.
- Note that when you are composing an engine, the code may be already provided in
- reusable subcomponents. In these cases you may not be developing new code but rather
- composing an aggregate engine by pointing to other components where the code has been
- included.</para>
-
- <para>Component descriptors are represented in XML and aid in component discovery,
- reuse, composition and development tooling. The UIMA SDK provides tools for easily
- creating and maintaining the component descriptors that relieve the developer from
- editing XML directly. This tool is described briefly in <olink
- targetdoc="&uima_docs_tutorial_guides;"/> <olink
- targetdoc="&uima_docs_tutorial_guides;"
- targetptr="ugr.tug.aae"/>, and more
- thoroughly in <olink targetdoc="&uima_docs_tools;"/>
- <olink targetdoc="&uima_docs_tools;" targetptr="ugr.tools.cde"/>
- .</para>
-
- <para>Component descriptors contain standard metadata including the
- component's name, author, version, and a reference to the class that
- implements the component.</para>
-
- <para>In addition to these standard fields, a component descriptor identifies the
- type system the component uses and the types it requires in an input CAS and the types it
- plans to produce in an output CAS.</para>
-
- <para>For example, an AE that detects person types may require as input a CAS that
- includes a tokenization and deep parse of the document. The descriptor refers to a
- type system to make the component's input requirements and output types
- explicit. In effect, the descriptor includes a declarative description of the
- component's behavior and can be used to aid in component discovery and
- composition based on desired results. UIMA analysis engines provide an interface
- for accessing the component metadata represented in their descriptors. For more
- details on the structure of UIMA component descriptors refer to <olink
- targetdoc="&uima_docs_ref;"/> <olink
- targetdoc="&uima_docs_ref;" targetptr="ugr.ref.xml.component_descriptor"/>.</para>
-
- </section>
- </section>
- <section id="ugr.ovv.conceptual.aggregate_analysis_engines">
- <title>Aggregate Analysis Engines</title>
-
- <note><title>&key_concepts;</title><para>Aggregate Analysis Engine, Delegate Analysis Engine,
- Tightly and Loosely Coupled, Flow Specification, Analysis Engine Assembler</para>
- </note>
-
- <figure id="ugr.ovv.conceptual.sample_aggregate">
- <title>Sample Aggregate Analysis Engine</title>
- <mediaobject>
- <imageobject role="html">
- <imagedata width="588px" format="PNG" fileref="&imgroot;image006.png"/>
- </imageobject>
- <imageobject role="fo">
- <imagedata width="5.5in" format="PNG" fileref="&imgroot;image006.png"/>
- </imageobject>
- <textobject><phrase>Picture of multiple parts (a language identifier,
- tokenizer, part of speech annotator, shallow parser, and named entity detector)
- strung together into a flow, and all of them wrapped as a single aggregate object,
- which produces as annotations the union of all the results of the individual
- annotator components ( tokens, parts of speech, names, organizations, places,
- persons, etc.)</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
- <para>A simple or primitive UIMA Analysis Engine (AE) contains a single annotator. AEs,
- however, may be defined to contain other AEs organized in a workflow. These more complex
- analysis engines are called <emphasis role="bold">Aggregate Analysis
- Engines.</emphasis> </para>
-
- <para>Annotators tend to perform fairly granular functions, for example language
- detection, tokenization or part of speech detection.
- These functions typically address just part of an overall analysis task. A workflow
- of component engines may be orchestrated to perform more complex tasks.</para>
-
- <para>An AE that performs named entity detection, for example, may
- include a pipeline of annotators starting with language detection feeding
- tokenization, then part-of-speech detection, then deep grammatical parsing and then
- finally named-entity detection. Each step in the pipeline is required by the
- subsequent analysis. For example, the final named-entity annotator can only do its
- analysis if the previous deep grammatical parse was recorded in the CAS.</para>
-
- <para>Aggregate AEs are built to encapsulate potentially complex internal structure
- and insulate it from users of the AE. In our example, the aggregate analysis engine
- developer acquires the internal components, defines the necessary flow
- between them and publishes the resulting AE. Consider the simple example illustrated
- in <xref linkend="ugr.ovv.conceptual.sample_aggregate"/> where
- <quote>MyNamed-EntityDetector</quote> is composed of a linear flow of more
- primitive analysis engines.</para>
-
- <para>Users of this AE need not know how it is constructed internally but only need its name
- and its published input requirements and output types. These must be declared in the
- aggregate AE's descriptor. Aggregate AE's descriptors declare the components
- they contain and a <emphasis role="bold">flow specification</emphasis>. The flow
- specification defines the order in which the internal component AEs should be run. The
- internal AEs specified in an aggregate are also called the <emphasis role="bold">
- delegate analysis engines.</emphasis> The term "delegate" is used because aggregate AE's
- are thought to "delegate" functions to their internal AEs.</para>
-
- <para>
- In UIMA 2.0, the developer can implement a "Flow Controller" and include it as part
- of an aggregate AE by referring to it in the aggregate AE's descriptor.
- The flow controller is responsible for computing the "flow", that is,
- for determining the order in which of delegate AE's that will process the CAS.
- The Flow Contoller has access to the CAS and any external resources it may require
- for determining the flow. It can do this dynamically at run-time, it can
- make multi-step decisions and it can consider any sort of flow specification
- included in the aggregate AE's descriptor. See
- <olink targetdoc="&uima_docs_tutorial_guides;"/>
- <olink targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.fc"/>
- for details on the UIMA Flow Controller interface.
- </para>
-
- <para>We refer to the development role associated with building an aggregate from
- delegate AEs as the <emphasis role="bold">Analysis Engine Assembler</emphasis>
- .</para>
-
- <para>The UIMA framework, given an aggregate analysis engine descriptor, will run all
- delegate AEs, ensuring that each one gets access to the CAS in the sequence produced by
- the flow controller. The UIMA framework is equipped to handle different
- deployments where the delegate engines, for example, are <emphasis role="bold">
- tightly-coupled</emphasis> (running in the same process) or <emphasis role="bold">
- loosely-coupled</emphasis> (running in separate processes or even on different
- machines). The framework supports a number of remote protocols for loose coupling
- deployments of aggregate analysis engines.</para>
-
- <para>The UIMA framework facilitates the deployment of AEs as remote services by using an
- adapter layer that automatically creates the necessary infrastructure in response to
- a declaration in the component's descriptor. For more details on creating
- aggregate analysis engines refer to <olink targetdoc="&uima_docs_ref;"
- /> <olink targetdoc="&uima_docs_ref;"
- targetptr="ugr.ref.xml.component_descriptor"/> The component descriptor editor tool
- assists in the specification of aggregate AEs from a repository of available engines.
- For more details on this tool refer to <olink targetdoc="&uima_docs_tools;"
- /> <olink targetdoc="&uima_docs_tools;"
- targetptr="ugr.tools.cde"/>.</para>
-
- <para>The UIMA framework implementation has two built-in flow implementations: one
- that support a linear flow between components, and one with conditional branching
- based on the language of the document. It also supports user-provided flow
- controllers, as described in <olink targetdoc="&uima_docs_tutorial_guides;"
- /> <olink targetdoc="&uima_docs_tutorial_guides;"
- targetptr="ugr.tug.fc"/>. Furthermore, the application developer is
- free to create multiple AEs and provide their own logic to combine the AEs in arbitrarily
- complex flows. For more details on this the reader may refer to <olink
- targetdoc="&uima_docs_tutorial_guides;"/> <olink
- targetdoc="&uima_docs_tutorial_guides;"
- targetptr="ugr.tug.application.using_aes"/>.</para>
-
- </section>
-
- <section id="ugr.ovv.conceptual.applicaiton_building_and_collection_processing">
- <title>Application Building and Collection Processing</title>
-
- <note><title>&key_concepts;</title><para>Process Method, Collection Processing Architecture,
- Collection Reader, CAS Consumer, CAS Initializer, Collection Processing Engine,
- Collection Processing Manager.</para></note>
-
- <section id="ugr.ovv.conceptual.using_framework_from_an_application">
- <title>Using the framework from an Application</title>
-
- <figure id="ugr.ovv.conceptual.application_factory_ae">
- <title>Using UIMA Framework to create and interact with an Analysis Engine</title>
- <mediaobject>
- <imageobject role="html">
- <imagedata width="618px" align="center" format="PNG" fileref="&imgroot;image008.png"/>
- </imageobject>
- <imageobject role="fo">
- <imagedata width="5.5in" align="center" format="PNG" fileref="&imgroot;image008.png"/>
- </imageobject>
- <textobject><phrase>Picture of application interacting with UIMA's
- factory to produce an analysis engine, which acts as a container for annotators,
- and interfaces with the application via the process and getMetaData methods
- among others.</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
- <para>As mentioned above, the basic AE interface may be thought of as simply CAS in/CAS
- out.</para>
-
- <para>The application is responsible for interacting with the UIMA framework to
- instantiate an AE, create or acquire an input CAS, initialize the input CAS with a
- document and then pass it to the AE through the <emphasis role="bold">process
- method</emphasis>. This interaction with the framework is illustrated in <xref
- linkend="ugr.ovv.conceptual.application_factory_ae"/>. </para>
-
- <para>The UIMA AE Factory takes the declarative information from the Component
- Descriptor and the class files implementing the annotator, and instantiates the AE
- instance, setting up the CAS and the UIMA Context.</para>
-
- <para>The AE, possibly calling many delegate AEs internally, performs the overall
- analysis and its process method returns the CAS containing new analysis results.
- </para>
-
- <para>The application then decides what to do with the returned CAS. There are many
- possibilities. For instance the application could: display the results, store the
- CAS to disk for post processing, extract and index analysis results as part of a search
- or database application etc.</para>
-
- <para>The UIMA framework provides methods to support the application developer in
- creating and managing CASes and instantiating, running and managing AEs. Details
- may be found in <olink targetdoc="&uima_docs_tutorial_guides;"
- /> <olink targetdoc="&uima_docs_tutorial_guides;"
- targetptr="ugr.tug.application"/>.</para>
- </section>
-
- <section id="ugr.ovv.conceptual.graduating_to_collection_processing">
- <title>Graduating to Collection Processing</title>
- <figure id="ugr.ovv.conceptual.fig.cpe">
- <title>High-Level UIMA Component Architecture from Source to Sink</title>
- <mediaobject>
- <imageobject role="html">
- <imagedata width="578px" format="PNG" align="center" fileref="&imgroot;image010.png"/>
- </imageobject>
- <imageobject role="fo">
- <imagedata width="5.5in" format="PNG" align="center" fileref="&imgroot;image010.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Many UIM applications analyze entire collections of documents. They connect to
- different document sources and do different things with the results. But in the
- typical case, the application must generally follow these logical steps:
-
- <orderedlist spacing="compact">
- <listitem><para>Connect to a physical source</para></listitem>
- <listitem><para>Acquire a document from the source</para></listitem>
- <listitem><para>Initialize a CAS with the document to be analyzed</para>
- </listitem>
- <listitem><para>Send the CAS to a selected analysis engine</para></listitem>
- <listitem><para>Process the resulting CAS</para></listitem>
- <listitem><para>Go back to 2 until the collection is processed</para>
- </listitem>
- <listitem><para>Do any final processing required after all the documents in the
- collection have been analyzed</para></listitem>
- </orderedlist> </para>
-
- <para>UIMA supports UIM application development for this general type of processing
- through its <emphasis role="bold">Collection Processing
- Architecture</emphasis>.</para>
-
- <para>As part of the collection processing architecture UIMA introduces two primary
- components in addition to the annotator and analysis engine. These are the <emphasis
- role="bold">Collection Reader</emphasis> and the <emphasis role="bold">CAS
- Consumer</emphasis>. The complete flow from source, through document analysis,
- and to CAS Consumers supported by UIMA is illustrated in <xref
- linkend="ugr.ovv.conceptual.fig.cpe"/>.</para>
-
- <para>The Collection Reader's job is to connect to and iterate through a source
- collection, acquiring documents and initializing CASes for analysis. </para>
-
- <!--
- <para>Since the structure, access and iteration methods for
- physical document sources vary independently from the format of stored
- documents, UIMA defines another type of component called a <emphasis role="bold">CAS Intializer</emphasis>.
- The CAS Initializer's job is specific to a
- document format and specialized logic for mapping that format to a CAS. In the
- simplest case a CAS Intializer may take the document provided by the containing
- Collection Reader and insert it as a subject of analysis (or Sofa) in the
- CAS. A more advanced scenario is one
- where the CAS Intializer may be implemented to handle documents that conform to
- a certain XML schema and map some subset of the XML tags to CAS types and then
- insert the de-tagged document content as the subject of analysis. Collection Readers may reuse plug-in CAS
- Initializers for different document formats.</para>
- -->
-
- <para>CAS Consumers, as the name suggests, function at the end of the flow. Their job is
- to do the final CAS processing. A CAS Consumer may be implemented, for example, to
- index CAS contents in a search engine, extract elements of interest and populate a
- relational database or serialize and store analysis results to disk for subsequent
- and further analysis. </para>
-
- <para>A UIMA <emphasis role="bold">Collection Processing Engine</emphasis> (CPE)
- is an aggregate component that specifies a <quote>source to sink</quote> flow from a
- Collection Reader though a set of analysis engines and then to a set of CAS Consumers.
- </para>
-
- <para>CPEs are specified by XML files called CPE Descriptors. These are declarative
- specifications that point to their contained components (Collection Readers,
- analysis engines and CAS Consumers) and indicate a flow among them. The flow
- specification allows for filtering capabilities to, for example, skip over AEs
- based on CAS contents. Details about the format of CPE Descriptors may be found in
- <olink targetdoc="&uima_docs_ref;"/>
- <olink targetdoc="&uima_docs_ref;" targetptr="ugr.ref.xml.cpe_descriptor"/>.
- </para>
-
- <figure id="ugr.ovv.conceptual.fig.cpm">
- <title>Collection Processing Manager in UIMA Framework</title>
- <mediaobject>
- <imageobject role="html">
- <imagedata width="576px" align="center" format="PNG" fileref="&imgroot;image012.png"/>
- </imageobject>
- <imageobject role="fo">
- <imagedata width="5.5in" align="center" format="PNG" fileref="&imgroot;image012.png"/>
- </imageobject>
- <textobject><phrase>box and arrows picture of application using CPE factory to
- instantiate a Collection Processing Engine, and that engine interacting with
- the application.</phrase></textobject>
- </mediaobject>
- </figure>
-
- <para>The UIMA framework includes a <emphasis role="bold">Collection Processing
- Manager</emphasis> (CPM). The CPM is capable of reading a CPE descriptor, and
- deploying and running the specified CPE. <xref
- linkend="ugr.ovv.conceptual.fig.cpe"/> illustrates the role of the CPM
- in the UIMA Framework.</para>
-
- <para>Key features of the CPM are failure recovery, CAS management and scale-out.
- </para>
-
- <para>Collections may be large and take considerable time to analyze. A configurable
- behavior of the CPM is to log faults on single document failures while continuing to
- process the collection. This behavior is commonly used because analysis components
- often tend to be the weakest link -- in practice they may choke on strangely formatted
- content. </para>
-
- <para>This deployment option requires that the CPM run in a separate process or a
- machine distinct from the CPE components. A CPE may be configured to run with a variety
- of deployment options that control the features provided by the CPM. For details see
- <olink targetdoc="&uima_docs_ref;"/>
- <olink targetdoc="&uima_docs_ref;" targetptr="ugr.ref.xml.cpe_descriptor"/>
- .</para>
-
- <para>The UIMA SDK also provides a tool called the CPE Configurator. This tool provides
- the developer with a user interface that simplifies the process of connecting up all
- the components in a CPE and running the result. For details on using the CPE
- Configurator see <olink targetdoc="&uima_docs_tools;"
- /> <olink targetdoc="&uima_docs_tools;"
- targetptr="ugr.tools.cpe"/>. This tool currently does not provide
- access to the full set of CPE deployment options supported by the CPM; however, you can
- configure other parts of the CPE descriptor by editing it directly. For details on how
- to create and run CPEs refer to <olink targetdoc="&uima_docs_tutorial_guides;"
- /> <olink targetdoc="&uima_docs_tutorial_guides;"
- targetptr="ugr.tug.cpe"/>.</para>
-
- </section>
-
- </section>
-
- <section id="ugr.ovv.conceptual.exploiting_analysis_results">
- <title>Exploiting Analysis Results</title>
-
- <note><title>&key_concepts;</title><para>Semantic Search, XML Fragment Queries.</para>
- </note>
-
- <section id="ugr.ovv.conceptual.semantic_search">
- <title>Semantic Search</title>
-
- <para>In a simple UIMA Collection Processing Engine (CPE), a Collection Reader reads
- documents from the file system and initializes CASs with their content. These are
- then fed to an AE that annotates tokens and sentences, the CASs, now enriched with
- token and sentence information, are passed to a CAS Consumer that populates a search
- engine index. </para>
-
- <para>The search engine query processor can then use the token index to provide basic
- key-word search. For example, given a query <quote>center</quote> the search
- engine would return all the documents that contained the word
- <quote>center</quote>.</para>
-
- <para><emphasis role="bold">Semantic Search</emphasis> is a search paradigm that
- can exploit the additional metadata generated by analytics like a UIMA CPE.</para>
-
- <para>Consider that we plugged a named-entity recognizer into the CPE described
- above. Assume this analysis engine is capable of detecting in documents and
- annotating in the CAS mentions of persons and organizations.</para>
-
- <para>Complementing the name-entity recognizer we add a CAS Consumer that extracts in
- addition to token and sentence annotations, the person and organizations added to
- the CASs by the name-entity detector. It then feeds these into the semantic search
- engine's index.</para>
-
- <para>A semantic search engine can exploit
- this addition information from the CAS to support more powerful queries. For
- example, imagine a user is looking for documents that mention an organization with
- <quote>center</quote> it is name but is not sure of the full or precise name of the
- organization. A key-word search on <quote>center</quote> would likely produce way
- too many documents because <quote>center</quote> is a common and ambiguous term.
- A semantic search engine might support a query language called
- <emphasis role="bold">XML Fragments</emphasis>. This query language is
- designed to exploit the CAS annotations entered in its index. The XML Fragment query,
- for example,
-
-
- <programlisting><organization> center </organization></programlisting>
- will produce first only documents that contain <quote>center</quote> where it
- appears as part of a mention annotated as an organization by the name-entity
- recognizer. This will likely be a much shorter list of documents more precisely
- matching the user's interest.</para>
-
- <para>Consider taking this one step further. We add a relationship recognizer that
- annotates mentions of the CEO-of relationship. We configure the CAS Consumer so that
- it sends these new relationship annotations to the semantic search index as well.
- With these additional analysis results in the index we can submit queries like
-
-
- <programlisting><ceo_of>
- <person> center </person>
- <organization> center </organization>
-<ceo_of></programlisting>
- This query will precisely target documents that contain a mention of an organization
- with <quote>center</quote> as part of its name where that organization is mentioned
- as part of a
- <code>CEO-of</code> relationship annotated by the relationship
- recognizer.</para>
-
- <para>For more details about using UIMA and Semantic Search see the section on
- integrating text analysis and search in <olink
- targetdoc="&uima_docs_tutorial_guides;"/> <olink
- targetdoc="&uima_docs_tutorial_guides;"
- targetptr="ugr.tug.application"/>.</para>
- </section>
-
- <section id="ugr.ovv.conceptual.databases">
- <title>Databases</title>
-
- <para>Search engine indices are not the only place to deposit analysis results for use
- by applications. Another classic example is populating databases. While many
- approaches are possible with varying degrees of flexibly and performance all are
- highly dependent on application specifics. We included a simple sample CAS Consumer
- that provides the basics for getting your analysis result into a relational
- database. It extracts annotations from a CAS and writes them to a relational
- database, using the open source Apache Derby database.</para>
- </section>
- </section>
-
- <section id="ugr.ovv.conceptual.multimodal_processing">
- <title>Multimodal Processing in UIMA</title>
- <para>In previous sections we've seen how the CAS is initialized with an initial
- artifact that will be subsequently analyzed by Analysis engines and CAS Consumers. The
- first Analysis engine may make some assertions about the artifact, for example, in the
- form of annotations. Subsequent Analysis engines will make further assertions about
- both the artifact and previous analysis results, and finally one or more CAS Consumers
- will extract information from these CASs for structured information storage.</para>
- <figure id="ugr.ovv.conceptual.fig.multiple_sofas">
- <title>Multiple Sofas in support of multi-modal analysis of an audio Stream. Some
- engines work on the audio <quote>view</quote>, some on the text
- <quote>view</quote> and some on both.</title>
- <mediaobject>
- <imageobject role="html">
- <imagedata width="576px" format="PNG" align="center" fileref="&imgroot;image014.png"/>
- </imageobject>
- <imageobject role="fo">
- <imagedata width="5.5in" format="PNG" align="center" fileref="&imgroot;image014.png"/>
- </imageobject>
- <textobject><phrase>Picture showing audio on the left broken into segments by a
- segmentation component, then sent to multiple analysis pipelines in parallel,
- some processing the raw audio, others processing the recognized speech as
- text.</phrase></textobject>
- </mediaobject>
- </figure>
- <para>Consider a processing pipeline, illustrated in <xref
- linkend="ugr.ovv.conceptual.fig.multiple_sofas"/>, that starts with an
- audio recording of a conversation, transcribes the audio into text, and then extracts
- information from the text transcript. Analysis Engines at the start of the pipeline are
- analyzing an audio subject of analysis, and later analysis engines are analyzing a text
- subject of analysis. The CAS Consumer will likely want to build a search index from
- concepts found in the text to the original audio segment covered by the concept.</para>
-
- <para>What becomes clear from this relatively simple scenario is that the CAS must be
- capable of simultaneously holding multiple subjects of analysis. Some analysis
- engine will analyze only one subject of analysis, some will analyze one and create
- another, and some will need to access multiple subjects of analysis at the same time.
- </para>
-
- <para>The support in UIMA for multiple subjects of analysis is called <emphasis
- role="bold">Sofa</emphasis> support; Sofa is an acronym which is derived from
- <emphasis role="underline">S</emphasis>ubject <emphasis role="underline">
- of</emphasis> <emphasis role="underline">A</emphasis>nalysis, which is a physical
- representation of an artifact (e.g., the detagged text of a web-page, the HTML
- text of the same web-page, the audio segment of a video, the close-caption text
- of the same audio segment). A Sofa may
- be associated with CAS Views. A particular CAS will have one or more views, each view
- corresponding to a particular subject of analysis, together with a set of the defined
- indexes that index the metadata (that is, Feature Structures) created in that view.</para>
-
- <para>Analysis results can be indexed in, or <quote>belong</quote> to, a specific view.
- UIMA components may be written in <quote>Multi-View</quote> mode - able to create and
- access multiple Sofas at the same time, or in <quote>Single-View</quote> mode, simply
- receiving a particular view of the CAS corresponding to a particular single Sofa. For
- single-view mode components, it is up to the person assembling the component to supply
- the needed information to insure a particular view is passed to the component at run
- time. This is done using XML descriptors for Sofa mapping (see <olink
- targetdoc="&uima_docs_tutorial_guides;"/> <olink
- targetdoc="&uima_docs_tutorial_guides;"
- targetptr="ugr.tug.mvs.sofa_name_mapping"/>).</para>
-
- <para>Multi-View capability brings benefits to text-only processing as well. An input
- document can be transformed from one format to another. Examples of this include
- transforming text from HTML to plain text or from one natural language to another.
- </para>
- </section>
-
- <section id="ugr.ovv.conceptual.next_steps">
- <title>Next Steps</title>
-
- <para>This chapter presented a high-level overview of UIMA concepts. Along the way, it
- pointed to other documents in the UIMA SDK documentation set where the reader can find
- details on how to apply the related concepts in building applications with the UIMA
- SDK.</para>
-
- <para>At this point the reader may return to the documentation guide in <olink
- targetdoc="&uima_docs_overview;" targetptr="ugr.project_overview_doc_use"/>
- to learn how they might proceed in getting started using UIMA.</para>
-
- <para>For a more detailed overview of the UIMA architecture, framework and development
- roles we refer the reader to the following paper:</para>
-
- <para>D. Ferrucci and A. Lally, <quote>Building an example application using the
- Unstructured Information Management Architecture,</quote> <emphasis>IBM Systems
- Journal</emphasis> <emphasis role="bold">43</emphasis>, No. 3, 455-475 (2004).
- </para>
-
- <para>This paper can be found on line at <ulink
- url="http://www.research.ibm.com/journal/sj43-3.html"/></para>
- </section>
-
-</chapter>
diff --git a/uima-docbook-overview-and-setup/src/docbook/eclipse_setup.xml b/uima-docbook-overview-and-setup/src/docbook/eclipse_setup.xml
deleted file mode 100644
index d3010c9df..000000000
--- a/uima-docbook-overview-and-setup/src/docbook/eclipse_setup.xml
+++ /dev/null
@@ -1,431 +0,0 @@
-<?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/overview-and-setup/eclipse_setup_files/" >
-<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >
-%uimaents;
-]>
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-<chapter id="ugr.ovv.eclipse_setup">
- <title>Setting up the Eclipse IDE to work with UIMA</title>
- <titleabbrev>Eclipse IDE setup for UIMA</titleabbrev>
-
- <para>This chapter describes how to set up the UIMA SDK to work with Eclipse. Eclipse (<ulink
- url="&url_eclipse;"/>) is a popular open-source Integrated Development
- Environment for many things, including Java. The UIMA SDK does not require that you use
- Eclipse. However, we recommend that you do use Eclipse because some useful UIMA SDK tools
- run as plug-ins to the Eclipse platform and because the UIMA SDK examples are provided in a
- form that's easy to import into your Eclipse environment.</para>
-
- <para>If you are not planning on using the UIMA SDK with Eclipse, you may skip this chapter and
- read <olink targetdoc="&uima_docs_tutorial_guides;"/>
- <olink targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.aae"/>
- next.</para>
-
- <para>This chapter provides instructions for
-
- <itemizedlist spacing="compact"><listitem><para>installing Eclipse, </para>
- </listitem>
-
- <listitem><para>installing the UIMA SDK's Eclipse plugins into your Eclipse
- environment, and </para></listitem>
-
- <listitem><para>importing the example UIMA code into an Eclipse project. </para>
- </listitem></itemizedlist></para>
-
- <para>The UIMA Eclipse plugins are designed to be used with Eclipse version 4.10 (2018-12) or
- later.
- </para>
-
- <note><para>You will need to run Eclipse using a Java at the 1.8 or later level, in order
- to use the UIMA Eclipse plugins.</para></note>
-
- <section id="ugr.ovv.eclipse_setup.installation">
- <title>Installation</title>
- <section id="ugr.ovv.eclipse_setup.install_eclipse">
- <title>Install Eclipse</title>
-
- <itemizedlist spacing="compact"><listitem><para>Go to <ulink
- url="&url_eclipse;"/> and follow the instructions there to download Eclipse.
- </para></listitem>
-
- <listitem><para>We recommend using the latest release level.
- Navigate to the Eclipse Release version you
- want and download the archive for your platform.</para></listitem>
-
- <listitem><para>Unzip the archive to install Eclipse somewhere, e.g., c:\</para>
- </listitem>
-
- <listitem><para>Eclipse has a bit of a learning curve. If you plan to make
- significant use of Eclipse, check out the tutorial under the help menu. It is well
- worth the effort. There are also books you can get that describe Eclipse and its
- use.</para></listitem></itemizedlist>
-
- <para>The first time Eclipse starts up it will take a bit longer as it completes its
- installation. A <quote>welcome</quote> page will come up. After you are through
- reading the welcome information, click on the arrow to exit the welcome page and get to
- the main Eclipse screens.</para>
- </section>
-
- <section id="ugr.ovv.eclipse_setup.install_uima_eclipse_plugins">
- <title>Installing the UIMA Eclipse Plugins</title>
-
- <para>The best way to do this is to use the Eclipse Install New Software mechanism, because that will
- insure that all needed prerequisites are also installed. See below for an alternative,
- manual approach.</para>
-
- <note><para>If your computer is on an internet connection which uses a proxy server, you can
- configure Eclipse to know about that. Put your proxy settings into Eclipse using the
- Eclipse preferences by accessing the menus: Window → Preferences... →
- Install/Update, and Enable HTTP proxy connection under the Proxy Settings with the
- information about your proxy. </para></note>
-
-
- <para>To use the Eclipse Install New Software mechanism, start Eclipse, and then pick the menu
- <command>Help → Install new software...</command>. In the next page, enter
- the following URL in the "Work with" box and press enter:
- <itemizedlist>
- <listitem><para></para><code>https://www.apache.org/dist/uima/eclipse-update-site/</code> or</listitem>
- <listitem><para></para><code>https://www.apache.org/dist/uima/eclipse-update-site-v3/</code>.</listitem>
- </itemizedlist>
- Choose the 2nd if you are working with core UIMA Java SDK at version 3 or later.
- .</para>
-
- <para>Now select the plugin tools you wish to install, and click Next, and follow the
- remaining panels to install the UIMA plugins. </para>
- </section>
-
- <!--
- <section id="ugr.ovv.eclipse_setup.install_emf">
- <title>Manual Install additional Eclipse component: EMF</title>
- <para>You can skip this section if you installed EMF using the above process.</para>
-
- <warning><para>EMF comes in many versions; <emphasis role="bold">you must install
- the version that corresponds to the level of Eclipse that you are running.</emphasis>
- This is automatically done for you if you install it using the Eclipse update mechanism,
- described below. If you separately download an EMF package, you will need to verify it is
- the version that corresponds to the level of Eclipse you are running, before installing
- it.</para></warning>
-
- <para>Before installing EMF using these instructions, please go to <ulink
- url="&url_emf;"/> and read the installation instructions, and then click on the
- "Update Manager" link to see what url to use in the next step, where you use the built-in
- facilities in Eclipse to find and install new features. </para>
-
- <para> The exact way to install EMF changes from time to time. In the next few paragraphs,
- we try to give instructions that should work for most versions. Please see the end of
- this section for shortcut instructions for the current version of Eclipse at the time
- of this writing, Eclipse 3.3. </para>
-
- <para>Activate the software feature finding by using the menu: Help → Software
- Updates → Find and Install. Select <quote>Search for new features to
- install</quote>, push <quote>Next</quote>. Specify the update sites to use to
- search for EMF, making sure the <quote>Ignore features not applicable to this
- environment</quote> box is checked (at the bottom of the dialog), and push
- <quote>Finish</quote>. A good site to use is one of the Discovery Sites (e.g. Callisto or Europa) - which has a
- collection of Eclipse components including EMF. </para>
-
- <para>This will launch a search for updates to Eclipse; it may show a list of update site
- mirrors – click OK. When it finishes, it shows a list of possible updates in an
- expandable tree. Expand the tree nodes to find EMF SDK. The specific level may vary
- from the level shown below as newer versions are released.</para>
-
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata width="4in" format="JPG" fileref="&imgroot;image002.jpg"/>
- </imageobject>
- <textobject><phrase>Screenshot showing search results for EMF</phrase>
- </textobject>
- </mediaobject>
- </informalfigure>
-
- <para>Click <quote>Next</quote>. Then pick Eclipse Modeling Framework (EMF), and
- push <quote>Next</quote>, accept any licensing agreements, etc., until it
- finishes the installation. It may say it's an <quote>unsigned feature</quote>;
- proceed by clicking <quote>Install</quote>. If it recommends restarting, you may
- do that.</para>
-
- <para>This will install EMF, without any extras. (If you want the whole EMF system,
- including source and documentation, you can pick the <quote>EMF SDK</quote> and the
- <quote>Examples for Eclipse Modeling Framework</quote>.)</para>
-
- <section id="ugr.ovv.eclipse_setup.install_emf_shortcut">
- <title>EMF Installation Shortcut for Eclipse 3.2</title>
- <para>Since Eclipse 3.2, all major Eclipse sub-projects coordinate their
- release timeframes and publish the consolidated releases. The code name
- for 3.2 was Callisto, the one for 3.3 is Europa. You can
- easily install EMF via the release discovery site as follows.
- <orderedlist>
- <listitem><para> From the Eclipse menu, select Help/Software Updates/Find
- and Install.../Search for new features to install. </para></listitem>
- <listitem><para> Check the "[release name] discovery site", push "Next". </para>
- </listitem>
- <listitem><para> Select a convenient mirror site. </para></listitem>
- <listitem><para> Check the EMF box under "Models and model development"
- </para></listitem>
- <listitem><para> Follow the instructions for the rest of the install. </para>
- </listitem>
- </orderedlist> </para>
- </section>
-
- </section>
- -->
-
- <section id="ugr.ovv.eclipse_setup.install_uima_sdk">
- <title>Install the UIMA SDK</title>
- <para>If you haven't already done so, please download and install the UIMA SDK from
- <ulink url="&url_apache_uima_download;"/>. Be sure to set the environmental variable
- UIMA_HOME pointing to the root of the installed UIMA SDK and run the
- <literal>adjustExamplePaths.bat</literal> or <literal>adjustExamplePaths.sh</literal>
- script, as explained in the README.</para>
-
- <para>The environmental parameter UIMA_HOME is used by the command-line scripts in the
- %UIMA_HOME%/bin directory as well as by eclipse run configurations in the uimaj-examples
- sample project.</para>
-
- </section>
-
- <section id="ugr.ovv.eclipse_setup.install_uima_eclipse_plugins_manually">
- <title>Installing the UIMA Eclipse Plugins, manually</title>
-
- <para>If you installed the UIMA plugins using the update mechanism above, please skip this section.</para>
-
- <para>If you are unable to use the Eclipse Update mechanism to install the UIMA plugins, you
- can do this manually. In the directory %UIMA_HOME%/eclipsePlugins (The environment variable
- %UIMA_HOME% is where you installed the UIMA SDK), you will see a set of folders. Copy these
- to your %ECLIPSE_HOME%/dropins directory (%ECLIPSE_HOME% is where you
- installed Eclipse).</para>
-
- </section>
-
- <section id="ugr.ovv.eclipse_setup.start_eclipse">
- <title>Start Eclipse</title>
- <para>If you have Eclipse running, restart it (shut it down, and start it again) using
- the
- <code>-clean</code> option; you can do this by running the command
- <command>eclipse -clean</command> (see explanation in the next section) in the
- directory where you installed Eclipse. You may want to set up a desktop shortcut at
- this point for Eclipse.</para>
-
- <section id="ugr.ovv.eclipse_setup.special_startup_parameter_clean">
- <title>Special startup parameter for Eclipse: -clean</title>
- <para>If you have modified the plugin structure (by copying or files directly in the
- file system) after you started it for the first time, please include
- the <quote>-clean</quote> parameter in the startup arguments to Eclipse,
- <emphasis>one time</emphasis> (after any plugin modifications were done). This
- is needed because Eclipse may not notice the changes you made, otherwise. This
- parameter forces Eclipse to reexamine all of its plugins at startup and recompute
- any cached information about them.</para>
- </section>
-
- </section>
- </section>
- <section id="ugr.ovv.eclipse_setup.example_code">
- <title>Setting up Eclipse to view Example Code</title>
- <para>Later chapters refer to example code. Here's how to create a special project in Eclipse to
- hold the examples.</para>
-
- <itemizedlist spacing="compact"><listitem><para>In Eclipse, if the Java
- perspective is not already open, switch to it by going to Window → Open Perspective
- → Java.</para></listitem>
-
- <listitem><para>Set up a class path variable named UIMA_HOME, whose value is the
- directory where you installed the UIMA SDK. This is done as follows:
-
- <itemizedlist><listitem><para>Go to Window → Preferences → Java
- → Build Path → Classpath Variables.</para></listitem>
-
- <listitem><para>Click <quote>New</quote></para></listitem>
-
- <listitem><para>Enter UIMA_HOME (all capitals, exactly as written) in the
- <quote>Name</quote> field.</para></listitem>
-
- <listitem><para>Enter your installation directory (e.g. <literal>C:/Program
- Files/apache-uima</literal>) in the <quote>Path</quote> field</para>
- </listitem>
-
- <listitem><para>Click <quote>OK</quote> in the <quote>New Variable
- Entry</quote> dialog</para></listitem>
-
- <listitem><para>Click <quote>OK</quote> in the <quote>Preferences</quote>
- dialog</para></listitem>
-
- <listitem><para>If it asks you if you want to do a full build, click
- <quote>Yes</quote> </para></listitem></itemizedlist></para>
- </listitem>
-
- <listitem><para>Select the File → Import menu option</para></listitem>
-
- <listitem><para>Select <quote>General/Existing Project into Workspace</quote> and click
- the <quote>Next</quote> button.</para></listitem>
-
- <listitem><para>Click <quote>Browse</quote> and browse to the
- %UIMA_HOME%/examples directory</para></listitem>
-
- <listitem><para>Click <quote>Finish.</quote> This will create a new project called
- <quote>uimaj-examples</quote> in your Eclipse workspace. There should be no
- compilation errors. </para></listitem></itemizedlist>
-
- <para>To verify that you have set up the project correctly, check that there are no error
- messages in the <quote>Problems</quote> view.</para>
-
- </section>
-
- <section id="ugr.ovv.eclipse_setup.adding_source">
- <title>Adding the UIMA source code to the jar files</title>
-
- <note><para>If you are running a current version of Eclipse, and have the m2e (Maven extensions for Eclipse)
- plugin installed, Eclipse should be able to automatically download the source for the jars, so you may not need
- to do anything special (it does take a few seconds, and you need an internet connection).</para></note>
- <para>Otherwise, if you would like to be able to jump to the UIMA source code in Eclipse or to step
- through it with the debugger, you can add the UIMA source code directly to the jar files. This is
- done via a shell script that comes with the source distribution. To add the source code
- to the jars, you need to:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Download and unpack the UIMA source distribution.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Download and install the UIMA binary distribution (the UIMA_HOME environment variable needs
- to be set to point to where you installed the UIMA binary distribution).
- </para>
- </listitem>
-
- <listitem>
- <para>"cd" to the root directory of the source distribution</para>
- </listitem>
-
- <listitem>
- <para>
- Execute the <command>src\main\readme_src\addSourceToJars</command> script in the root directory of the
- source distribution.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- This adds the source code to the jar files, and it will then be automatically available
- from Eclipse. There is no further Eclipse setup required.
- </para>
-
- </section>
-
-
- <section id="ugr.ovv.eclipse_setup.linking_uima_javadocs">
- <title>Attaching UIMA Javadocs</title>
-
- <para>The binary distribution also includes the UIMA Javadocs. They are
- attached to the UIMA library Jar files in the uima-examples project described
- above. You can attach the Javadocs to your own project as well.
- </para>
-
- <note><para>If you attached the source as described in the previous section, you
- don't need to attach the Javadocs because the source includes the Javadoc comments.</para></note>
-
- <para>Attaching the Javadocs enables Javadoc help for UIMA APIs. After they are
- attached, if you hover your mouse
- over a certain UIMA api element, the corresponding Javadoc will appear.
- You can then press <quote>F2</quote> to make the hover "stick", or
- <quote>Shift-F2</quote> to open the default
- web-browser on your system to let you browse the entire Javadoc information
- for that element.
- </para>
- <para>If this pop-up behavior is something you don't want, you can turn it off
- in the Eclipse preferences, in the menu Window → Preferences →
- Java → Editors → hovers.
- </para>
-
- <para>Eclipse also has a Javadoc "view" which you can show, using the Window →
- Show View → Javadoc.</para>
-
- <para>See <olink targetdoc="&uima_docs_ref;"/>
- <olink targetdoc="&uima_docs_ref;" targetptr="ugr.ref.javadocs.libraries"/>
- for information on how to set up a UIMA "library" with the Javadocs attached, which
- can be reused for other projects in your Eclipse workspace.</para>
-
- <para>You can attach the Javadocs to each UIMA library jar you think you might be
- interested in. It makes most sense
- for the uima-core.jar, you'll probably use the core APIs most of all.
- </para>
-
- <para>Here's a screenshot of what you should see when you hover your mouse pointer over the
- class name <quote>CAS</quote> in the source code.
- </para>
-
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata width="5.7in" format="JPG" fileref="&imgroot;image004.jpg"/>
- </imageobject>
- <textobject><phrase>Screenshot of mouse-over for UIMA APIs</phrase>
- </textobject>
- </mediaobject>
- </informalfigure>
-
- </section>
-
- <section id="ugr.ovv.eclipse_setup.running_external_tools_from_eclipse">
- <title>Running external tools from Eclipse</title>
-
- <para>You can run many tools without using Eclipse at all, by using the shell scripts in the
- UIMA SDK's bin directory. In addition, many tools can be run from inside Eclipse;
- examples are the Document Analyzer, CPE Configurator, CAS Visual Debugger,
- and JCasGen. The uimaj-examples project provides Eclipse launch
- configurations that make this easy to do.</para>
-
- <para>To run these tools from Eclipse:</para>
-
- <itemizedlist spacing="compact"><listitem><para>If the Java perspective is not
- already open, switch to it by going to Window → Open Perspective →
- Java.</para></listitem>
-
- <listitem><para>Go to Run → Run... </para></listitem>
-
- <listitem><para>In the window that appears, select <quote>UIMA CPE GUI</quote>,
- <quote>UIMA CAS Visual Debugger</quote>, <quote>UIMA JCasGen</quote>, or
- <quote>UIMA Document Analyzer</quote>
- from the list of run configurations on the left. (If you don't see, these, please
- select the uimaj-examples project and do a Menu → File
- → Refresh).</para></listitem>
-
- <listitem><para>Press the <quote>Run</quote> button. The tools should start. Close
- the tools by clicking the <quote>X</quote> in the upper right corner on the GUI.
- </para></listitem></itemizedlist>
-
- <para>For instructions on using the Document Analyzer and CPE Configurator,
- in the <olink targetdoc="&uima_docs_tools;"/> book see <olink
- targetdoc="&uima_docs_tools;" targetptr="ugr.tools.doc_analyzer"/>, and
- <olink targetdoc="&uima_docs_tools;" targetptr="ugr.tools.cpe"/> For
- instructions on using the CAS Visual Debugger and JCasGen, see <olink
- targetdoc="&uima_docs_tools;" targetptr="ugr.tools.cvd"/> and
- <olink targetdoc="&uima_docs_tools;" targetptr="ugr.tools.jcasgen"/></para>
-
- </section>
-
-</chapter>
diff --git a/uima-docbook-overview-and-setup/src/docbook/faqs.xml b/uima-docbook-overview-and-setup/src/docbook/faqs.xml
deleted file mode 100644
index f6cd391ee..000000000
--- a/uima-docbook-overview-and-setup/src/docbook/faqs.xml
+++ /dev/null
@@ -1,411 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
-<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >
-%uimaents;
-]>
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-<chapter id="ugr.faqs">
- <title>UIMA Frequently Asked Questions (FAQ's)</title>
- <titleabbrev>UIMA FAQ's</titleabbrev>
-
- <variablelist>
- <varlistentry id="ugr.faqs.what_is_uima">
- <term><emphasis role="bold">What is UIMA?</emphasis></term>
- <listitem><para>UIMA stands for Unstructured Information Management
- Architecture. It is component software architecture for the development,
- discovery, composition and deployment of multi-modal analytics for the analysis
- of unstructured information.</para>
- <para>UIMA processing occurs through a series of modules called
- <link linkend="ugr.faqs.annotator_versus_ae">analysis engines</link>. The result of analysis is an assignment of semantics to the elements of
- unstructured data, for example, the indication that the phrase
- <quote>Washington</quote> refers to a person's name or that it refers to a
- place.</para>
-
- <para>Analysis Engine's output can be saved in conventional structures,
- for example, relational databases or search engine indices, where the content
- of the original unstructured information may be efficiently accessed
- according to its inferred semantics. </para>
-
- <para>UIMA supports developers in creating,
- integrating, and deploying components across platforms and among dispersed
- teams working to develop unstructured information management
- applications.</para>
- </listitem>
- </varlistentry>
- <varlistentry id="ugr.faqs.pronounce">
- <term><emphasis role="bold">How do you pronounce UIMA?</emphasis></term>
- <listitem><para>You – eee – muh.
- <!-- Or, in IPA notation, /juːiːmə/ (which does not
- display correctly in our PDF documentation, so it's commented out). --></para></listitem>
- </varlistentry>
- <varlistentry id="ugr.faqs.difference_apache_uima">
- <term><emphasis role="bold">What's the difference between UIMA and the Apache UIMA?</emphasis></term>
- <listitem><para>UIMA is an architecture which specifies component interfaces,
- design patterns, data representations and development roles.</para>
-
- <para>Apache UIMA is an open source, Apache-licensed software project. It includes run-time
- frameworks in Java and C++, APIs and tools for implementing, composing, packaging
- and deploying UIMA components.</para>
-
- <para>The UIMA run-time framework allows developers to plug-in their components
- and applications and run them on different platforms and according to different
- deployment options that range from tightly-coupled (running in the same
- process space) to loosely-coupled (distributed across different processes or
- machines for greater scale, flexibility and recoverability).</para>
-
- <para>The UIMA project has several significant subprojects, including UIMA-AS (for flexibly
- scaling out UIMA pipelines over clusters of machines), uimaFIT (for a way of using UIMA without the xml descriptors; also provides
- many convenience methods), UIMA-DUCC (for managing clusters of
- machines running scaled-out UIMA "jobs" in a "fair" way), RUTA (Eclipse-based tooling and \
- a runtime framework for development of rule-based
- Annotators), Addons (where you can find many extensions), and uimaFIT supplying a Java centric
- set of friendlier interfaces and avoiding XML.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ugr.faqs.what_is_an_annotation">
-
- <term><emphasis role="bold">What is an Annotation?</emphasis></term>
- <listitem><para>An annotation is metadata that is associated with a region of a
- document. It often is a label, typically represented as string of characters. The
- region may be the whole document. </para>
-
- <para>An example is the label <quote>Person</quote> associated with the span of
- text <quote>George Washington</quote>. We say that <quote>Person</quote>
- annotates <quote>George Washington</quote> in the sentence <quote>George
- Washington was the first president of the United States</quote>. The
- association of the label
- <quote>Person</quote> with a particular span of text is an annotation. Another
- example may have an annotation represent a topic, like <quote>American
- Presidents</quote> and be used to label an entire document.</para>
-
- <para>Annotations are not limited to regions of texts. An annotation may annotate
- a region of an image or a segment of audio. The same concepts apply.</para>
- </listitem>
- </varlistentry>
-
-
- <varlistentry id="ugr.faqs.what_is_the_cas">
- <term><emphasis role="bold">What is the CAS?</emphasis></term>
- <listitem><para>The CAS stands for Common Analysis Structure. It provides
- cooperating UIMA components with a common representation and mechanism for
- shared access to the artifact being analyzed (e.g., a document, audio file, video
- stream etc.) and the current analysis results.</para></listitem>
- </varlistentry>
- <varlistentry id="ugr.faqs.what_does_the_cas_contain">
- <term><emphasis role="bold">What does the CAS contain?</emphasis></term>
- <listitem><para>The CAS is a data structure for which UIMA provides multiple
- interfaces. It contains and provides the analysis algorithm or application
- developer with access to</para>
-
- <itemizedlist spacing="compact">
-
- <listitem><para>the subject of analysis (the artifact being analyzed, like
- the document),</para></listitem>
-
- <listitem><para>the analysis results or metadata(e.g., annotations, parse
- trees, relations, entities etc.),</para></listitem>
-
- <listitem><para>indices to the analysis results, and</para></listitem>
-
- <listitem><para>the type system (a schema for the analysis results).</para>
- </listitem>
- </itemizedlist>
-
- <para>A CAS can hold multiple versions of the artifact being analyzed (for
- instance, a raw html document, and a detagged version, or an English version and a
- corresponding German version, or an audio sample, and the text that
- corresponds, etc.). For each version there is a separate instance of the results
- indices.</para></listitem>
- </varlistentry>
-
- <varlistentry id="ugr.faqs.only_annotations">
- <term><emphasis role="bold">Does the CAS only contain Annotations?</emphasis></term>
- <listitem><para>No. The CAS contains the artifact being analyzed plus the analysis
- results. Analysis results are those metadata recorded by <link linkend="ugr.faqs.annotator_versus_ae">analysis engines</link> in the
- CAS. The most common form of analysis result is the addition of an annotation. But an
- analysis engine may write any structure that conforms to the CAS's type
- system into the CAS. These may not be annotations but may be other things, for
- example links between annotations and properties of objects associated with
- annotations.</para>
- <para>The CAS may have multiple representations of the artifact being analyzed, each one
- represented in the CAS as a particular Subject of Analysis. or <link linkend="ugr.faqs.what_is_a_sofa">Sofa</link></para></listitem>
- </varlistentry>
-
- <varlistentry id="ugr.faqs.just_xml">
- <term><emphasis role="bold">Is the CAS just XML?</emphasis></term>
- <listitem><para>No, in fact there are many possible representations of the CAS. If all
- of the <link linkend="ugr.faqs.annotator_versus_ae">analysis engines</link> are running in the same process, an efficient, in-memory
- data object is used. If a CAS must be sent to an analysis engine on a remote machine, it
- can be done via an XML or a binary serialization of the CAS. </para>
-
- <para>The UIMA framework provides multiple serialization and de-serialization methods
- in various formats, including XML. See the Javadocs for the CasIOUtils class.
- </para></listitem>
- </varlistentry>
-
- <varlistentry id="ugr.faqs.what_is_a_type_system">
- <term><emphasis role="bold">What is a Type System?</emphasis></term>
- <listitem><para>Think of a type system as a schema or class model for the <link linkend="ugr.faqs.what_is_the_cas">CAS</link>. It defines
- the types of objects and their properties (or features) that may be instantiated in
- a CAS. A specific CAS conforms to a particular type system. UIMA components declare
- their input and output with respect to a type system. </para>
-
- <para>Type Systems include the definitions of types, their properties, range
- types (these can restrict the value of properties to other types) and
- single-inheritance hierarchy of types.</para></listitem>
- </varlistentry>
-
- <varlistentry id="ugr.faqs.what_is_a_sofa">
- <term><emphasis role="bold">What is a Sofa?</emphasis></term>
- <listitem><para>Sofa stands for “Subject of Analysis". A <link linkend="ugr.faqs.what_is_the_cas">CAS</link> is
- associated with a single artifact being analysed by a collection of UIMA analysis
- engines. But a single artifact may have multiple independent views, each of which
- may be analyzed separately by a different set of <link linkend="ugr.faqs.annotator_versus_ae">analysis engines</link>. For example,
- given a document it may have different translations, each of which are associated
- with the original document but each potentially analyzed by different engines. A
- CAS may have multiple Views, each containing a different Subject of Analysis
- corresponding to some version of the original artifact. This feature is ideal for
- multi-modal analysis, where for example, one view of a video stream may be the video
- frames and the other the close-captions.</para></listitem>
- </varlistentry>
-
- <varlistentry id="ugr.faqs.annotator_versus_ae">
- <term><emphasis role="bold">What's the difference between an Annotator and an Analysis
- Engine?</emphasis></term>
- <listitem><para>In the terminology of UIMA, an annotator is simply some code that
- analyzes documents and outputs <link linkend="ugr.faqs.what_is_an_annotation">annotations</link> on the content of the documents. The
- UIMA framework takes the annotator, together with metadata describing such
- things as the input requirements and outputs types of the annotator, and produces
- an analysis engine. </para>
-
- <para>Analysis Engines contain the framework-provided infrastructure that
- allows them to be easily combined with other analysis engines in different flows
- and according to different deployment options (collocated or as web services,
- for example). </para>
-
- <para>Analysis Engines are the framework-generated objects that an Application
- interacts with. An Annotator is a user-written class that implements the one of
- the supported Annotator interfaces.</para></listitem>
- </varlistentry>
-
- <varlistentry id="ugr.faqs.web_services">
- <term><emphasis role="bold">Are UIMA analysis engines web services?</emphasis></term>
- <listitem><para>They can be deployed as such. Deploying an analysis engine as a web
- service is one of the deployment options supported by the UIMA framework.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ugr.faqs.stateless_aes">
- <term><emphasis role="bold">Do Analysis Engines have to be
- "stateless"?</emphasis></term>
- <listitem><para>This is a user-specifyable option. The XML metadata for the
- component includes an
- <code>operationalProperties</code> element which can specify if multiple
- deployment is allowed. If true, then a particular instance of an Engine might not
- see all the CASes being processed. If false, then that component will see all of the
- CASes being processed. In this case, it can accumulate state information among all
- the CASes. Typically, Analysis Engines in the main analysis pipeline are marked
- multipleDeploymentAllowed = true. The CAS Consumer component, on the other hand,
- defaults to having this property set to false, and is typically associated with
- some resource like a database or search engine that aggregates analysis results
- across an entire collection.</para>
-
- <para>Analysis Engines developers are encouraged not to maintain state between
- documents that would prevent their engine from working as advertised if
- operated in a parallelized environment.</para></listitem>
- </varlistentry>
-
- <varlistentry id="ugr.faqs.uddi">
- <term><emphasis role="bold">Is engine meta-data compatible with web services and
- UDDI?</emphasis></term>
- <listitem><para>All UIMA component implementations are associated with Component
- Descriptors which represents metadata describing various properties about the
- component to support discovery, reuse, validation, automatic composition and
- development tooling. In principle, UIMA component descriptors are compatible
- with web services and UDDI. However, the UIMA framework currently uses its own XML
- representation for component metadata. It would not be difficult to convert
- between UIMA's XML representation and other standard representations.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ugr.faqs.scaling">
- <term><emphasis role="bold">How do you scale a UIMA application?</emphasis></term>
- <listitem><para>The UIMA framework allows components such as
- <link linkend="ugr.faqs.annotator_versus_ae">analysis engines</link> and
- CAS Consumers to be easily deployed as services or in other containers and managed
- by systems middleware designed to scale. UIMA applications tend to naturally
- scale-out across documents allowing many documents to be analyzed in
- parallel.</para>
- <para>The UIMA-AS project has extensive capabilities to flexibly scale a UIMA
- pipeline across multiple machines. The UIMA-DUCC project supports a
- unified management of large clusters of machines running multiple "jobs"
- each consisting of a pipeline with data sources and sinks.</para>
- <para>Within the core UIMA framework, there is a component called the CPM (Collection Processing
- Manager) which has features and configuration settings for scaling an
- application to increase its throughput and recoverability;
- the CPM was the earlier version of scaleout technology, and has been
- superceded by the UIMA-AS effort (although it is still supported).</para></listitem>
- </varlistentry>
-
- <varlistentry id="ugr.faqs.embedding">
- <term><emphasis role="bold">What does it mean to embed UIMA in systems middleware?</emphasis></term>
- <listitem><para>An example of an embedding would be the deployment of a UIMA analysis
- engine as an Enterprise Java Bean inside an application server such as IBM
- WebSphere. Such an embedding allows the deployer to take advantage of the features
- and tools provided by WebSphere for achieving scalability, service management,
- recoverability etc. UIMA is independent of any particular systems middleware, so
- <link linkend="ugr.faqs.annotator_versus_ae">analysis engines</link> could be deployed on other application servers as well.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ugr.faqs.cpm_versus_cpe">
- <term><emphasis role="bold">How is the CPM different from a CPE?</emphasis></term>
- <listitem><para>These name complimentary aspects of collection processing. The CPM
- (Collection Processing <emphasis role="bold">Manager</emphasis> is the part of
- the UIMA framework that manages the execution of a workflow of UIMA
- components orchestrated to analyze a large collection of documents. The UIMA
- developer does not implement or describe a CPM. It is a piece of infrastructure code
- that handles CAS transport, instance management, batching, check-pointing,
- statistics collection and failure recovery in the execution of a collection
- processing workflow.</para>
-
- <para>A Collection Processing Engine (CPE) is component created by the framework
- from a specific CPE descriptor. A CPE descriptor refers to a series of UIMA
- components including a Collection Reader, CAS Initializer, Analysis
- Engine(s) and CAS Consumers. These components are organized in a work flow and
- define a collection analysis job or CPE. A CPE acquires documents from a source
- collection, initializes CASs with document content, performs document
- analysis and then produces collection level results (e.g., search engine
- index, database etc). The CPM is the execution engine for a CPE.</para>
- </listitem>
- </varlistentry>
-
- <!--
- <varlistentry id="ugr.faqs.semantic_search">
- <term><emphasis role="bold">What is Semantic Search and what is its relationship to
- UIMA?</emphasis></term>
- <listitem><para>Semantic Search refers to a document search paradigm that allows
- users to search based not just on the keywords contained in the documents, but also
- on the semantics associated with the text by <link linkend="ugr.faqs.annotator_versus_ae">analysis engines</link>. UIMA applications
- perform analysis on text documents and generate semantics in the form of
- <link linkend="ugr.faqs.what_is_an_annotation">annotations</link> on regions of text. For example, a UIMA analysis engine may discover
- the text <quote>First Financial Bank</quote> to refer to an organization and
- annotated it as such. With traditional keyword search, the query
- <command>first</command> will return all documents that contain that word.
- <command>First</command> is a frequent and ambiguous term – it occurs a lot
- and can mean different things in different places. If the user is looking for
- organizations that contain that word <command>first</command> in their names,
- s/he will likely have to sift through lots of documents containing the word
- <quote>first</quote> used in different ways. Semantic Search exploits the
- results of analysis to allow more precise queries. For example, the semantic
- search query <emphasis><organization> first
- </organization></emphasis> will rank first documents that contain the
- word <quote>first</quote> as part of the name of an organization. The UIMA SDK
- documentation demonstrates how UIMA applications can be built using semantic
- search. It provides details about the XML Fragment Query language. This is the
- particular query language used by the semantic search engine that comes with the
- SDK.</para>
- </listitem>
- </varlistentry>
-
-
- <varlistentry id="ugr.faqs.xml_fragment_not_xml">
- <term><emphasis role="bold">Is an XML Fragment Query valid XML?</emphasis></term>
- <listitem><para>Not necessarily. The XML Fragment Query syntax is used to formulate
- queries interpreted by the semantic search engine that ships with the UIMA SDK.
- This query language relies on basic XML syntax as an intuitive way to describe
- hierarchical patterns of annotations that may occur in a <link linkend="ugr.faqs.what_is_the_cas">CAS</link>. The language
- deviates from valid XML in order to support queries over
- <quote>overlapping</quote> or <quote>cross-over</quote> annotations and
- other features that affect the interpretation of the query by the query processor.
- For example, it admits notations in the query to indicate whether a keyword or an
- annotation is optional or required to match a document.</para></listitem>
- </varlistentry>
- -->
-
- <varlistentry id="ugr.faqs.modalities_other_than_text">
- <term><emphasis role="bold">Does UIMA support modalities other than text?</emphasis></term>
- <listitem><para>The UIMA architecture supports the development, discovery,
- composition and deployment of multi-modal analytics including text, audio and
- video. Applications that process text, speech and video have been developed using
- UIMA. This release of the SDK, however, does not include examples of these
- multi-modal applications. </para>
-
- <para>It does however include documentation and programming examples for using
- the key feature required for building multi-modal applications. UIMA supports
- multiple subjects of analysis or <link linkend="ugr.faqs.what_is_a_sofa">Sofas</link>. These allow multiple views of a single
- artifact to be associated with a <link linkend="ugr.faqs.what_is_the_cas">CAS</link>. For example, if an artifact is a video
- stream, one Sofa could be associated with the video frames and another with the
- closed-captions text. UIMA's multiple Sofa feature is included and
- described in this release of the SDK.</para></listitem>
- </varlistentry>
-
- <varlistentry id="ugr.faqs.compare">
- <term><emphasis role="bold">How does UIMA compare to other similar work?</emphasis></term>
- <listitem><para>A number of different frameworks for NLP have preceded UIMA. Two of
- them were developed at IBM Research and represent UIMA's early roots. For
- details please refer to the UIMA article that appears in the IBM Systems Journal
- Vol. 43, No. 3 (<ulink
- url="http://www.research.ibm.com/journal/sj/433/ferrucci.html"/>
- ).</para>
-
- <para>UIMA has advanced that state of the art along a number of dimensions
- including: support for distributed deployments in different middleware
- environments, easy framework embedding in different software product
- platforms (key for commercial applications), broader architectural converge
- with its collection processing architecture, support for
- multiple-modalities, support for efficient integration across programming
- languages, support for a modern software engineering discipline calling out
- different roles in the use of UIMA to develop applications, the extensive use of
- descriptive component metadata to support development tooling, component
- discovery and composition. (Please note that not all of these features are
- available in this release of the SDK.)</para></listitem>
- </varlistentry>
-
- <varlistentry id="ugr.faqs.open_source">
- <term><emphasis role="bold">Is UIMA Open Source?</emphasis></term>
- <listitem><para>Yes. As of version 2, UIMA development has moved to Apache and is being
- developed within the Apache open source processes. It is licensed under the Apache
- version 2 license.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ugr.faqs.levels_required">
- <term><emphasis role="bold">What Java level and OS are required for the UIMA SDK?</emphasis></term>
- <listitem><para>As of release 3.0.0, the UIMA SDK requires Java 1.8.
- It has been tested on mainly on Windows and Linux platforms, with some
- testing on the MacOSX. Other
- platforms and JDK implementations will likely work, but have
- not been as significantly tested.</para></listitem>
- </varlistentry>
-
- <varlistentry id="ugr.faqs.building_apps_on_top_of_uima">
- <term><emphasis role="bold">Can I build my UIM application on top of UIMA?</emphasis></term>
- <listitem><para>Yes. Apache UIMA is licensed under the Apache version 2 license,
- enabling you to build and distribute applications which include the framework.
- </para></listitem>
- </varlistentry>
-
-
- </variablelist>
-</chapter>
diff --git a/uima-docbook-overview-and-setup/src/docbook/glossary.xml b/uima-docbook-overview-and-setup/src/docbook/glossary.xml
deleted file mode 100644
index 24e7ec8a5..000000000
--- a/uima-docbook-overview-and-setup/src/docbook/glossary.xml
+++ /dev/null
@@ -1,582 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
-<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >
-%uimaents;
-]>
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-<glossary id="ugr.glossary">
- <title>Glossary: Key Terms & Concepts</title>
- <titleabbrev>Glossary</titleabbrev>
- <!--
- <para></para>
- <glossary id="ugr.glossary.glossary">
- -->
- <!--
- <glossentry id="ugr.glossary.">
- <glossterm></glossterm>
- <glosssee otherterm="ugr.glossary."></glosssee>
- <glossdef>
- <para></para>
- <glossseealso otherterm="ugr.glossary."/>
- </glossdef>
- </glossentry>
- -->
- <glossentry id="ugr.glossary.aggregate">
- <glossterm>Aggregate &ae;</glossterm>
- <glossdef>
- <para>An <glossterm linkend="ugr.glossary.analysis_engine">Analysis Engine</glossterm>
- made up of multiple subcomponent
-&ae;s arranged in a flow. The
-flow can be one of the two built-in flows, or a custom flow provided by the user.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.analysis_engine">
- <glossterm>&ae;</glossterm>
- <glossdef><para>A program that analyzes artifacts (e.g. documents) and infers information about
-them, and which implements the UIMA &ae; interface Specification. It
-does not matter how the program is built, with what framework or whether or not
-it contains component (<quote>sub</quote>) &ae;s.</para>
- </glossdef>
- </glossentry>
-
-
- <glossentry id="ugr.glossary.annotation">
- <glossterm>Annotation</glossterm>
- <glossdef>
- <para>The association of a metadata, such as a label, with a region of text (or other
-type of artifact). For example, the label <quote>Person</quote> associated with a
-region of text <quote>John Doe</quote> constitutes an annotation. We say
-<quote>Person</quote> annotates the span of text from X to Y containing exactly
-<quote>John Doe</quote>. An annotation is represented as a special
- <glossterm linkend="ugr.glossary.type">type</glossterm>
-
-in a UIMA <glossterm linkend="ugr.glossary.type_system">type system</glossterm>.
- It is the type used to record
-the labeling of regions of a <glossterm linkend="ugr.glossary.sofa">Sofa</glossterm>.
- Annotations are <glossterm linkend="ugr.glossary.feature_structure">Feature Structures</glossterm>
- whose <glossterm linkend="ugr.glossary.type">Type</glossterm> is Annotation or a subtype
- of that.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.annotator">
- <glossterm>Annotator</glossterm>
- <glossdef>
- <para>A software
-component that implements the UIMA annotator interface. Annotators are
-implemented to produce and record annotations over regions of an artifact
-(e.g., text document, audio, and video).</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.application">
- <glossterm>Application</glossterm>
- <glossdef>
- <para>An application is the outer containing code that invokes
- the UIMA framework functions to instantiate an
- <glossterm linkend="ugr.glossary.analysis_engine">Analysis Engine</glossterm> or a
- <glossterm linkend="ugr.glossary.cpe">Collection Processing Engine</glossterm> from a particular
- descriptor, and run it.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.apache_uima_java_framework">
- <glossterm>Apache UIMA Java Framework</glossterm>
- <glossdef>
- <para>A Java-based implementation of the <glossterm linkend="ugr.glossary.uima">UIMA</glossterm>
- architecture. It provides a run-time environment in which developers can plug in and run their UIMA component
- implementations and with which they can build and deploy UIM applications. The framework is the
- core part of the <glossterm linkend="ugr.glossary.apache_uima_sdk">Apache UIMA SDK</glossterm>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.apache_uima_sdk">
- <glossterm>Apache UIMA Software Development Kit (SDK)</glossterm>
- <glossdef>
- <para>The SDK for which you are now reading the documentation. The SDK includes the framework
- plus additional components such as tooling and examples. Some of the tooling is Eclipse-based
- (<ulink url="http://www.eclipse.org/"/>).</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.cas">
- <glossterm>CAS</glossterm>
- <glossdef>
- <para>The UIMA Common Analysis Structure is
-the primary data structure which UIMA analysis components use to represent and
-share analysis results. It contains:</para>
-
-<itemizedlist><listitem><para>The artifact. This is the object
-being analyzed such as a text document or audio or video stream. The CAS
-projects one or more views of the artifact. Each view is referred to as a
- <glossterm linkend="ugr.glossary.sofa">Sofa</glossterm>.</para></listitem>
-
-
-<listitem><para>A type system description –
-indicating the types, subtypes, and their features. </para></listitem>
-
-
-<listitem><para>Analysis metadata – <quote>standoff</quote>
-annotations describing the artifact or a region of the artifact </para></listitem>
-
-
-<listitem><para>An index repository to support
-efficient access to and iteration over the results of analysis.
-</para></listitem></itemizedlist>
-
-<para>UIMA's primary interface to this structure is provided by
-a class called the Common Analysis System. We use <quote>CAS</quote> to refer to
-both the structure and system. Where the common analysis structure is used
-through a different interface, the particular implementation of the structure
-is indicated, For example, the <glossterm linkend="ugr.glossary.jcas">JCas</glossterm> is a native Java object
-representation of the contents of the common analysis structure.</para>
-
-<para>A CAS can have multiple views; each view has a unique
-representation of the artifact, and has its own index repository, representing
-results of analysis for that representation of the artifact.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.cas_consumer">
- <glossterm>CAS Consumer</glossterm>
- <glossdef>
- <para>A component that
-receives each CAS in the collection, usually after it has been processed by an
- <glossterm linkend="ugr.glossary.analysis_engine">Analysis Engine</glossterm>. It is responsible for taking the results from
-the CAS and using them for some purpose, perhaps storing selected results into
-a database, for instance. The CAS
-Consumer may also perform collection-level analysis, saving these results in an
-application-specific, aggregate data structure.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.cas_initializer">
- <glossterm>CAS Initializer (deprecated)</glossterm>
- <glossdef>
- <para>Prior to version 2, this was the component that took an
- undefined input form and produced a particular <glossterm linkend="ugr.glossary.sofa">Sofa</glossterm>.
- For version 2, this has been replaced with using any <glossterm linkend="ugr.glossary.analysis_engine">Analysis Engine</glossterm>
- which takes a particular <glossterm linkend="ugr.glossary.cas_view">CAS View</glossterm> and creates a
- new output Sofa. For example, if the document is HTML, an &ae; might
- create a Sofa which is a detagged version of an input CAS View, perhaps also
-creating annotations derived from the tags. For example <p> tags
-might be translated into Paragraph annotations in the CAS.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.cas_multiplier">
- <glossterm>CAS Multiplier</glossterm>
- <glossdef>
- <para>A component, implemented by a UIMA developer,
-that takes a CAS as input and produces 0 or more new CASes as output. Common use cases for a CAS Multiplier
- include creating alternative versions of an input <glossterm linkend="ugr.glossary.sofa">Sofa</glossterm>
- (see <glossterm linkend="ugr.glossary.cas_initializer">CAS Initializer</glossterm>), and breaking
- a large input CAS into smaller pieces, each of which is emitted as a
-separate output CAS. There are other
-uses, however, such as aggregating input CASes into a single output CAS.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.cas_processor">
- <glossterm>CAS Processor</glossterm>
- <glossdef>
- <para>A component of a Collection Processing Engine (CPE) that
-takes a CAS as input and returns a CAS as output. There are two types of CAS
-Processors: <glossterm linkend="ugr.glossary.analysis_engine">Analysis Engine</glossterm>s and
- <glossterm linkend="ugr.glossary.cas_consumer">CAS Consumer</glossterm>s.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.cas_view">
- <glossterm>CAS View</glossterm>
- <glossdef>
- <para>A CAS Object which shares the base CAS and type system
-definition and index specifications, but has a unique index repository and a
-particular <glossterm linkend="ugr.glossary.sofa">Sofa</glossterm>. Views are named, and applications and
-annotators can dynamically create additional views whenever they are needed.
-Annotations are made with respect to one view. Feature structures can have references to feature structures
- indexed in other views, as needed.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.cde">
- <glossterm>CDE</glossterm>
- <glossdef>
- <para>The Component Descriptor Editor. This
-is the Eclipse tool that lets you conveniently edit the UIMA descriptors;
- see <olink targetdoc="&uima_docs_tools;" targetptr="ugr.tools.cde"/>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.cpe">
- <glossterm>Collection Processing Engine (CPE)</glossterm>
- <glossdef>
- <para>Performs Collection Processing
-through the combination of a
- <glossterm linkend="ugr.glossary.collection_reader">Collection Reader</glossterm>,
- 0 or more <glossterm linkend="ugr.glossary.analysis_engine">Analysis Engine</glossterm>s,
- and zero or more <glossterm linkend="ugr.glossary.cas_consumer">CAS Consumer</glossterm>s.
-The Collection Processing Manager (CPM) manages the execution of the engine.</para>
- <para>The CPE also refers to the XML specification of the Collection Processing
- engine. The CPM reads a CPE specification and instantiates a CPE instance from it,
- and runs it.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.cpm">
- <glossterm>Collection Processing Manager (CPM)</glossterm>
- <glossdef>
- <para>The part of the framework that
-manages the execution of collection processing, routing CASs from the
- <glossterm linkend="ugr.glossary.collection_reader">Collection Reader</glossterm>
-
-to 0 or more <glossterm linkend="ugr.glossary.analysis_engine">Analysis Engine</glossterm>s
-and then to the 0 or more <glossterm linkend="ugr.glossary.cas_consumer">CAS Consumer</glossterm>s. The CPM
-provides feedback such as performance statistics and error reporting and supports
-other features such as parallelization and error handling.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.collection_reader">
- <glossterm>Collection Reader</glossterm>
- <glossdef>
- <para>A component
-that reads documents from some source, for example a file system or database.
-The collection reader initializes a CAS with this document.
- Each document is returned as a CAS that may then be processed by
- an <glossterm linkend="ugr.glossary.analysis_engine">Analysis Engine</glossterm>s. If the task of populating a CAS
-from the document is complex, you may use an arbitrarily complex chain of
- <glossterm linkend="ugr.glossary.analysis_engine">Analysis Engine</glossterm>s and have the last one
- create and initialize a new <glossterm linkend="ugr.glossary.sofa">Sofa</glossterm>.</para>
- </glossdef>
- </glossentry>
-
-<!--
- <glossentry id="ugr.glossary.fact_search">
- <glossterm>Fact Search</glossterm>
- <glossdef>
- <para>A search that given a fact pattern, returns facts
-extracted from a collection of documents by a set of &ae;s that
-match the fact pattern.</para>
- </glossdef>
- </glossentry>
- -->
-
- <glossentry id="ugr.glossary.feature_structure">
- <glossterm>Feature Structure</glossterm>
- <glossdef>
- <para>An instance of a <glossterm linkend="ugr.glossary.type">Type</glossterm>.
- Feature Structures are kept in the <glossterm linkend="ugr.glossary.cas">CAS, and may
- (optionally) be added to the defined <glossterm linkend="ugr.glossary.index">indexes</glossterm>.
- Feature Structures may contain references to other Feature Structures.
- Feature Structures whose type is Annotation or a subtype of that, are referred to as
- <glossterm linkend="ugr.glossary.annotation">annotations</glossterm>.</glossterm></para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.feature">
- <glossterm>Feature</glossterm>
- <glossdef>
- <para>A data member or attribute of a type. Each feature itself has an
-associated range type, the type of the value that it can hold. In the
-database analogy where types are tables, features are columns.
- In the world of structured data types, each feature is a <quote>field</quote>,
- or data member.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.flow_controller">
- <glossterm>Flow Controller</glossterm>
- <glossdef>
- <para>A component which implements the interfaces needed
-to specify a custom flow within an <glossterm linkend="ugr.glossary.aggregate">&aae;</glossterm>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.hybrid_analysis_engine">
- <glossterm>Hybrid &ae;</glossterm>
- <glossdef>
- <para>An <glossterm linkend="ugr.glossary.aggregate">&aae;</glossterm>
- where more than one of its component &ae;s are deployed
-the same address space and one or more are deployed remotely (part tightly and
-part loosely-coupled).</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.index">
- <glossterm>Index</glossterm>
- <glossdef>
- <para>Data in the CAS can only be retrieved using Indexes.
- Indexes are analogous to the indexes that are
-specified on tables of a database. Indexes belong to Index Repositories;
-there is one Repository for each
-view of the CAS. Indexes are specified
-to retrieve instances of some CAS Type (including its subtypes), and can be
-optionally sorted in a user-definable way.
- For example, all types derived from the UIMA
-built-in type <literal>uima.tcas.Annotation</literal> contain begin
-and end features, which mark the begin and end offsets in the text where this
-annotation occurs. There is a built-in index of Annotations that specifies that
-annotations are retrieved sequentially by sorting first on the value of the begin
-feature (ascending) and then by the value of the end feature (descending).
-In this case, iterating over the annotations, one first obtains annotations that
-come sequentially first in the text, while favoring longer annotations, in the case
-where two annotations start at the same offset. Users can define their own indexes
-as well.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.jcas">
- <glossterm>JCas</glossterm>
- <glossdef>
- <para>A Java object interface to the contents of the CAS.
- This interface uses additional generated Java classes, where each type in the CAS
-is represented as a Java class with the same name, each feature is represented with
-a getter and setter method, and each instance of a type is represented as a
-Java object of the corresponding Java class.</para>
- </glossdef>
- </glossentry>
-
-<!--
- <glossentry id="ugr.glossary.keyword_search">
- <glossterm>Keyword Search</glossterm>
- <glossdef>
- <para>The standard search method where one supplies words (or <quote>keywords</quote>)
-and candidate documents are returned.</para>
- </glossdef>
- </glossentry>
- -->
- <!--
- <glossentry id="ugr.glossary.knowledge_base">
- <glossterm>Knowledge Base</glossterm>
- <glossdef>
- <para>A collection of data that may be interpreted as a
-set of facts and rules considered true in a possible world.</para>
- </glossdef>
- </glossentry>
- -->
-
- <glossentry id="ugr.glossary.loosely_coupled_analysis_engine">
- <glossterm>Loosely-Coupled &ae;</glossterm>
- <glossdef>
- <para>An <glossterm linkend="ugr.glossary.aggregate">&aae;</glossterm>
- where no two of its component &ae;s run in the
-same address space but where each is remote with respect to the others that
-make up the aggregate. Loosely coupled engines are ideal for using
- remote &ae; services that are
-not locally available, or for quickly assembling and testing functionality in
-cross-language, cross-platform distributed environments. They also better enable
-distributed scaleable implementations where quick recoverability may have a
-greater impact on overall throughput than analysis speed.</para>
- </glossdef>
- </glossentry>
-
-<!-- -->
- <glossentry id="ugr.glossary.ontology">
- <glossterm></glossterm>
- <glossdef>
- <para>The part of a knowledge base that defines the semantics of the data
-axiomatically.</para>
- </glossdef>
- </glossentry>
- -->
-
- <glossentry id="ugr.glossary.pear">
- <glossterm>PEAR</glossterm>
- <glossdef>
- <para>An archive file that packages up a UIMA component with its code,
-descriptor files and other resources required to install and run it in another
-environment. You can generate PEAR files using utilities that come with the
-UIMA SDK.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.primitive_analysis_engine">
- <glossterm>Primitive &ae;</glossterm>
- <glossdef>
- <para>An <glossterm linkend="ugr.glossary.analysis_engine">Analysis Engine</glossterm>
- that is composed of a single
- <glossterm linkend="ugr.glossary.annotator">Annotator</glossterm>; one that has
-no component (or <quote>sub</quote>) &ae;s inside of it;
-contrast with
- <glossterm linkend="ugr.glossary.aggregate">&aae;</glossterm>.</para>
- </glossdef>
- </glossentry>
-
- <!--
- <glossentry id="ugr.glossary.semantic_search">
- <glossterm>Semantic Search</glossterm>
- <glossdef>
- <para> search where the semantic intent of the query is
-specified using one or more entity or relation specifiers. For example,
-one could specify that they are looking for a person (named) <quote>Bush.</quote>
-Such a query would then not return results about the kind of bushes that grow
-in your garden but rather just persons named Bush.</para>
- </glossdef>
- </glossentry>
- -->
-
- <glossentry id="ugr.glossary.structured_information">
- <glossterm>Structured Information</glossterm>
- <glossdef>
- <para>Items stored in structured resources such as
-search engine indices, databases or knowledge bases. The canonical example of
-structured information is the database table. Each element of information in
-the database is associated with a precisely defined schema where each table
-column heading indicates its precise semantics, defining exactly how the
-information should be interpreted by a computer program or end-user.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.sofa">
- <glossterm>Subject of Analysis (Sofa)</glossterm>
- <glossdef>
- <para>A piece of
-data (e.g., text document, image, audio segment, or video segment), which is intended
-for analysis by UIMA analysis components. It belongs to a
- <glossterm linkend="ugr.glossary.cas_view">CAS View</glossterm> which has the same name; there
- is a one-to-one correspondence between these. There can be multiple Sofas contained within
-one CAS, each one representing a different view of the original artifact – for example,
-an audio file could be the original artifact, and also be one Sofa, and another
-could be the output of a voice-recognition component, where the Sofa would be
-the corresponding text document. Sofas may be analyzed independently or
-simultaneously; they all co-exist within the CAS. </para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.tightly_coupled_analysis_engine">
- <glossterm>Tightly-Coupled &ae;</glossterm>
- <glossdef>
- <para>An <glossterm linkend="ugr.glossary.aggregate">&aae;</glossterm>
- where all of its component &ae;s run in the same address space.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.type">
- <glossterm>Type</glossterm>
- <glossdef>
- <para>A specification of an object in the
- <glossterm linkend="ugr.glossary.cas">CAS</glossterm> used to store the results of
-analysis. Types are defined using inheritance, so some types may be
-defined purely for the sake of defining other types, and are in this sense <quote>abstract
-types.</quote> Types usually contain
- <glossterm linkend="ugr.glossary.feature">Feature</glossterm>s, which are attributes, or
-properties of the type. A type is roughly equivalent to a class in an
-object oriented programming language, or a table in a database. Instances of types in the CAS
- may be indexed for retrieval.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.type_system">
- <glossterm>Type System</glossterm>
- <glossdef>
- <para>A collection of related <glossterm linkend="ugr.glossary.type">types</glossterm>.
- All components that can access the CAS,
-including <glossterm linkend="ugr.glossary.application">Applications</glossterm>,
- <glossterm linkend="ugr.glossary.analysis_engine">Analysis Engine</glossterm>s,
- <glossterm linkend="ugr.glossary.collection_reader">Collection Readers</glossterm>,
- <glossterm linkend="ugr.glossary.flow_controller">Flow Controllers</glossterm>, or
- <glossterm linkend="ugr.glossary.cas_consumer">CAS Consumers</glossterm>
-declare the type system that they use. Type systems are shared across &ae;s, allowing the outputs
- of one &ae; to be read as input by another &ae;.
-A type system is roughly analogous to a set of related classes in object
-oriented programming, or a set of related tables in a database. The type
-system / type / feature terminology comes from computational linguistics.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.unstructured_information">
- <glossterm>Unstructured Information</glossterm>
- <glossdef>
- <para>The canonical example of unstructured
-information is the natural language text document. The intended meaning of a
-document's content is only implicit and its precise interpretation by a
-computer program requires some degree of analysis to explicate the document's
-semantics. Other examples include audio, video and images. Contrast with
-<glossterm linkend="ugr.glossary.structured_information">Structured Information</glossterm>.
- </para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.uima">
- <glossterm>UIMA</glossterm>
- <glossdef>
- <para>UIMA is an acronym that stands for Unstructured Information Management Architecture;
- it is a software architecture which specifies component interfaces, design patterns
-and development roles for creating, describing, discovering, composing and
-deploying multi-modal analysis capabilities. The UIMA specification is being developed by a
- technical committee at <ulink url="http://www.oasis-open.org/committees/uima">OASIS</ulink>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.uima_java_framework">
- <glossterm>UIMA Java Framework</glossterm>
- <glossdef>
- <para>See <glossterm linkend="ugr.glossary.apache_uima_java_framework">Apache UIMA Java Framework</glossterm>.</para>
- <para/>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.uima_sdk">
- <glossterm>UIMA SDK</glossterm>
- <glossdef>
- <para>See <glossterm linkend="ugr.glossary.apache_uima_sdk">Apache UIMA SDK</glossterm>.</para>
- <para/>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.xcas">
- <glossterm>XCAS</glossterm>
- <glossdef>
- <para>An XML representation of the CAS. The XCAS can be used for saving
-and restoring CASs to and from streams. The UIMA SDK provides XCAS serialization and
-de-serialization methods for CASes. This is an older serialization format and
-new UIMA code should use the standard <glossterm linkend="ugr.glossary.xmi">XMI</glossterm>
-format instead.</para>
- </glossdef>
- </glossentry>
-
- <glossentry id="ugr.glossary.xmi">
- <glossterm>XML Metadata Interchange (XMI)</glossterm>
- <glossdef>
- <para>An OMG standard for representing
-object graphs in XML, which UIMA uses to serialize analysis results from the
-CAS to an XML representation. The UIMA SDK provides XMI serialization and
-de-serialization methods for CASes</para>
- </glossdef>
- </glossentry>
-
-
- <!--
- <glossentry id="ugr.glossary.">
- <glossterm></glossterm>
- <glossdef>
- <para></para>
- </glossdef>
- </glossentry>
- -->
-
- </glossary>
-
- <!--
-</chapter>
- -->
diff --git a/uima-docbook-overview-and-setup/src/docbook/known_issues.xml b/uima-docbook-overview-and-setup/src/docbook/known_issues.xml
deleted file mode 100644
index 2fcfd080e..000000000
--- a/uima-docbook-overview-and-setup/src/docbook/known_issues.xml
+++ /dev/null
@@ -1,68 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
-<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >
-%uimaents;
-]>
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-<chapter id="ugr.issues">
- <title>Known Issues</title>
- <titleabbrev>Known Issues</titleabbrev>
-
- <variablelist>
- <varlistentry id="ugr.issues.cr_to_xml">
- <term><emphasis role="bold">Sun Java 1.4.2_12 doesn't serialize CR characters to XML</emphasis></term>
- <listitem>
- <para>(Note: Apache UIMA now requires Java 1.5, so this issue is moot.) The XML serialization support in Sun Java 1.4.2_12 doesn't serialize CR characters to
- XML. As a result, if the document text contains CR characters, XCAS or XMI serialization
- will cause them to be lost, resulting in incorrect annotation offsets. This is exposed in
- the DocumentAnalyzer, with the highlighting being incorrect if the input document contains
- CR characters. </para>
- </listitem>
- </varlistentry>
- <varlistentry id="ugr.issues.jcasgen_java_1.4">
- <term><emphasis role="bold">JCasGen merge facility only supports Java levels 1.4 or earlier</emphasis></term>
- <listitem>
- <para>JCasGen has a facility to merge in user (hand-coded) changes with the code generated
- by JCasGen. This merging supports Java 1.4 constructs only. JCasGen generates Java 1.4
- compliant code, so as long as any code you change here also only uses Java 1.4 constructs, the
- merge will work, even if you're using Java 5 or later.
- If you use syntactic structures particular to Java 5 or later, the merge
- operation will likely fail to merge properly.</para>
- </listitem>
- </varlistentry>
- <varlistentry id="ugr.issues.libgcj.4.1.2">
- <term><emphasis role="bold">Descriptor editor in Eclipse tooling does not work with libgcj 4.1.2</emphasis></term>
- <listitem>
- <para>The descriptor editor in the Eclipse tooling does not work with libgcj 4.1.2, and
- possibly other versions of libgcj. This is apparently due to a bug in the implementation of
- their XML library, which results in a class cast error. libgcj is used as the default
- JVM for Eclipse in Ubuntu (and other Linux distributions?). The workaround is to use a
- different JVM to start Eclipse.</para>
- </listitem>
- </varlistentry>
- <!--
- <varlistentry>
- <term><emphasis role="bold"></emphasis></term>
- <listitem><para></para></listitem>
- </varlistentry>
- -->
- </variablelist>
-</chapter>
diff --git a/uima-docbook-overview-and-setup/src/docbook/overview_and_setup.xml b/uima-docbook-overview-and-setup/src/docbook/overview_and_setup.xml
deleted file mode 100644
index 54ca57b3a..000000000
--- a/uima-docbook-overview-and-setup/src/docbook/overview_and_setup.xml
+++ /dev/null
@@ -1,34 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
-<!--
-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.
--->
-<book lang="en" >
- <title>UIMA Overview & SDK Setup</title>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../target/docbook-shared/common_book_info_ibm_c.xml"/>
-
- <toc/>
-
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="project_overview.xml" />
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="conceptual_overview.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eclipse_setup.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="faqs.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="known_issues.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="glossary.xml"/>
-</book>
diff --git a/uima-docbook-overview-and-setup/src/docbook/project_overview.xml b/uima-docbook-overview-and-setup/src/docbook/project_overview.xml
deleted file mode 100644
index 8ffec2950..000000000
--- a/uima-docbook-overview-and-setup/src/docbook/project_overview.xml
+++ /dev/null
@@ -1,731 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
-<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >
-%uimaents;
-]>
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-<chapter id="ugr.project_overview">
- <title>UIMA Overview</title>
- <titleabbrev>Overview</titleabbrev>
-
- <para>The Unstructured Information Management Architecture (UIMA) is an architecture and software framework
- for creating, discovering, composing and deploying a broad range of multi-modal analysis capabilities and
- integrating them with search technologies. The architecture is undergoing a standardization effort,
- referred to as the <emphasis>UIMA specification</emphasis> by a technical committee within
- <ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=uima">OASIS</ulink>.
- </para>
-
- <para>The <emphasis>Apache UIMA</emphasis> framework is an Apache licensed, open source implementation of the
- UIMA Architecture, and provides a run-time environment in which developers can plug in
- and run their UIMA component implementations and with which they can build and deploy UIM applications. The
- framework itself is not specific to any IDE or platform.</para>
-
- <para>It includes an all-Java implementation of the
- UIMA framework for the development, description, composition and deployment of UIMA components and
- applications. It also provides the developer with an Eclipse-based (<ulink url="http://www.eclipse.org/"/>
- ) development environment that includes a set of tools and utilities for using UIMA. It also includes
- a C++ version of the framework, and
- enablements for Annotators built in Perl, Python, and TCL.</para>
-
- <para>This chapter is the intended starting point for readers that are new to the Apache UIMA Project. It includes
- this introduction and the following sections:</para>
- <itemizedlist>
- <listitem>
- <para> <xref linkend="ugr.project_overview_doc_overview"/> provides a list of the books and topics included in
- the Apache UIMA documentation with a brief summary of each. </para>
- </listitem>
- <listitem>
- <para> <xref linkend="ugr.project_overview_doc_use"/> describes a recommended path through the
- documentation to help get the reader up and running with UIMA </para>
- </listitem>
- </itemizedlist>
-
- <para>The main website for Apache UIMA is <ulink url="http://uima.apache.org"/>. Here you
- can find out many things, including:
- <itemizedlist spacing="compact">
- <listitem><para>how to download (both the binary and source distributions</para></listitem>
- <listitem><para>how to participate in the development</para></listitem>
- <listitem><para>mailing lists - including the user list used like a forum for questions and answers</para></listitem>
- <listitem><para>a Wiki where you can find and contribute all kinds of information, including tips and best practices</para></listitem>
- <listitem><para>a sandbox - a subproject for potential new additions to Apache UIMA or to subprojects of it. Things here
- are works in progress, and may (or may not) be included in releases.</para></listitem>
- <listitem><para>links to conferences</para></listitem>
- </itemizedlist>
- </para>
-
- <section id="ugr.project_overview_doc_overview">
- <title>Apache UIMA Project Documentation Overview</title>
- <para> The user documentation for UIMA is organized into several parts.
- <itemizedlist spacing="compact">
- <listitem>
- <para> Overviews - this documentation </para>
- </listitem>
- <listitem>
- <para> Eclipse Tooling Installation and Setup - also in this document </para>
- </listitem>
- <listitem>
- <para> Tutorials and Developer's Guides </para>
- </listitem>
- <listitem>
- <para> Tools Users' Guides </para>
- </listitem>
- <listitem>
- <para> References </para>
- </listitem>
- <listitem>
- <para>Version 3 users-guide</para>
- </listitem>
- </itemizedlist> </para>
-
- <para>
- The first 2 parts make up this book; the last 4 have individual
- books. The books are provided both as
- (somewhat large) html files, viewable in browsers, and also as PDF files.
- The documentation is fully hyperlinked, with tables of contents. The PDF versions are set up to
- print nicely - they have page numbers included on the cross references within a book. </para>
-
- <para>If you view the PDF files inside
- a browser that supports imbedded viewing of PDF, the hyperlinks between different PDF books may work (not
- all browsers have been tested...).</para>
-
- <para>The following set of tables gives a more detailed overview of the various parts of the
- documentation.
- </para>
-
- <section id="ugr.project_overview_overview">
- <title>Overviews</title>
-
- <informaltable frame="all" rowsep="1" colsep="1">
- <tgroup cols="2">
- <colspec colnum="1" colname="col1" colwidth="1*"/>
- <colspec colnum="2" colname="col2" colwidth="2.5*"/>
- <tbody>
- <row>
- <entry><emphasis>Overview of the Documentation</emphasis>
- </entry>
- <entry>
- <para>What you are currently reading. Lists the documents provided in the Apache
- UIMA documentation set and provides
- a recommended path through the documentation for getting started using
- UIMA. It includes release notes and provides a brief high-level description of
- the different software modules included in the
- Apache UIMA Project. See <xref linkend="ugr.project_overview_doc_overview"/>.</para>
- </entry>
- </row>
- <row>
- <entry><emphasis>Conceptual Overview</emphasis>
- </entry>
- <entry>Provides a broad conceptual overview of the UIMA component architecture; includes
- references to the other documents in the documentation set that provide more detail.
- See <xref linkend="ugr.ovv.conceptual"/></entry>
- </row>
- <row>
- <entry><emphasis>UIMA FAQs</emphasis>
- </entry>
- <entry>Frequently Asked Questions about general UIMA concepts. (Not a programming
- resource.) See <xref linkend="ugr.faqs"/>.</entry>
- </row>
- <row>
- <entry><emphasis>Known Issues</emphasis>
- </entry>
- <entry>Known issues and problems with the UIMA SDK. See <xref linkend="ugr.issues"/>.</entry>
- </row>
- <row>
- <entry><emphasis>Glossary</emphasis>
- </entry>
- <entry>UIMA terms and concepts and their basic definitions. See <xref linkend="ugr.glossary"/>.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
-
- <section id="ugr.project_overview_setup">
- <title>Eclipse Tooling Installation and Setup</title>
- <para>Provides step-by-step instructions for installing Apache UIMA in the Eclipse Interactive
- Development Environment. See <xref linkend="ugr.ovv.eclipse_setup"/>.</para>
- </section>
-
- <section id="ugr.project_overview_tutorials_dev_guides">
- <title>Tutorials and Developer's Guides</title>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colname="col1" colwidth="1*"/>
- <colspec colnum="2" colname="col2" colwidth="2.5*"/>
- <tbody>
- <row id="ugr.project_overview_tutorial_annotator">
- <entry><emphasis>Annotators and Analysis Engines</emphasis>
- </entry>
- <entry>Tutorial-style guide for building UIMA annotators and analysis engines. This chapter
- introduces the developer to creating type systems and using UIMA's common data structure,
- the CAS or Common Analysis Structure. It demonstrates how to use built in tools to specify and create
- basic UIMA analysis components. See
- <olink targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.aae"/>.</entry>
- </row>
- <row id="ugr.project_overview_tutorial_cpe">
- <entry><emphasis>Building UIMA Collection Processing Engines</emphasis>
- </entry>
- <entry>Tutorial-style guide for building UIMA collection processing engines. These
- manage the
- analysis of collections of documents from source to sink. See
- <olink targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.cpe"/>.</entry>
- </row>
- <row id="ugr.project_overview_tutorial_application_development">
- <entry><emphasis>Developing Complete Applications</emphasis>
- </entry>
- <entry>Tutorial-style guide on using the UIMA APIs to create, run and manage UIMA components from
- your application. Also describes APIs for saving and restoring the contents of a CAS using an XML
- format called <trademark class="registered"> XMI</trademark>. See
- <olink targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.application"/>.</entry>
- </row>
- <row id="ugr.project_overview_guide_flow_controller">
- <entry><emphasis>Flow Controller</emphasis>
- </entry>
- <entry>When multiple components are combined in an Aggregate, each CAS flow among the various
- components. UIMA provides two built-in flows, and also allows custom flows to be
- implemented. See <olink targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.fc"/>.</entry>
- </row>
- <row id="ugr.project_overview_guide_multiple_sofas">
- <entry><emphasis>Developing Applications using Multiple Subjects of Analysis</emphasis>
- </entry>
- <entry>A single CAS maybe associated with multiple subjects of analysis (Sofas). These are useful
- for representing and analyzing different formats or translations of the same document. For
- multi-modal analysis, Sofas are good for different modal representations of the same stream
- (e.g., audio and close-captions).This chapter provides the developer details on how to use
- multiple Sofas in an application. See
- <olink targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.aas"/>.</entry>
- </row>
- <row id="ugr.project_overview_guide_multiple_views">
- <entry><emphasis>Multiple CAS Views of an Artifact</emphasis>
- </entry>
- <entry>UIMA provides an extension to the basic model of the CAS which supports
- analysis of multiple views of the same artifact, all contained with the CAS. This
- chapter describes the concepts, terminology, and the API and XML extensions that
- enable this. See
- <olink targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.mvs"/>.</entry>
- </row>
- <row id="ugr.project_overview_guide_cas_multiplier">
- <entry><emphasis>CAS Multiplier</emphasis>
- </entry>
- <entry>A component may add additional CASes into the workflow. This may be useful to break up a large
- artifact into smaller units, or to create a new CAS that collects information from multiple other
- CASes. See <olink targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.cm"/>.</entry>
- </row>
- <row id="ugr.project_overview_xmi_emf">
- <entry><emphasis>XMI and EMF Interoperability</emphasis>
- </entry>
- <entry>The UIMA Type system and the contents of the CAS itself can be externalized using the XMI
- standard for XML MetaData. Eclipse Modeling Framework (EMF) tooling can be used to develop
- applications that use this information. See
- <olink targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.xmi_emf"/>.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
-
- <section id="ugr.project_overview_tool_guides">
- <title>Tools Users' Guides</title>
-
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colname="col1" colwidth="1*"/>
- <colspec colnum="2" colname="col2" colwidth="2.5*"/>
- <tbody>
- <row id="ugr.project_overview_tools_component_descriptor_editor">
- <entry><emphasis>Component Descriptor Editor</emphasis>
- </entry>
- <entry>Describes the features of the Component Descriptor Editor Tool. This tool provides a GUI for
- specifying the details of UIMA component descriptors, including those for Analysis Engines
- (primitive and aggregate), Collection Readers, CAS Consumers and Type Systems. See
- <olink targetdoc="&uima_docs_tools;" targetptr="ugr.tools.cde"/>.</entry>
- </row>
- <row id="ugr.project_overview_tools_cpe_configurator">
- <entry><emphasis>Collection Processing Engine Configurator</emphasis>
- </entry>
- <entry>Describes the User Interfaces and features of the CPE Configurator tool. This tool allows the
- user to select and configure the components of a Collection Processing Engine and then to run the
- engine. See
- <olink targetdoc="&uima_docs_tools;" targetptr="ugr.tools.cpe"/>.</entry>
- </row>
- <row id="ugr.project_overview_tools_pear_packager">
- <entry><emphasis>Pear Packager</emphasis>
- </entry>
- <entry>Describes how to use the PEAR Packager utility. This utility enables developers to produce an
- archive file for an analysis engine that includes all required resources for installing that
- analysis engine in another UIMA environment. See
- <olink targetdoc="&uima_docs_tools;" targetptr="ugr.tools.pear.packager"/>.</entry>
- </row>
- <row id="ugr.project_overview_tools_pear_installer">
- <entry><emphasis>Pear Installer</emphasis>
- </entry>
- <entry>Describes how to use the PEAR Installer utility. This utility installs and verifies an
- analysis engine from an archive file (PEAR) with all its resources in the right place so it is ready to
- run. See
- <olink targetdoc="&uima_docs_tools;" targetptr="ugr.tools.pear.installer"/>.</entry>
- </row>
- <row id="ugr.project_overview_tools_pear_merger">
- <entry><emphasis>Pear Merger</emphasis>
- </entry>
- <entry>Describes how to use the Pear Merger utility, which does a simple merge of multiple PEAR
- packages into one. See
- <olink targetdoc="&uima_docs_tools;" targetptr="ugr.tools.pear.merger"/>.</entry>
- </row>
- <row id="ugr.project_overview_tools_document_analyzer">
- <entry><emphasis>Document Analyzer</emphasis>
- </entry>
- <entry>Describes the features of a tool for applying a UIMA analysis engine to a set of documents and
- viewing the results. See
- <olink targetdoc="&uima_docs_tools;" targetptr="ugr.tools.doc_analyzer"/>.</entry>
- </row>
- <row id="ugr.project_overview_tools_cas_visual_debugger">
- <entry><emphasis>CAS Visual Debugger</emphasis>
- </entry>
- <entry>Describes the features of a tool for viewing the detailed structure and contents of a CAS. Good
- for debugging. See
- <olink targetdoc="&uima_docs_tools;" targetptr="ugr.tools.cvd"/>.</entry>
- </row>
- <row id="ugr.project_overview_tools_jcasgen">
- <entry><emphasis>JCasGen</emphasis>
- </entry>
- <entry>Describes how to run the JCasGen utility, which automatically builds Java classes that
- correspond to a particular CAS Type System. See
- <olink targetdoc="&uima_docs_tools;" targetptr="ugr.tools.jcasgen"/>.</entry>
- </row>
- <row id="ugr.project_overview_tools_xml_cas_viewer">
- <entry><emphasis>XML CAS Viewer</emphasis>
- </entry>
- <entry>Describes how to run the supplied viewer to view externalized XML forms of CASes. This viewer
- is used in the examples. See
- <olink targetdoc="&uima_docs_tools;" targetptr="ugr.tools.annotation_viewer"/>.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
-
- <section id="ugr.project_overview_reference">
- <title>References</title>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colname="col1" colwidth="1*"/>
- <colspec colnum="2" colname="col2" colwidth="2.5*"/>
- <tbody>
- <row id="ugr.project_overview_javadocs">
- <entry><emphasis>Introduction to the UIMA API Javadocs</emphasis>
- </entry>
- <entry>Javadocs detailing the UIMA programming interfaces See
- <olink targetdoc="&uima_docs_ref;" targetptr="ugr.ref.javadocs"/></entry>
- </row>
- <row id="ugr.project_overview_xml_ref_component_descriptor">
- <entry><emphasis>XML: Component Descriptor</emphasis>
- </entry>
- <entry>Provides detailed XML format for all the UIMA component descriptors, except the CPE (see
- next). See
- <olink targetdoc="&uima_docs_ref;" targetptr="ugr.ref.xml.component_descriptor"/>.</entry>
- </row>
- <row id="ugr.project_overview_xml_ref_collection_processing_engine_descriptor">
- <entry><emphasis>XML: Collection Processing Engine Descriptor</emphasis>
- </entry>
- <entry>Provides detailed XML format for the Collection Processing Engine descriptor. See
- <olink targetdoc="&uima_docs_ref;" targetptr="ugr.ref.xml.cpe_descriptor"/></entry>
- </row>
- <row id="ugr.project_overview_cas">
- <entry><emphasis>CAS</emphasis>
- </entry>
- <entry>Provides detailed description of the principal CAS interface. See
- <olink targetdoc="&uima_docs_ref;" targetptr="ugr.ref.cas"/></entry>
- </row>
- <row id="ugr.project_overview_jcas">
- <entry><emphasis>JCas</emphasis>
- </entry>
- <entry>Provides details on the JCas, a native Java interface to the CAS. See
- <olink targetdoc="&uima_docs_ref;" targetptr="ugr.ref.jcas"/></entry>
- </row>
- <row id="ugr.project_overview_ref_pear">
- <entry><emphasis>PEAR Reference</emphasis>
- </entry>
- <entry>Provides detailed description of the deployable archive format for UIMA
- components. See
- <olink targetdoc="&uima_docs_ref;" targetptr="ugr.ref.pear"/></entry>
- </row>
- <row id="ugr.project_overview_xmi_cas_serialization">
- <entry><emphasis>XMI CAS Serialization Reference</emphasis>
- </entry>
- <entry>Provides detailed description of the deployable archive format for UIMA
- components. See
- <olink targetdoc="&uima_docs_ref;" targetptr="ugr.ref.xmi"/></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
-
- <section id="ugr.project_overview_v3">
- <title>Version 3 User's guide</title>
- <para>This book describes Version 3's features, capabilities, and differences with version 2.
- </para>
- </section>
-
- </section>
-
- <section id="ugr.project_overview_doc_use">
- <!-- _crossRef358 -->
- <title>How to use the Documentation</title>
- <orderedlist>
- <listitem>
- <para>Explore this chapter to get an overview of the different documents that are included with Apache UIMA.</para>
- </listitem>
- <listitem>
- <para> Read <olink targetdoc="&uima_docs_overview;" targetptr="ugr.ovv.conceptual"/> to get a broad
- view of the basic UIMA concepts and philosophy with reference to the other documents included in the
- documentation set which provide greater detail. </para>
- </listitem>
- <listitem>
- <para> For more general information on the UIMA architecture and how it has been used, refer to the IBM Systems
- Journal special issue on Unstructured Information Management, on-line at <ulink
- url="http://www.research.ibm.com/journal/sj43-3.html"/> or to the section of the UIMA project
- website on Apache website where other publications are listed. </para>
- </listitem>
- <listitem>
- <para> Set up Apache UIMA in your Eclipse environment. To do this, follow the instructions in <xref
- linkend="ugr.ovv.eclipse_setup"/>. </para>
- </listitem>
- <listitem>
- <para> Develop sample UIMA annotators, run them and explore the results. Read <olink
- targetdoc="&uima_docs_tutorial_guides;"/> <olink
- targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.aae"/> and follow it like a tutorial
- to learn how to develop your first UIMA annotator and set up and run your first UIMA analysis engines.
- <itemizedlist>
- <listitem>
- <para> As part of this you will use a few tools including
- <itemizedlist>
- <listitem>
- <para> The UIMA Component Descriptor Editor, described in more detail in <olink
- targetdoc="&uima_docs_tools;"/> <olink
- targetdoc="&uima_docs_tools;" targetptr="ugr.tools.cde"/> and </para>
- </listitem>
- <listitem>
- <para> The Document Analyzer, described in more detail in <olink
- targetdoc="&uima_docs_tools;"/> <olink
- targetdoc="&uima_docs_tools;" targetptr="ugr.tools.doc_analyzer"/>. </para>
- </listitem>
-
- </itemizedlist> </para>
-
- </listitem>
- <listitem>
- <para>While following along in <olink targetdoc="&uima_docs_tutorial_guides;"/>
- <olink targetdoc="&uima_docs_tutorial_guides;"
- targetptr="ugr.tug.aae"/>, reference documents that may help are:
- <itemizedlist>
- <listitem>
- <para> <olink targetdoc="&uima_docs_ref;"/> <olink targetdoc="&uima_docs_ref;"
- targetptr="ugr.ref.xml.component_descriptor"/> for understanding the analysis
- engine descriptors </para>
- </listitem>
- <listitem>
- <para> <olink targetdoc="&uima_docs_ref;"/>
- <olink targetdoc="&uima_docs_ref;" targetptr="ugr.ref.jcas"/> for
- understanding the JCas </para>
- </listitem>
- </itemizedlist> </para>
- </listitem>
- </itemizedlist> </para>
- </listitem>
- <listitem>
- <para> Learn how to create, run and manage a UIMA analysis engine as part of an application.
- Connect your analysis engine to the provided semantic search engine to learn how a
- complete analysis and search application may be built with Apache UIMA. <olink
- targetdoc="&uima_docs_tutorial_guides;"/> <olink
- targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.application"/> will guide you
- through this process.
- <itemizedlist>
- <listitem>
- <para> As part of this you will use the document analyzer (described in more detail in <olink
- targetdoc="&uima_docs_tools;"/> <olink
- targetdoc="&uima_docs_tools;" targetptr="ugr.tools.doc_analyzer"/> and semantic search
- GUI tools (see <olink targetdoc="&uima_docs_tutorial_guides;"/>
- <olink targetdoc="&uima_docs_tutorial_guides;"
- targetptr="ugr.tug.application.search.query_tool"/>. </para>
- </listitem>
- </itemizedlist> </para>
- </listitem>
- <listitem>
- <para> Pat yourself on the back. Congratulations! If you reached this step successfully, then you have an
- appreciation for the UIMA analysis engine architecture. You would have built a few sample annotators,
- deployed UIMA analysis engines to analyze a few documents, searched over the results using the built-in
- semantic search engine and viewed the results through a built-in viewer
- – all as part of a simple but complete application. </para>
- </listitem>
- <listitem>
- <para> Develop and run a Collection Processing Engine (CPE) to analyze and gather the results of an entire
- collection of documents. <olink targetdoc="&uima_docs_tutorial_guides;"/>
- <olink targetdoc="&uima_docs_tutorial_guides;"
- targetptr="ugr.tug.cpe"/> will guide you through this process.
- <itemizedlist>
- <listitem>
- <para> As part of this you will use the CPE Configurator tool. For details see <olink
- targetdoc="&uima_docs_tools;"/> <olink
- targetdoc="&uima_docs_tools;" targetptr="ugr.tools.cpe"/>. </para>
- </listitem>
- <listitem>
- <para> You will also learn about CPE Descriptors. The detailed format for these may be found in <olink
- targetdoc="&uima_docs_ref;"/> <olink
- targetdoc="&uima_docs_ref;" targetptr="ugr.ref.xml.cpe_descriptor"/>. </para>
- </listitem>
- </itemizedlist> </para>
- </listitem>
- <listitem>
- <para> Learn how to package up an analysis engine for easy installation into another UIMA environment.
- <olink targetdoc="&uima_docs_tools;"/>
- <olink targetdoc="&uima_docs_tools;" targetptr="ugr.tools.pear.packager"/> and <olink
- targetdoc="&uima_docs_tools;"/> <olink
- targetdoc="&uima_docs_tools;" targetptr="ugr.tools.pear.installer"/> will teach you how to
- create UIMA analysis engine archives so that you can easily share your components with a broader
- community. </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section id="ugr.project_overview_changes_from_previous">
- <title>Changes from UIMA Version 2</title>
- <para>See the separate document Version 3 User's Guide.s</para>
- </section>
-
- <section id="ugr.project_overview_migrating_from_v2_to_v3">
- <title>Migrating existing UIMA pipelines from Version 2 to Version 3</title>
- <para>The format of JCas classes changed when going from version 2 to version 3.
- If you had JCas classes for user types, these need to be regenerated using the
- version 3 JCasGen tooling or Maven plugin. Alternatively, these can be
- migrated without regenerating; the migration preserves any customization
- users may have added to the JCas classes.</para>
-
- <para>The Version 3 User's Guide has a chapter detailing the migration, including
- a description of the migration tool to aid in this process.</para>
- </section>
-
- <section id="ugr.project_overview_summary">
- <title>Apache UIMA Summary</title>
- <section id="ugr.ovv.summary.general">
- <title>General</title>
- <para>UIMA supports the development, discovery, composition and deployment of multi-modal
- analytics for the analysis of unstructured information and its integration with search
- technologies.</para>
-
- <para>Apache UIMA includes APIs and tools for creating analysis components. Examples of analysis components include
- tokenizers, summarizers, categorizers, parsers, named-entity detectors etc. Tutorial examples are
- provided with Apache UIMA; additional components are available from the community. </para>
- </section>
- <section id="ugr.ovv.summary.programming_language_support">
- <title>Programming Language Support</title>
- <para>UIMA supports the development and integration of analysis algorithms developed in different
- programming languages. </para>
-
- <para>The Apache UIMA project is both a Java framework and a matching C++
- enablement layer, which allows annotators to be written in C++ and have access to a C++ version of the CAS. The
- C++ enablement layer also enables annotators to be written in Perl, Python, and TCL, and to interoperate with
- those written in other languages. <!--Documentation for this is provided here (link to be filled in).-->
- </para>
-
- </section>
- <section id="ugr.ovv.general.summary.multi_modal_support">
- <title>Multi-Modal Support</title>
- <para>The UIMA architecture supports the development, discovery, composition and deployment of
- multi-modal analytics, including text, audio and video. <olink
- targetdoc="&uima_docs_tutorial_guides;"/> <olink
- targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.aas"/> discuss this is more
- detail.</para>
- </section>
- </section>
-
- <section id="ugr.project_overview_summary_sdk_capabilities">
- <title>Summary of Apache UIMA Capabilities</title>
- <informaltable frame="all" rowsep="1" colsep="1">
- <tgroup cols="2">
- <colspec colnum="1" colname="col1" colwidth=".75*"/>
- <colspec colnum="2" colname="col2" colwidth="*"/>
- <tbody>
- <row>
- <entry role="tableSubhead">Module</entry>
- <entry role="tableSubhead">Description</entry>
- </row>
- <row>
- <entry>UIMA Framework Core</entry>
- <entry>
- <para>A framework integrating core functions for creating, deploying, running and managing UIMA
- components, including analysis engines and Collection Processing Engines in collocated and/or
- distributed configurations. </para>
-
- <para>The framework includes an implementation of core components for transport layer adaptation,
- CAS management, workflow management based on declarative specifications, resource management,
- configuration management, logging, and other functions.</para>
- </entry>
- </row>
- <row>
- <entry>C++ and other programming language Interoperability</entry>
-
- <entry>
- <para>Includes C++ CAS and supports the creation of UIMA compliant C++ components that can be
- deployed in the UIMA run-time through a built-in JNI adapter. This includes high-speed binary
- serialization.</para>
-
- <para>Includes support for creating service-based UIMA engines. This is ideal for
- wrapping existing code written in different languages.</para>
- </entry>
- </row>
- <row>
- <entry role="tableSubhead">Framework Services and APIs</entry>
- <entry role="tableSubhead">Note that interfaces of these components are available to the developer
- but different implementations are possible in different implementations of the UIMA
- framework.</entry>
- </row>
- <row>
- <entry>CAS</entry>
- <entry>These classes provide the developer with typed access to the Common Analysis Structure (CAS),
- including type system schema, elements, subjects of analysis and indices. Multiple subjects of
- analysis (Sofas) mechanism supports the independent or simultaneous analysis of multiple views of
- the same artifacts (e.g. documents), supporting multi-lingual and multi-modal analysis.</entry>
- </row>
- <row>
- <entry>JCas</entry>
- <entry>An alternative interface to the CAS, providing Java-based UIMA Analysis components with
- native Java object access to CAS types and their attributes or features, using the
- JavaBeans conventions of getters and setters.</entry>
- </row>
-
- <row>
- <entry>Collection Processing Management (CPM)</entry>
- <entry>Core functions for running UIMA collection processing engines in collocated and/or
- distributed configurations. The CPM provides scalability across parallel processing pipelines,
- check-pointing, performance monitoring and recoverability.</entry>
- </row>
- <row>
- <entry>Resource Manager</entry>
- <entry>Provides UIMA components with run-time access to external resources handling capabilities
- such as resource naming, sharing, and caching. </entry>
- </row>
- <row>
- <entry>Configuration Manager</entry>
- <entry>Provides UIMA components with run-time access to their configuration parameter settings.
- </entry>
- </row>
- <row>
- <entry>Logger</entry>
- <entry>Provides access to a common logging facility.</entry>
- </row>
- <row>
- <entry namest="col1" nameend="col2" align="center" role="tableSubhead"> Tools and Utilities
- </entry>
- </row>
- <row>
- <entry>JCasGen</entry>
- <entry>Utility for generating a Java object model for CAS types from a UIMA XML type system
- definition.</entry>
- </row>
- <row>
- <entry>Saving and Restoring CAS contents</entry>
- <entry>APIs in the core framework support saving and restoring the contents of a CAS to streams
- in multiple formats, including XMI, binary, and compressed forms.
- These apis are collected into the CasIOUtils class.</entry>
- </row>
- <row>
- <entry>PEAR Packager for Eclipse</entry>
- <entry>Tool for building a UIMA component archive to facilitate porting, registering, installing and
- testing components.</entry>
- </row>
- <row>
- <entry>PEAR Installer</entry>
- <entry>Tool for installing and verifying a UIMA component archive in a UIMA installation.</entry>
- </row>
- <row>
- <entry>PEAR Merger</entry>
- <entry>Utility that combines multiple PEARs into one.</entry>
- </row>
- <row>
- <entry>Component Descriptor Editor</entry>
- <entry>Eclipse Plug-in for specifying and configuring component descriptors for UIMA analysis
- engines as well as other UIMA component types including Collection Readers and CAS
- Consumers.</entry>
- </row>
- <row>
- <entry>CPE Configurator</entry>
- <entry>Graphical tool for configuring Collection Processing Engines and applying them to
- collections of documents.</entry>
- </row>
- <row>
- <entry>Java Annotation Viewer</entry>
- <entry>Viewer for exploring annotations and related CAS data.</entry>
- </row>
- <row>
- <entry>CAS Visual Debugger</entry>
- <entry>GUI Java application that provides developers with detailed visual view of the contents of a
- CAS.</entry>
- </row>
- <row>
- <entry>Document Analyzer</entry>
- <entry>GUI Java application that applies analysis engines to sets of documents and shows results in a
- viewer.</entry>
- </row>
- <row>
- <entry>CAS Editor</entry>
- <entry>Eclipse plug-in that lets you edit the contents of a CAS</entry>
- </row>
- <row>
- <entry>UIMA Pipeline Eclipse Launcher</entry>
- <entry>Eclipse plug-in that lets you configure Eclipse launchers for UIMA pipelines</entry>
- </row>
- <row>
- <entry namest="col1" nameend="col2" align="center" role="tableSubhead"> Example Analysis
- Components </entry>
- </row>
- <row>
- <entry>Database Writer</entry>
- <entry>CAS Consumer that writes the content of selected CAS types into a relational database, using
- JDBC. This code is in cpe/PersonTitleDBWriterCasConsumer. </entry>
- </row>
- <row>
- <entry>Annotators</entry>
- <entry> Set of simple annotators meant for pedagogical purposes. Includes: Date/time, Room-number,
- Regular expression, Tokenizer, and Meeting-finder annotator. There are sample CAS Multipliers
- as well. </entry>
- </row>
- <row>
- <entry>Flow Controllers</entry>
- <entry> There is a sample flow-controller based on the whiteboard concept of sending the CAS to whatever
- annotator hasn't yet processed it, when that annotator's inputs are available in the CAS. </entry>
- </row>
- <row>
- <entry>XMI Collection Reader, CAS Consumer</entry>
- <entry>Reads and writes the CAS in the XMI format</entry>
- </row>
-
- <row>
- <entry>File System Collection Reader</entry>
- <entry> Simple Collection Reader for pulling documents from the file system and initializing CASes.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
-
-</chapter>
\ No newline at end of file
diff --git a/uima-docbook-references/pom.xml b/uima-docbook-references/pom.xml
deleted file mode 100644
index 3b0a8f0aa..000000000
--- a/uima-docbook-references/pom.xml
+++ /dev/null
@@ -1,50 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- 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.
--->
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
- <modelVersion>4.0.0</modelVersion>
-
- <parent>
- <groupId>org.apache.uima</groupId>
- <artifactId>uimaj-parent</artifactId>
- <version>3.5.0-SNAPSHOT</version>
- <relativePath>../uimaj-parent/pom.xml</relativePath>
- </parent>
-
- <artifactId>uima-docbook-references</artifactId>
- <packaging>pom</packaging>
- <name>Apache UIMA SDK Documentation - references</name>
- <url>${uimaWebsiteUrl}</url>
-
- <properties>
- <!-- next property is the name of the top file under src/docbook without trailing .xml -->
- <bookNameRoot>references</bookNameRoot>
- </properties>
-
- <repositories>
- <repository>
- <id>apache.snapshots</id>
- <name>Apache Snapshot Repository</name>
- <url>https://repository.apache.org/snapshots</url>
- <releases>
- <enabled>false</enabled>
- </releases>
- </repository>
- </repositories>
-</project>
\ No newline at end of file
diff --git a/uima-docbook-references/src/docbook/ref.cas.xml b/uima-docbook-references/src/docbook/ref.cas.xml
deleted file mode 100644
index 00a0c8660..000000000
--- a/uima-docbook-references/src/docbook/ref.cas.xml
+++ /dev/null
@@ -1,1228 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
-<!ENTITY imgroot "images/references/ref.cas/" >
-<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >
-%uimaents;
-]>
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-<chapter id="ugr.ref.cas">
- <title>CAS Reference</title>
-
- <para>The CAS (Common Analysis System) is the part of the Unstructured Information
- Management Architecture (UIMA) that is concerned with creating and handling the data
- that annotators manipulate.</para>
-
- <para>Java users typically use the JCas (Java interface to the CAS) when manipulating
- objects in the CAS. This chapter describes an alternative interface to the CAS which
- allows discovery and specification of types and features at run time. It is recommended
- for use when the using code cannot know ahead of time the type system it will be dealing
- with.</para>
-
- <para>Use of the CAS as described here is also recommended (or necessary) when components add
- to the definitions of types of other components. This UIMA feature allows users to add features
- to a type that was already defined elsewhere. When this feature is used in conjunction with the
- JCas, it can lead to problems with class loading. This is because different JCas representations
- of a single type are generated by the different components, and only one of them is loaded
- (unless you are using Pear descriptors). Note:
- we do not recommend that you add features to pre-existing types. A type should be defined in one
- place only, and then there is no problem with using the JCas. However, if you do use this feature,
- do not use the JCas. Similarly, if you distribute your components for inclusion in somebody else's
- UIMA application, and you're not sure that they won't add features to your types, do not use the
- JCas for the same reasons.
- </para>
-
- <section id="ugr.ref.cas.javadocs">
- <title>Javadocs</title>
-
- <para>The subdirectory <literal>docs/api</literal> contains the documentation
- details of all the classes, methods, and constants for the APIs discussed here. Please
- refer to this for details on the methods, classes and constants, specifically in the
- packages <literal>org.apache.uima.cas.*</literal>.</para>
- </section>
-
- <section id="ugr.ref.cas.overview">
- <title>CAS Overview</title>
-
- <para>There are three<footnote><para>A fourth part, the Subject of Analysis,
- is discussed in <olink targetdoc="&uima_docs_tutorial_guides;"
- /> <olink targetdoc="&uima_docs_tutorial_guides;"
- targetptr="ugr.tug.aas"/>.</para></footnote> main parts to the CAS: the type system, data creation and
- manipulation, and indexing. We will start with a brief
- description of these components.</para>
- <section id="ugr.ref.cas.type_system">
- <title>The Type System</title>
-
- <para>The type system specifies what kind of data you will be able to manipulate in your
- annotators. The type system defines two kinds of entities, types and features. Types
- are arranged in a single inheritance tree and define the kinds of entities (objects)
- you can manipulate in the CAS. Features optionally specify slots or fields within a
- type. The correspondence to Java is to equate a CAS Type to a Java Class, and the CAS
- Features to fields within the type. A critical difference is that CAS types have no
- methods; they are just data structures with named slots (features). These features can
- have as values primitive things like integers, floating point numbers, and strings,
- and they also can hold references to other instances of objects in the CAS. We call
- instances of the data structures declared by the type system <quote>feature
- structures</quote> (not to be confused with <quote>features</quote>). Feature
- structures are similar to the many variants of record structures found in computer
- science.<footnote><para> The name <quote>feature structure</quote> comes from
- terminology used in linguistics.</para></footnote></para>
-
- <para>Each CAS Type defines a supertype; it is a subtype of that supertype. This means
- that any features that the supertype defines are features of the subtype; in other
- words, it inherits its supertype's features. Only single inheritance is
- supported; a type's feature set is the union of all of the features in its
- supertype hierarchy. There is a built-in type called uima.cas.TOP; this is the top,
- root node of the inheritance tree. It defines no features.</para>
-
- <para>The values that can be stored in features are either built-in primitive values or
- references to other feature structures. The primitive values are
- <literal>boolean</literal>, <literal>byte</literal>,
- <literal>short</literal> (16 bit integers), <literal>integer</literal> (32
- bit), <literal>long</literal> (64 bit), <literal>float</literal> (32 bit),
- <literal>double</literal> (64 bit floats) and strings; the official names of these
- are <literal>uima.cas.Boolean</literal>, <literal>uima.cas.Byte</literal>,
- <literal>uima.cas.Short</literal>, <literal>uima.cas.Integer</literal>,
- <literal>uima.cas.Long</literal>, <literal>uima.cas.Float</literal>
- ,<literal> uima.cas.Double</literal> and <literal>uima.cas.String</literal>
- . The strings are Java strings, and characters are Java characters. Technically, this means
- that characters are UTF-16 code points, which is not quite the same as a Unicode character.
- This distinction should make no difference for almost all applications.
- The CAS also defines other basic built-in types for arrays of these, plus arrays of
- references to other objects, called <literal>uima.cas.IntegerArray</literal>
- ,<literal> uima.cas.FloatArray</literal>,
- <literal>uima.cas.StringArray</literal>,
- <literal>uima.cas.FSArray</literal>, etc.</para>
-
- <para>The CAS also defines a built-in type called
- <literal>uima.tcas.Annotation</literal> which inherits from
- <literal>uima.cas.AnnotationBase</literal> which in turn inherits from
- <literal>uima.cas.TOP</literal>. There are two features defined by this type,
- called <literal>begin</literal> and <literal>end</literal>, both of which are
- integer valued.</para>
-
- </section>
-
- <section id="ugr.ref.cas.creating_accessing_manipulating_data">
- <title>Creating, accessing and manipulating data</title>
- <titleabbrev>Creating/Accessing/Changing data</titleabbrev>
-
- <para>
- Creating and accessing data in the CAS requires knowledge about the types and features
- defined in the type system. The idea is similar to other data access APIs, such as the XML
- DOM or SAX APIs, or database access APIs such as JDBC. Contrary to those APIs, however, the
- CAS does not use the names of type system entities directly in the APIs. Rather, you use
- the type system to access type and feature entities by name, then use these entities in the
- data manipulation APIs. This can be compared to the Java reflection APIs: the type system
- is comparable to the Java class loader, and the type and feature objects to the
- <literal>java.lang.Class</literal> and <literal>java.lang.reflect.Field</literal> classes.
- </para>
-
- <para>
- Why does it have to be this complicated? You wouldn't normally use reflection to create a
- Java object, either. As mentioned earlier, the JCas provides the more straightforward
- method to manipulate CAS data. The CAS access methods described here need only be used for
- generic types of applications that need to be able to handle any kind of data (e.g., generic
- tooling) or when the JCas may not be used for other reasons. The generic kinds of applications
- are exactly the ones where you would use the reflection API in Java as well.
- </para>
-
- </section>
-
- <section id="ugr.ref.cas.creating_using_indexes">
- <title>Creating and using indexes</title>
-
- <para>Each view of a CAS provides a set of indexes for that view. Instances of Types (that is, Feature
- Structures) can be added to a view's indexes. These indexes provide
- a way for annotators to locate existing data in the CAS, using a specific index (or the
- method <literal>getAllIndexedFS</literal> of the object <literal>FSIndexRepository</literal>) to
- retrieve the Feature Structures that were previously created. If you want the data you
- Newly created Feature Structures are not automatically added to the indexes; you choose which
- Feature Structures to add and use one of several APIs to add them.
- </para>
-
- <para>Indexes are named and are associated with a CAS Type; they are used to index
- instances of that CAS type (including instances of that type's subtypes). If
- you are using multiple views (see <olink
- targetdoc="&uima_docs_tutorial_guides;"/> <olink
- targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.mvs"/>),
- each view contains a separate instantiation of all of the indexes.
- To access an index, you
- minimally need to know its name. A CAS view provides an index repository which you can
- query for indexes for that view. Once you have a handle to an index, you can get
- information about the feature structures in the index, the size of the index, as well
- as an iterator over the feature structures.</para>
-
- <para>There are three kinds of indexes:
- <itemizedlist spacing="compact">
- <listitem>
- <para>bag - no ordering</para>
- </listitem>
- <listitem>
- <para>set - uses a user-specfied set of keys to define equality; holds one instance of the set of equal items.</para>
- </listitem>
- <listitem>
- <para>sorted - uses a user-specified set of keys to define ordering.</para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>For set indexes, the comparator keys are augmented with an implicit additional field - the type of the
- feature structure. This means that an index over Annotations, having subtype Token, and a key of the "begin" value,
- will behave as follows:
-
- <itemizedlist>
- <listitem><para>If you make two Tokens (or two Annotations), both having a begin value of 17, and add both of them to the indexes,
- only one of them will be in the index.</para>
- </listitem>
- <listitem><para>If you make 1 Token and 1 Annotation, both having a begin value of 17, and add both of them to the indexes,
- both of them will be in the index (because the types are different).
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>Indexes are defined in the XML descriptor metadata for the application. Each CAS
- View has its own, separate instantiation of indexes based on these definitions,
- kept in the view's index repository. When you obtain an index, it is always from a
- particular CAS view's index repository.
- When you index an item, it is always added to all indexes where it
- belongs, within just the view's repository. You can specify different repositories
- (associated with different CAS views) to use; a given Feature Structure instance
- may be indexed in more than one CAS View (unless it is a subtype of AnnotationBase).</para>
-
- <para>Indexes implement the Iterable interface, so you may use the Java enhanced for loop to iterate over them.</para>
-
- <para>You can also get iterators from indexes;
- iterators allow you to enumerate the feature structures in an index. There are two kinds of iterators supported:
- the regular Java iterator API, and a specific FS iterator API
- where the usual Java iterator APIs (<literal>hasNext()</literal> and <literal>next()</literal>)
- are augmented by <literal>isValid()</literal>, <literal>moveToNext() / moveToPrevious()</literal> (which does
- not return an element) and <literal>get()</literal>. Finally, there is a <literal>moveTo(FeatureStructure)</literal>
- API, which, for sorted indexes, moves the iteration point to the left-most (among otherwise "equal") item
- in the index which compares "equal" to the given FeatureStructure, using the index's defined comparator.
- </para>
-
- <para>
- Which API style you use is up to you,
- but we do not recommend mixing the styles as the results are sometimes unexpected. If you
- just want to iterate over an index from start to finish, either style is equally appropriate.
- If you also use <literal>moveTo(FeatureStructure fs)</literal> and
- <literal>moveToPrevious()</literal>, it is better to use the special FS iterator style.
- </para>
-
- <note><para>The reason to not mix these styles is that you might be thinking that
- next() followed by moveToPrevious() would always work. This is not true, because
- next() returns the "current" element, and advances to the next position, which might be
- beyond the last element. At that point, the iterator becomes "invalid", and
- moveToNext and moveToPrevious no longer move the iterator. But you can
- call these methods on the iterator — moveToFirst(), moveToLast(), or moveTo(FS) — to reset it.</para></note>
-
- <para>Indexes are created by specifying them in the annotator's or
- aggregate's resource descriptor. An index specification includes its name,
- the CAS type being indexed, the kind (bag, set or sorted) of index it is, and an (optional) set of keys.
- The keys are used for set and sorted indexes, and specify what values are used for
- ordering, or (for sets) what values are used to determine set equality.
- When a CAS pipeline is created, all index
- specifications are combined; duplicate definitions (having the same name) are
- allowed only if their definitions are the same. </para>
-
- <para>Feature structure instances need to be explicitly added to the index repository by a
- method call. Feature structures that are not indexed will not be visible to other
- annotators, (unless they are located via being referenced by some other feature of
- another feature structure, which is indexed, or through a chain of these).</para>
-
- <para>The framework defines an unnamed bag index which indexes all types. The
- only access provided for this index is the getAllIndexedFS(type) method on the
- index repository, which returns an iterator over all indexed instances of the
- specified type (including its subtypes) for that CAS View.
- </para>
-
- <para>The framework defines one standard, built-in annotation index, called
- AnnotationIndex, which indexes the <literal>uima.tcas.Annotation</literal>
- type: all feature structures of type <literal>uima.tcas.Annotation</literal> or
- its subtypes are automatically indexed with this built-in index.</para>
-
- <para>The ordering relation used by this index is to first order by the value of the
- <quote>begin</quote> features (in ascending order) and then by the value of the
- <quote>end</quote> feature (in descending order), and then, finally, by the
- Type Priority. This ordering insures that
- longer annotations starting at the same spot come before shorter ones. For Subjects
- of Analysis other than Text, this may not be an appropriate index.</para>
-
- <para>In addition to normal iterators, there is a <literal>select</literal> API, documented
- in the Version 3 Users guide, which provides additional capabilities for accessing
- Feature Structures via the indexes.</para>
-
- </section>
- </section>
-
- <section id="ugr.ref.cas.builtin_types">
- <title>Built-in CAS Types</title>
-
- <para>The CAS has two kinds of built-in types – primitive and non-primitive. The
- primitive types are:
-
- <itemizedlist spacing="compact">
- <listitem><para>uima.cas.Boolean</para></listitem>
- <listitem><para>uima.cas.Byte</para></listitem>
- <listitem><para>uima.cas.Short</para></listitem>
- <listitem><para>uima.cas.Integer</para></listitem>
- <listitem><para>uima.cas.Long</para></listitem>
- <listitem><para>uima.cas.Float</para></listitem>
- <listitem><para>uima.cas.Double</para></listitem>
- <listitem><para>uima.cas.String</para></listitem>
- </itemizedlist></para>
-
- <para>The <literal>Byte, Short, Integer, </literal>and<literal> Long</literal> are
- all signed integer types, of length 8, 16, 32, and 64 bits. The
- <literal>Double</literal> type is 64 bit floating point. The
- <literal>String</literal> type can be subtyped to create sets of allowed values; see
- <olink targetdoc="&uima_docs_ref;"
- targetptr="ugr.ref.xml.component_descriptor.type_system.string_subtypes"/>.
- These types can be used to specify the range of a String-valued feature. They act like
- Strings, but have additional checking to insure the setting of values into them
- conforms to one of the allowed values, or to null (which is the value if it is not set).
- Note that the other primitive types cannot be used
- as a supertype for another type definition; only
- <literal>uima.cas.String</literal> can be sub-typed.</para>
-
- <para>The non-primitive types exist in a type hierarchy; the top of the hierarchy is the
- type <literal>uima.cas.TOP</literal>. All other non-primitive types inherit from
- some supertype.</para>
-
- <para>There are 9 built-in array types. These arrays have a size specified when they are
- created; the size is fixed at creation time. They are named:
-
- <itemizedlist spacing="compact">
- <listitem><para>uima.cas.BooleanArray</para></listitem>
- <listitem><para>uima.cas.ByteArray</para></listitem>
- <listitem><para>uima.cas.ShortArray</para></listitem>
- <listitem><para>uima.cas.IntegerArray</para></listitem>
- <listitem><para>uima.cas.LongArray</para></listitem>
- <listitem><para>uima.cas.FloatArray</para></listitem>
- <listitem><para>uima.cas.DoubleArray</para></listitem>
- <listitem><para>uima.cas.StringArray</para></listitem>
- <listitem><para>uima.cas.FSArray</para></listitem>
- </itemizedlist></para>
-
- <para>The <literal>uima.cas.FSArray</literal> type is an array whose elements are
- arbitrary other feature structures (instances of non-primitive types).</para>
-
- <para>The JCas cover classes for the array types support the Iterable API, so you may
- write extended for loops over instances of these. For example:
- <programlisting>FSArray<MyType> myArray = ...
-for (MyType fs : myArray) {
- some_method(fs);
-}</programlisting>
- </para>
-
- <para>There are 3 built-in types associated with the artifact being analyzed:
-
- <itemizedlist spacing="compact">
- <listitem><para>uima.cas.AnnotationBase</para></listitem>
- <listitem><para>uima.tcas.Annotation</para></listitem>
- <listitem><para>uima.tcas.DocumentAnnotation</para></listitem>
- </itemizedlist></para>
-
- <para>The <literal>AnnotationBase</literal> type defines one system-used feature
- which specifies for an annotation the subject of analysis (Sofa) to which it refers. The
- Annotation type extends from this and defines 2 features, taking
- <literal>uima.cas.Integer</literal> values, called <literal>begin</literal>
- and <literal>end</literal>. The <literal>begin</literal> feature typically
- identifies the start of a span of text the annotation covers; the
- <literal>end</literal> feature identifies the end. The values refer to character
- offsets; the starting index is 0. An annotation of the word <quote>CAS</quote> in a text
- <quote>CAS Reference</quote> would have a start index of 0, and an end index of 3; the
- difference between end and start is the length of the span the annotation refers
- to.</para>
-
- <para>Annotations are always with respect to some Sofa (Subject of Analysis – see
- <olink targetdoc="&uima_docs_tutorial_guides;"/>
- <olink targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.aas"/>
- .</para>
- <note><para>Artifacts which are not text strings may have a different interpretation of
- the meaning of begin and end, or may define their own kind of annotation, extending from
- <literal>AnnotationBase</literal>. </para></note>
-
- <para id="ugr.ref.cas.document_annotation">The <literal>DocumentAnnotation</literal> type has one special instance. It is
- a subtype of the Annotation type, and the built-in definition defines one feature,
- <literal>language</literal>, which is a string indicating the language of the
- document in the CAS. The value of this language feature is used by the system to control
- flow among annotators when the <quote>CapabilityLanguageFlow</quote> mode is used,
- allowing the flow to skip over annotators that don't process particular
- languages. Users may extend this type by adding additional features to it, using the XML
- Descriptor element for defining a type.</para>
-
- <note><para>
- We do <emphasis>not</emphasis> recommend extending the <literal>DocumentAnnotation</literal>
- type. If you do, you must <emphasis>not</emphasis> use the JCas, for the reasons stated
- earlier.
- </para></note>
-
- <para>Each CAS view has a different associated instance of the
- <literal>DocumentAnnotation</literal> type. On the CAS, use
- <literal>getDocumentationAnnotation()</literal> to access the
- <literal>DocumentAnnotation</literal>.</para>
-
- <para>There are also built-in types supporting linked lists, similar to the ones available in
- Java and other programming languages. Their use is
- constrained by the usual properties of linked lists: not very space efficient, no (efficient)
- random access, but an easy choice if you don't know how long your list will be ahead of time. The
- implementation is type specific; there are different list building objects for each of
- the primitive types, plus one for general feature structures. Here are the type names:
- <itemizedlist spacing="compact">
- <listitem><para>uima.cas.FloatList</para></listitem>
- <listitem><para>uima.cas.IntegerList</para></listitem>
- <listitem><para>uima.cas.StringList</para></listitem>
- <listitem><para>uima.cas.FSList</para>
- <para></para></listitem>
- <listitem><para>uima.cas.EmptyFloatList</para></listitem>
- <listitem><para>uima.cas.EmptyIntegerList</para></listitem>
- <listitem><para>uima.cas.EmptyStringList</para></listitem>
- <listitem><para>uima.cas.EmptyFSList</para>
- <para></para></listitem>
- <listitem><para>uima.cas.NonEmptyFloatList</para></listitem>
- <listitem><para>uima.cas.NonEmptyIntegerList</para></listitem>
- <listitem><para>uima.cas.NonEmptyStringList</para></listitem>
- <listitem><para>uima.cas.NonEmptyFSList</para></listitem>
-
- </itemizedlist></para>
-
- <para>For the primitive types <literal>Float</literal>,
- <literal>Integer</literal>, <literal>String</literal> and
- <literal>FeatureStructure</literal>, there is a base type, for instance,
- <literal>uima.cas.FloatList</literal>. For each of these, there are two subtypes,
- corresponding to a non-empty element, and a marker that serves to indicate the end of the
- list, or an empty list. The non-empty types define two features –
- <literal>head</literal> and <literal>tail</literal>. The head feature holds the
- particular value for that part of the list. The tail refers to the next list object
- (either a non-empty one or the empty version to indicate the end of the list).</para>
-
- <para>For JCas users, the new operator for the NonEmptyXyzList classes includes a 3 argument version
- where you may specify the head and tail values as part of the constructor. The JCas
- cover classes for these implement
- a <code>push(item)</code> method which creates a new non-empty node, sets the <code>head</code> value
- to <code>item</code>, and the tail to the node it is called on, and returns the new node.
- These classes also implement Iterable, so you can use the enhanced Java <code>for</code> operator.
- The iterator stops when it gets to the end of the list, determined by either the tail being null or
- the element being one of the EmptyXXXList elements.
- Here's a StringList example:
- <programlisting>StringList sl = jcas.emptyStringList();
-sl = sl.push("2");
-sl = sl.push("1");
-
-for (String s : sl) {
- someMethod(s); // some sample use
-}</programlisting>
-
- </para>
-
- <para>There are no other built-in types. Users are free to define their own type systems,
- building upon these types.</para>
-
- </section>
-
- <section id="ugr.ref.cas.accessing_the_type_system">
- <title>Accessing the type system</title>
-
- <para>
- During annotator processing, or outside an annotator, access the type system by calling
- <literal>CAS.getTypeSystem()</literal>.
- </para>
-
- <para>However, CAS annotators implement an additional method,
- <literal>typeSystemInit()</literal>, which is called by the UIMA framework before the
- annotator's process method. This method, implemented by the annotator writer,
- is passed a reference to the CAS's type system metadata. The method typically uses
- the type system APIs to obtain type and feature objects corresponding to all the types
- and features the annotator will be using in its process method. This initialization
- step should not be done during an annotator's initialize method since the type
- system can change after the initialize method is called; it should not be done during the
- process method, since this is presumably work that is identical for each incoming
- document, and so should be performed only when the type system changes (which will be a
- rare event). The UIMA framework guarantees it will call the <literal>typeSystemInit
- </literal>method of an annotator whenever the type system changes, before calling the
- annotator's <literal>process()</literal> method.</para>
-
- <para>The initialization done by <literal>typeSystemInit()</literal> is done by the
- UIMA framework when you use the JCas APIs; you only need to provide a
- <literal>typeSystemInit()</literal> method, as described here, when you are not using
- the JCas approach.</para>
-
- <section id="ugr.ref.cas.type_system.printer_example">
- <title>TypeSystemPrinter example</title>
-
- <para>Here is a code fragment that, given a CAS Type System, will print a list of all
- types.</para>
-
-
- <programlisting>// Get all type names from the type system
-// and print them to stdout.
-private void listTypes1(TypeSystem ts) {
- for (Type t : ts) {
- // print its name.
- System.out.println(t.getName());
- }
-}</programlisting>
-
- <para>This method is passed the type system as a parameter. From the type system, we can
- get an iterator
- over all the types. If you run this against a CAS created with no additional
- user-defined types, we should see something like this on the console:</para>
-
- <programlisting>Types in the type system:
-uima.cas.Boolean
-uima.cas.Byte
-uima.cas.Short
-uima.cas.Integer
-uima.cas.Long
-uima.cas.ArrayBase
-...
- </programlisting>
-
- <para>If the type system had user-defined types these would show up too. Note that some
- of these types are not directly creatable – they are types used by the framework
- in the type hierarchy (e.g. uima.cas.ArrayBase).</para>
-
- <para>CAS type names include a name-space prefix. The components of a type name are
- separated by the dot (.). A type name component must start with a Unicode letter,
- followed by an arbitrary sequence of letters, digits and the underscore (_). By
- convention, the last component of a type name starts with an uppercase letter, the
- rest start with a lowercase letter.</para>
-
- <para>Listing the type names is mildly useful, but it would be even better if we could see
- the inheritance relation between the types. The following code prints the
- inheritance tree in indented format.</para>
-
-
- <programlisting>private static final int INDENT = 2;
-private void listTypes2(TypeSystem ts) {
- // Get the root of the inheritance tree.
- Type top = ts.getTopType();
- // Recursively print the tree.
- printInheritanceTree(ts, top, 0);
-}
-
-private void printInheritanceTree(TypeSystem ts, Type type, int level) {
- indent(level); // Print indentation.
- System.out.println(type.getName());
- // Get a vector of the immediate subtypes.
- Vector subTypes =
- ts.getDirectlySubsumedTypes(type);
- ++level; // Increase the indentation level.
- for (int i = 0; i < subTypes.size(); i++) {
- // Print the subtypes.
- printInheritanceTree(ts, (Type) subTypes.get(i), level);
- }
-}
-
-// A simple, inefficient indenter
-private void indent(int level) {
- int spaces = level * INDENT;
- for (int i = 0; i < spaces; i++) {
- System.out.print(" ");
- }
-}</programlisting>
-
- <para> This example shows that you can traverse the type hierarchy by starting at the top
- with TypeSystem.getTopType and by retrieving subtypes with
- <literal>TypeSystem.getDirectlySubsumedTypes()</literal>.</para>
-
- <para>The Javadocs also have APIs that allow you to access the features, as well as what
- the allowed value type is for that feature. Here is sample code which prints out all the
- features of all the types, together with the allowed value types (the feature
- <quote>range</quote>). Each feature has a <quote>domain</quote> which is the type
- where it is defined, as well as a <quote>range</quote>.
-
-
- <programlisting>private void listFeatures2(TypeSystem ts) {
- Iterator featureIterator = ts.getFeatures();
- Feature f;
- System.out.println("Features in the type system:");
- while (featureIterator.hasNext()) {
- f = (Feature) featureIterator.next();
- System.out.println(
- f.getShortName() + ": " +
- f.getDomain() + " -> " + f.getRange());
- }
- System.out.println();
-}</programlisting></para>
-
- <para>We can ask a feature object for its domain (the type it is defined on) and its range
- (the type of the value of the feature). The terminology derives from the fact that
- features can be viewed as functions on subspaces of the object space.</para>
-
- </section>
-
- <section id="ugr.ref.cas.cas_apis_create_modify_feature_structures">
- <title>Using the CAS APIs to create and modify feature structures</title>
- <titleabbrev>Using CAS APIs: Feature Structures</titleabbrev>
-
- <para>Assume a type system declaration that defines two types: Entity and Person.
- Entity has no features defined within it but inherits from uima.tcas.Annotation
- – so it has the begin and end features. Person is, in turn, a subtype of Entity,
- and adds firstName and lastName features. CAS type systems are declaratively
- specified using XML; the format of this XML is described in <olink
- targetdoc="&uima_docs_ref;"
- targetptr="ugr.ref.xml.component_descriptor.type_system"/>.
-
-
- <programlisting><![CDATA[<!-- Type System Definition -->
-<typeSystemDescription>
- <types>
- <typeDescription>
- <name>com.xyz.proj.Entity</name>
- <description />
- <supertypeName>uima.tcas.Annotation</supertypeName>
- </typeDescription>
- <typeDescription>
- <name>Person</name>
- <description />
- <supertypeName>com.xyz.proj.Entity </supertypeName>
- <features>
- <featureDescription>
- <name>firstName</name>
- <description />
- <rangeTypeName>uima.cas.String</rangeTypeName>
- </featureDescription>
- <featureDescription>
- <name>lastName</name>
- <description />
- <rangeTypeName>uima.cas.String</rangeTypeName>
- </featureDescription>
- </features>
- </typeDescription>
- </types>
-</typeSystemDescription>]]></programlisting></para>
-
- <para>
- To be able to access types and features, we need to know their names. The CAS interface defines
- constants that hold the names of built-in feature names, such as, e.g.,
- <literal>CAS.TYPE_NAME_INTEGER</literal>. It is good programming practice to create such
- constants for the types and features you define, for your own use as well as for others who will
- be using your annotators.
- </para>
-
-
- <programlisting>/** Entity type name constant. */
-public static final String ENTITY_TYPE_NAME = "com.xyz.proj.Entity";
-
-/** Person type name constant. */
-public static final String PERSON_TYPE_NAME = "com. xyz.proj.Person";
-
-/** First name feature name constant. */
-public static final String FIRST_NAME_FEAT_NAME = "firstName";
-
-/** Last name feature name constant. */
-public static final String LAST_NAME_FEAT_NAME = "lastName";</programlisting>
-
- <para>Next we define type and feature member variables; these will hold the values of the
- type and feature objects needed by the CAS APIs, to be assigned during
- <literal>typeSystemInit()</literal>.</para>
-
-
- <programlisting>// Type system object variables
-private Type entityType;
-private Type personType;
-private Feature firstNameFeature;
-private Feature lastNameFeature;
-private Type stringType;</programlisting>
-
- <para>The type system does not throw an exception if we ask for something that is
- not known, it simply returns null; therefore the code checks for this and throws a proper
- exception. We require all these types and features to be defined for the annotator to
- work. One might imagine situations where certain computations are predicated on some type
- or feature being defined in the type system, but that is not the case here.</para>
-
-
- <programlisting>// Get a type object corresponding to a name.
-// If it doesn't exist, throw an exception.
-private Type initType(String typeName)
- throws AnnotatorInitializationException {
- Type type = ts.getType(typeName);
- if (type == null) {
- throw new AnnotatorInitializationException(
- AnnotatorInitializationException.TYPE_NOT_FOUND,
- new Object[] { this.getClass().getName(), typeName });
- }
- return type;
-}
-
-// We add similar code for retrieving feature objects.
-// Get a feature object from a name and a type object.
-// If it doesn't exist, throw an exception.
-private Feature initFeature(String featName, Type type)
- throws AnnotatorInitializationException {
- Feature feat = type.getFeatureByBaseName(featName);
- if (feat == null) {
- throw new AnnotatorInitializationException(
- AnnotatorInitializationException.FEATURE_NOT_FOUND,
- new Object[] { this.getClass().getName(), featName });
- }
- return feat;
-}</programlisting>
-
- <para>Using these two functions, code for initializing the type system described
- above would be:
-
-
- <programlisting>public void typeSystemInit(TypeSystem aTypeSystem)
- throws AnalysisEngineProcessException {
- this.typeSystem = aTypeSystem;
- // Set type system member variables.
- this.entityType = initType(ENTITY_TYPE_NAME);
- this.personType = initType(PERSON_TYPE_NAME);
- this.firstNameFeature =
- initFeature(FIRST_NAME_FEAT_NAME, personType);
- this.lastNameFeature =
- initFeature(LAST_NAME_FEAT_NAME, personType);
- this.stringType = initType(CAS.TYPE_NAME_STRING);
-}</programlisting></para>
-
- <para>Note that we initialize the string type by using a type name constant from the
- CAS.</para>
-
- </section>
- </section>
-
- <section id="ugr.ref.cas.creating_feature_structures">
- <title>Creating feature structures</title>
-
- <para>To create feature structures in JCas, we use the Java <quote>new</quote>
- operator. In the CAS, we use one of several different API methods on the CAS object,
- depending on which of the 10 basic kinds of feature structures we are creating (a plain
- feature structure, or an instance of the built-in primitive type arrays or FSArray).
- There are is also a method to create an instance of a
- <literal>uima.tcas.Annotation</literal>, setting the begin and end
- values.</para>
-
- <para>Once a feature structure is created, it needs to be added to the CAS indexes (unless
- it will be accessed via some reference from another accessible feature structure). The
- CAS provides this API: Assuming aCAS holds a reference to a CAS, and token holds a
- reference to a newly created feature structure, here's the code to add that
- feature structure to all the relevant CAS indexes:</para>
-
-
- <programlisting> // Add the token to the index repository.
- aCAS.addFsToIndexes(token);</programlisting>
-
- <para>There is also a corresponding <literal>removeFsFromIndexes(token)</literal>
- method on CAS objects.</para>
-
- <para>As of version 2.4.1, there are two methods you can use on an index repository
- to efficiently bulk-remove all
- instances of particular types of feature structures from a particular view. One of these,
- <code>aCas.getIndexRepository().removeAllIncludingSubtypes(aType)</code> removes all instances of a particular
- type, including instances which are subtypes of the specified type. The other,
- <code>aCas.getIndexRepository().removeAllExcludingSubtypes(aType)</code> remove all instances of a particular
- type, only. In both cases, the removal is done from the particular view of the CAS referenced
- by aCas.</para>
-
- <section id="ugr.ref.cas.updating_indexed_feature_structures">
- <title>Updating indexed feature structures</title>
- <para>Version 2.7.0 added protection for indexes when feature structure key
- value features are updated. By default this protection is automatic, but
- at some performance cost. Users may optimize this further.</para>
-
- <para>Protection is needed because some of the indexes (the Sorted and Set types) use comparators defined
- to use values of the particular features; if these values
- need to be changed after the feature structure is added to the indexes,
- the correct way to do this is to:
- <orderedlist spacing="compact">
- <listitem><para>completely remove the item from all indexes where it is indexed, in all views
- where it is indexed,</para>
- </listitem>
- <listitem><para>update the value of the features being used as keys,</para></listitem>
- <listitem><para>add the item back to the indexes, in all views.</para></listitem>
- </orderedlist></para>
-
- <note><para>It’s OK to change feature values which are not used in determining
- sort ordering (or set membership), without removing and re-adding back to the index.
- </para></note>
-
- <!-- <para>To completely remove an item from the indexes may entail removing it multiple times, if it was
- added multiple times and (as of version 2.7.0) the JVM global property
- <code>uima.allow_duplicate_add_to_indexes</code> is true.</para> -->
-
- <para>The automatic protection checks for updates of
- features being used as keys, and if it finds an update like this for a feature structure that
- is in the indexes, it removes the feature structure from the indexes, does the update,
- and adds it back. It will do this for every feature update. This is obviously not
- efficient when multiple features are being updated; in that case it would better to
- remove the feature structure, do all the updates to all the features needing updates, and then
- do a single add-back operation.</para>
-
- <para>This is supported in user’s code by using the new method <code>protectIndexes</code>
- available in both the CAS and JCas interface.
-
- Here's two ways
- of using this, one with a try / finally and the other with a Runnable:
- <programlisting>// an approach using try / finally
-AutoCloseable ac = my_cas.protectIndexes(); // my_cas is a CAS or a JCas
-try {
- ... arbitrary user code which updates features
- which may be "keys" in one or more indexes
-} finally {
- ac.close();
-}
-
-// This can more compactly be written using the auto-close feature of try:
-
-try (AutoCloseable ac = my_cas.protectIndexes()) {
- ... arbitrary user code which updates features
- which may be "keys" in one or more indexes
-}
-
-// an approach using a Runnable, written in Java 8 lambda syntax
-my_cas.protectIndexes(() -> {
- ... arbitrary user code updating "key" features,
- but no checked exceptions are permitted
- });</programlisting></para>
-
- <para>The <code>protectIndexes</code> implementation only removes feature structures that
- have features being updated which are used as keys in some index(es). At the end of the scope
- of the protectIndexes, it adds all of these back. It also skips removing feature structures
- from bag indexes, since these have no keys.</para>
-
- <para>Within a <code>protectIndexes</code> block, do not do any operations which depend on the
- indexes being valid, such as creating and using an iterator. This is because the removed FSs
- are only added back at the end of the protectIndexes block.</para>
-
- <para>The JVM property <code>-Duima.report_fs_update_corrupts_index</code> will generate a log entry
- everytime the frameworks finds (and automatically surrounds with a remove - add-back) an update to
- a feature which could corrupt the index. The log entries can be identified by scanning for messages
- starting with <code>While FS was in the index, the feature</code> - the message goes on to identify
- the feature in question. Users can use these reports to find the places in their code where
- they can either change the design to avoid updating these values after the item is indexed, or
- surround the updates with their own <code>protectIndexes</code> blocks.</para>
-
- <para>Initially, the out-of-the-box defaults
- for the UIMA framework will run with an automatic (but somewhat inefficient) protection. To improve upon this,
- users would:
- <itemizedlist>
- <listitem><para>Turn on reporting using a global JVM flag <code>
- -Duima.report_fs_update_corrupts_index</code>.
- This will cause a message to be logged each time the automatic protection is being invoked,
- and allows the user to find the spots to improve.</para>
- </listitem>
- <listitem><para>Improve each spot, perhaps by surrounding the update code with a protectIndexes
- block, or by rearranging code to reduce updating feature values used as index keys.</para>
- </listitem>
- <listitem><para>Once the code is no longer generating any reports, you can turn off the
- automatic protection for production runs using the JVM global property
- <code>-Duima.disable_auto_protect_indexes</code>, and rely on the protectIndexes blocks.
- If protection is disabled, then the corruption detection is skipped, making the production
- runs perhaps a bit faster, although this is not significant in most cases.</para></listitem>
- <listitem><para>For automated build systems, there’s a JVM parameter,
- <code>-Duima.exception_when_fs_update_corrupts_index</code>, which will throw an
- exception if any automatic recovery situation is encountered. You can use this
- in build/test scenarios to insure
- (after adding all needed protectIndexes blocks) that the code remains safe for
- turning off the checking in production runs.</para></listitem>
-
- </itemizedlist>
- </para>
-
- </section>
- </section>
-
- <section id="ugr.ref.cas.accessing_modifying_features_of_feature_structures">
- <title>Accessing or modifying features of feature structures</title>
- <titleabbrev>Accessing or modifying Features</titleabbrev>
-
- <para>Values of individual features for a feature structure can be set or referenced,
- using a set of methods that depend on the type of value that feature is declared to have.
- There are methods on FeatureStructure for this: getBooleanValue, getByteValue,
- getShortValue, getIntValue, getLongValue, getFloatValue, getDoubleValue,
- getStringValue, and getFeatureValue (which means to get a value which in turn is a
- reference to a feature structure). There are corresponding <quote>setter</quote>
- methods, as well. These methods on the feature structure object take as arguments the
- feature object retrieved earlier in the typeSystemInit method.</para>
-
- <para>Using the previous example, with the type system initialized with type personType
- and feature lastNameFeature, here's a sample code fragment that gets and sets
- that feature:</para>
-
-
- <programlisting>// Assume aPerson is a variable holding an object of type Person
-// get the lastNameFeature value from the feature structure
-String lastName = aPerson.getStringValue(lastNameFeature);
-// set the lastNameFeature value
-aPerson.setStringValue(lastNameFeature, newStringValueForLastName);</programlisting>
-
- <para>The getters and setters for each of the primitive types are defined in the Javadocs
- as methods of the FeatureStructure interface.</para>
-
- </section>
-
- <section id="ugr.ref.cas.indexes_and_iterators">
- <title>Indexes and Iterators</title>
-
- <para>Each CAS can have many indexes associated with it; each CAS View contains
- a complete set of instantiations of the indexes. Each index is represented by an
- instance of the type org.apache.uima.cas.FSIndex. You use the object
- org.apache.uima.cas.FSIndexRepository, accessible via a method on a CAS object, to
- retrieve instances of indexes. There are methods that let you select the index
- by name, by type, or by both name and type. Since each index is already associated with a type,
- passing both a name and a type is valid only if the type passed in is the same
- type or a subtype of the one declared in the index specification for the named index. If you
- pass in a subtype, the returned FSIndex object refers to an index that will return only
- items belonging to that subtype (or subtypes of that subtype).</para>
-
- <para>The returned FSIndex objects are used, in turn, to create iterators.
- There is also a method on the Index Repository, <literal>getAllIndexedFS</literal>,
- which will return an iterator over all indexed Feature Structures (for that CAS View),
- in no particular order. The iterators
- created can be used like common Java iterators, to sequentially retrieve items
- indexed. If the index represents a sorted index, the items are returned in a sorted
- order, where the sort order is specified in the XML index definition. This XML is part of
- the Component Descriptor, see <olink targetdoc="&uima_docs_ref;"
- targetptr="ugr.ref.xml.component_descriptor.aes.index"/>.</para>
-
- <para>In UIMA V3, Feature structures may be added to or removed from indexes while iterating
- over them. If this happens, any iterators already created will continue to operate over the
- before-modification version of the index, unless or until the iterator is re-synchronized with the current
- value of the index via one of the following specific 3 iterator API calls:
- moveToFirst, moveToLast, or moveTo(FeatureStructure).
- ConcurrentModificationException is no longer thrown in UIMA v3.
- </para>
-
- <para>Feature structures being iterated over may have features which are used as the "keys" of an index, updated.
- If this is done, UIMA will protect the indexes (to prevent index corruption) by automatically removing the
- Feature Structure from the indexes,
- updating the field, and adding the FS back to the index (possibly in a new position).
- This automatic remove / add-back operation no longer makes the iterator throw a ConcurrentModificationException
- (as it did in UIMA Version 2) if the iterator is incremented or decremented;
- existing iterators will continue to operate as if no index modification occurred.
- </para>
-
- <!-- <para>As of version 2.7.0, a new method on FSIndex, <code>withSnapshotIterators(),</code>
- allows creating a light-weight FSIndex based on the original FSIndex
- that supports doing arbitrary index operations while iterating, and will not throw
- <code>ConcurrentModificationException</code>. Iterators obtained from this instance use a
- <emphasis>snapshot</emphasis> technique - they create a snapshot of the original index when the
- iterator is created, and then use that snapshot while operating, so the iteration is unaffected by any
- modifications to the actual index.</para> -->
-
- <section id="ugr.ref.cas.index.built_in_indexes">
- <title>Built-in Indexes</title>
-
- <para>An unnamed built-in bag index exists which holds all feature structures which are indexed.
- The only access to this index is the method getAllIndexedFS(Type) which returns an iterator
- over all indexed Feature Structures.</para>
-
- <para>The CAS also contains a built-in index for the type <literal>uima.tcas.Annotation</literal>, which sorts
- annotations in the order in which they appear in the document. Annotations are sorted first by increasing
- <literal>begin</literal> position. Ties are then broken by <emphasis>decreasing</emphasis>
- <literal>end</literal> position (so that longer annotations come first). Annotations that match in both
- their <literal>begin</literal> and <literal>end</literal> features are sorted using the Type Priority,
- if any are defined
- (see <olink targetdoc="&uima_docs_ref;"
- targetptr="ugr.ref.xml.component_descriptor.aes.type_priority"/> )</para>
- </section>
-
-
- <section id="ugr.ref.cas.index.adding_to_indexes">
- <title>Adding Feature Structures to the Indexes</title>
-
- <para>Feature Structures are added to the indexes by various APIs. These add the Feature Structure to
- <emphasis>all</emphasis> indexes that are defined for the type of that FeatureStructure (or any of its
- supertypes), in a particular view.
- Note that you should not add a Feature Structure to the indexes until you have set values for all
- of the features that may be used as sort keys in an index.</para>
-
- <para>There are multiple APIs for adding FSs to the index.
- <itemizedlist>
- <listitem><para>(preferred) myFeatureStructure.addToIndexes(). This adds the feature structure instance to the
- view in which it was originally created.</para>
- </listitem>
- <listitem><para>(preferred) myFeatureStructure.addToIndexes(JCas or CAS). This adds the feature structure instance to the
- view represented by the argument.</para>
- </listitem>
- <listitem><para>(older form) casView.addFsToIndexes(myFeatureStructure) or jcasView.addFsToIndexes(myFeatureStructure).
- This adds the feature structure instance to the
- view represented by the cas (or jcas).</para>
- </listitem>
- <listitem><para>(older form) fsIndexRepositoryView.addFsToIndexes(myFeatureStructure).
- This adds the feature structure instance to the
- view represented by the fsIndexRepository instance.</para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id="ugr.ref.cas.index.iterators">
- <title>Iterators over UIMA Indexes</title>
-
-
- <para>Iterators are objects of class <literal>org.apache.uima.cas.FSIterator.</literal> This class
- extends <literal>java.util.Iterator</literal> and implements the normal Java iterator methods, plus
- additional ones that allow moving both forwards and backwards.</para>
-
- <para>UIMA Indexes implement iterable, so you can use the index directly in a Java extended for loop.</para>
-
- </section>
-
- <section id="ugr.ref.cas.index.annotation_index">
- <title>Special iterators for Annotation types</title>
-
- <para>Note: we recommend using the UIMA V3 select framework, instead of the following.
- It implements all of the following capabilities, and more, in a uniform manner.</para>
-
- <para>The built-in index over the <literal>uima.tcas.Annotation</literal> type
- named <quote><literal>AnnotationIndex</literal></quote> has additional
- capabilities. To use them, you first get a reference to this built-in index using
- either the <literal>getAnnotationIndex</literal> method on a CAS View object, or
- by asking the <literal>FSIndexRepository</literal> object for an index having the
- particular name <quote>AnnotationIndex</quote>, for example:
-
- <programlisting>AnnotationIndex idx = aCAS.getAnnotationIndex();
-// or you can iterate over a specific subtype of Annotation:
-AnnotationIndex idx = aCAS.getAnnotationIndex(aType); </programlisting></para>
-
- <para>This object can be used to produce several additional kinds of iterators. It can
- produce unambiguous iterators; these skip over elements until it finds one where the
- start position of the next annotation is equal to or greater than the end position of
- the previously returned annotation.</para>
-
- <para>It can also produce several kinds of subiterators; these are iterators whose
- annotations fall within the span of another annotation. This kind of iterator can
- also have the unambiguous property, if desired. It also can be
- <quote>strict</quote> or not; strict means that the returned annotation lies
- completely within the span of the controlling annotation. Non-strict only implies
- that the beginning of the returned annotation falls within the span of the
- controlling annotation.</para>
-
- <para>There is also a method which produces an <literal>AnnotationTree</literal>
- object, which contains nodes representing the results of doing a strict,
- unambiguous subiterator over the span of some controlling annotation. For more
- details, please refer to the Javadocs for the
- <literal>org.apache.uima.cas.text</literal> package.</para>
-
- </section>
-
- <section id="ugr.ref.cas.index.constraints_and_filtered_iterators">
- <title>Constraints and Filtered iterators</title>
-
- <para>Note: for new code, consider using the select framework plus Streams, instead of
- the following.</para>
-
- <para>There is a set of API calls that build constraint objects. These objects can be
- used directly to test if a particular feature structure matches (satisfies) the
- constraint, or they can be passed to the createFilteredIterator method to create an
- iterator that skips over instances which fail to satisfy the constraint.</para>
-
- <para>It is possible to specify a feature value located by following a chain of
- references starting from the feature structure being tested. Here's a
- scenario to explore this concept. Let's suppose you have the following type
- system (namespaces are omitted for clarity):
-
- <blockquote>
- <para><emphasis role="bold">Token</emphasis>, having a feature PartOfSpeech
- which holds a reference to another type (POS)</para>
-
- <para><emphasis role="bold">POS</emphasis> (a type with many subtypes, each
- representing a different part of speech)</para>
-
- <para><emphasis role="bold">Noun</emphasis> (a subtype of POS)</para>
-
- <para><emphasis role="bold">ProperName</emphasis> (a subtype of Noun),
- having a feature Class which holds an integer value encoding some information
- about the proper noun.</para></blockquote></para>
-
- <para>If you want to filter Token instances, such that only those tokens get through
- which are proper names of class 3 (for example), you would need a test that started with
- a Token instance, followed its PartOfSpeech reference to another instance (the
- ProperName instance) and then tested the Class feature of that instance for a value
- equal to 3.</para>
-
- <para>To support this, the filtering approach has components that specify tests, and
- components that specify <quote>paths</quote>. The tests that can be done include
- testing references to type instances to see if they are instances of some type or its
- subtypes; this is done with a FSTypeConstraint constraint. Other tests check for
- equality or, for numeric values, ranges.</para>
-
- <para>Each test may be combined with a path – to get to the value to test. Tests that
- start from a feature structure instance can be combined with and and or connectors.
- The Javadocs for these are in the package org.apache.uima.cas in the classes that end
- in Constraint, plus the classes ConstraintFactory, FeaturePath and CAS.
- Here's an example; assume the variable cas holds a reference to a CAS instance.
-
-
- <programlisting>// Start by getting the constraint factory from the CAS.
-ConstraintFactory cf = cas.getConstraintFactory();
-
-// To specify a path to an item to test, you start by
-// creating an empty path.
-FeaturePath path = cas.createFeaturePath();
-
-// Add POS feature to path, creating one-element path.
-path.addFeature(posFeat);
-
-// You can extend the chain arbitrarily by adding additional
-// features.
-
-// Create a new type constraint.
-
-// Type constraints will check that structures
-// they match against have a type at least as specific
-// as the type specified in the constraint.
-FSTypeConstraint nounConstraint = cf.createTypeConstraint();
-
-// Set the type (by default it is TOP).
-// This succeeds if the type being tested by this constraint
-// is nounType or a subtype of nounType.
-nounConstraint.add(nounType);
-
-// Embed the noun constraint under the pos path.
-// This means, associate the test with the path, so it tests the
-// proper value.
-
-// The result is a test which will
-// match a feature structure that has a posFeat defined
-// which has a value which is an instance of a nounType or
-// one of its subtypes.
-FSMatchConstraint embeddedNoun = cf.embedConstraint(path, nounConstraint);
-
-// Create a type constraint for token (or a subtype of it)
-FSTypeConstraint tokenConstraint = cf.createTypeConstraint();
-
-// Set the type.
-tokenConstraint.add(tokenType);
-
-// Create the final constraint by conjoining the two constraints.
-FSMatchConstraint nounTokenCons = cf.and(nounConstraint, tokenConstraint);
-
-// Create a filtered iterator from some annotation iterator.
-FSIterator it = cas.createFilteredIterator(annotIt, nounTokenCons);</programlisting>
- </para></section></section>
-
- <section id="ugr.ref.cas.guide_to_javadocs">
- <title>The CAS API's – a guide to the Javadocs</title>
- <titleabbrev>CAS API's Javadocs</titleabbrev>
-
- <para>The CAS APIs are organized into 3 Java packages: cas, cas.impl, and cas.text. Most
- of the APIs described here are in the cas package. The cas.impl package contains classes
- used in serializing and deserializing (reading and writing external representations) the
- CAS in various formats, for
- transporting the CAS among local and remote annotators, or for storing the CAS in
- permanent storage. The cas.text contains the APIs that extend the CAS to support
- artifact (including <quote>text</quote>) analysis.</para>
-
- <section id="ugr.ref.cas.javadocs.cas_package">
- <title>APIs in the CAS package</title>
-
- <para>The main objects implementing the APIs discussed here are shown in the diagram
- below. The hierarchy represents that there is a way to get from an upper object to an
- instance of the lower object, usually by using a method on the upper object; this is not
- an inheritance hierarchy.
- <figure id="ugr.ref.cas.fig.api_hierarchy">
- <title>CAS Object hierarchy</title>
- <mediaobject>
- <imageobject>
- <imagedata width="5.8in" format="JPG"
- fileref="&imgroot;image001.png"/>
- </imageobject>
- <textobject><phrase>CAS object hierarchy</phrase></textobject>
- </mediaobject>
- </figure> </para>
-
- <para>The main Interface is the CAS interface. This has most of the functionality of the
- CAS, except for the type system metadata access, and the indexing access. JCas and CAS
- are alternative representations and API approaches to the CAS; each has a method to
- get the other. You can mix JCas and CAS APIs in your application as needed. To use the
- JCas APIs, you have to create the Java classes that correspond to the CAS types, and
- include them in the Java class path of the application. If you have a CAS object, you can
- get a JCas object by using the getJCas() method call on the CAS object; likewise, you
- can get the CAS object from a JCas by using the getCAS() method call on the JCas object.
- There is also a low level CAS interface that is not part of the official API, and is
- intended for internal use only – it is not documented here.</para>
-
- <para>The type system metadata APIs are found in the TypeSystem interface. The objects
- defining each type and feature are defined by the interfaces Type and Feature. The
- Type interface has methods to see what types subsume other types, to iterate over the
- types available, and to extract information about the types, including what
- features it has. The Feature interface has methods that get what type it belongs to,
- its name, and its range (the kind of values it can hold).</para>
-
- <para>The FSIndexRepository gives you access to methods to get instances of indexes, and
- also provides access to the iterator over all indexed feature structures:
- <literal>getAllIndexedFS(aType)</literal>.
- The FSIndex and AnnotationIndex objects give you methods to create instances of
- iterators.</para>
-
- <para>Iterators and the CAS methods that create new feature structures return
- FeatureStructure objects. These objects can be used to set and get the values of
- defined features within them.</para>
- </section>
- </section>
-
- <section id="ugr.ref.cas.typemerging">
- <title>Type Merging</title>
-
- <para>When annotators are combined in an aggregate, their defined type systems are merged.
- This is designed to support independent development of annotator components. The merge
- results in a single defined type system for CASes that flow through a particular set of
- annotators.</para>
-
- <para>The basic operation of a type system merge is to iterate through all the defined types,
- and if two annotators define the same fully qualified type name,
- to take the features defined for those types
- and form a logical union of those features. This operation requires that same-named features
- have the same range type names. The resulting type system has features comprising the union
- of all features over all the various definitions for this type in different annotators.
- </para>
-
- <para>Feature merging checks that for all features having the same name in a type, that the
- range type is identical; otherwise an error is signaled.</para>
-
- <para>Types are combined for merging when their fully qualified names are the same.
- Two different definitions can be merged even if their supertype definitions do not match, if
- one supertype subsumes the other supertype; otherwise an error is signaled. Likewise, two types
- with the same name can be merged only if their features can be merged.
- </para>
- </section>
-
- <section id="ugr.ref.cas.limitedmultipleaccess">
- <title>Limited multi-thread access to read-only CASs</title>
-
- <para>Some applications may find it useful to scale up pipelines and run these in parallel.</para>
- <para>
- Generally, CASs are not threadsafe, and only one thread at a time may operate on it. In many
- scenarios, a CAS may be initialized and then filled with Feature Structures, and after some point,
- no more updates to that particular CAS will be done.</para>
-
- <para>
- If a CAS is no longer going to be changed, it is possible to
- access it on multiple threads in a read-only mode, simultaneously, with some limitations. Limitations
- arise because some UIMA Framework activities may update internal CAS data structures.</para>
-
- <para>Operational data is updated while running a pipeline when a PEAR is entered or exited,
- because PEARs establish new class loaders and can potentially switch the JCas classes being used
- (This happens because the class loaders might define different JCas cover classes
- implementing the same UIMA type).
- Because of this, you cannot have multiple pipelines accessing a CAS in read-only mode if one or more of those
- pipelines contains a PEAR. There are other edge cases where this may happen as well; for example, if you are
- running a pipeline with an Extension Class Loader,
- and have a callback routine loaded under a different class loader, UIMA will switch the JCas classes when
- calling the callback.
- </para>
- </section>
-</chapter>
\ No newline at end of file
diff --git a/uima-docbook-references/src/docbook/ref.compress.xml b/uima-docbook-references/src/docbook/ref.compress.xml
deleted file mode 100644
index 84ab76e76..000000000
--- a/uima-docbook-references/src/docbook/ref.compress.xml
+++ /dev/null
@@ -1,212 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
-<!ENTITY imgroot "images/references/ref.compress/">
-<!ENTITY tp "ugr.ref.compress.">
-<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >
-%uimaents;
-]>
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-<chapter id="ugr.ref.compress">
- <title>Compressed Binary CASes</title>
-
- <section id="ugr.ref.compress.overview">
- <title>Binary CAS Compression overview</title>
-
- <para>UIMA has a proprietary binary serialization format, used internally
- for several things, including communicating with embedded C++ annotators using
- UIMA-CPP. This binary format is also selectable for use with UIMA-AS. Its use
- requires that the source and target systems implement the identical type system
- (because the type system is not sent, and internal coding is used within the
- format that is keyed to the particular type system).</para>
-
- <para>Starting with version 2.4.1, two additional forms of binary serialization are added.
- Both compress the data being serialized; typical size ratios can approach 50 : 1,
- depending on the exact contents of the CAS, when compared with normal binary serialization.
- </para>
-
- <para>The two forms are called 4 and 6, for historical/internal reasons. The serialized forms
- of both of these is fixed, but not currently standardized, and the form being used is encoded in the header so
- that the appropriate deserializer can be chosen. Both forms include support for Delta CAS
- being returned from a service.</para>
-
- <para>Form 6 builds on form 4, and adds: serializing only those feature structures which
- are reachable (that is, in some index, or referenced by other reachable feature structures),
- and type filtering.</para>
-
- <para>Type filtering takes a source type system and a target type system, and for serializing
- (source to target), sends the binary representation of reachable feature structures in the target's type system.
- For deserializing (reading a target into a source), the filtering takes the specification being read
- as being encoded using the target's type system, and translates that into the source's type system.
- In this process, types which exist in the source but not the target are skipped (when serializing);
- types which exist in the target, but not the source are skipped when deserializing.
- <!-- Note that this
- never happens when the target is a remote service, as the client type system is guaranteed to be a superset
- of the service's due to type merging that UIMA does when starting up pipelines.
- -->
- Features that exist in some
- source type but not in the version of the same type in the target are skipped (when serializing)
- or set to default values (i.e., 0 or null) when being deserialized.</para>
-
- <para>There are two main use cases for using compressed forms. The first one is for communicating with
- UIMA-AS remote services (not yet implemented).
- <!--
- Form 6 is automatically used when binary is selected as the method
- in the <serializer> element in the UIMA-AS deployment descriptor. It is used with delta CAS
- support for the returned CAS, and with type filtering - sending to the remote service only those
- types and features it defines in its type system.
- -->
- </para>
-
- <para>The second use case is for saving compressed representations of CASes to other media, such as disk files,
- where they can be deserialized later for use in other UIMA applications.</para>
-
- </section>
-
-
- <section id="ugr.ref.compress.usage">
- <title>Using Compressed Binary CASes</title>
-
- <para>The main user interface for serializing a CAS using compression is to use one of the
- static methods named serializeWithCompression in Serialization. If you pass a Type System argument representing
- a target type system, then form 6 compression is used; otherwise form 4 is used.
- To get the benefit of only serializing reachable Feature Structure instances, without type mapping
- (which is only in form 6), pass a type system argument which is null.
- </para>
-
- <para>To deserialize into a CAS without type mapping, use one of the deserialize method in Serialization.
- There are multiple forms of this method, depending on the arguments. The forms which take extra arguments
- include a ReuseInfo may only be used with serialized forms created with form 6 compression.
- The plain form of deserialize works with all forms of binary serialization, compressed and non-compressed, by examining a common
- header which identifies the form of binary serialization used; however, for form 6, since it requires
- additional arguments, it will fail - and you need to use the other deserialize form.</para>
-
- <para>Form 6 has an additional object, ReuseInfo, which holds information which
- is required for subsequent Delta CAS format serializations / deserializations.
- It can speed up subsequent serializations of the same
- CAS (before it is further updated), for instance, if an application is sending the CAS to multiple services in parallel.
- The serializeWithCompression method returns this object when form 6 is being used.
- <!--
- This object is also
- used when deserializing delta CASs being returned from services: internally, it is saved on the client side
- when serializing a CAS to a remote service; it is saved on the service side after
- deserialization an incoming CAS. The server-side instance of ReuseInfo is provided when that CAS is being
- serialized and returned to the client in delta-cas format, and the client-side instance of it is used when deserializing the delta CAS.
- This is all done under the covers by the UIMA-AS implementation.
- -->
- </para>
- <para>In addition, the CasIOUtils class offers static load and save methods, which can be used with the SerialFormat
- enum to serialize and deserialize to URLs or streams; see the Javadocs for details.</para>
- </section>
-
- <section id="ugr.ref.compress.simple-deltas">
- <title>Simple Delta CAS serialization</title>
- <para>Use Form 4 for this, because form 6 supports delta CAS but requires
- that at the time of deserialization of a CAS (on the receiver side) which will later be delta serialized
- back to the sender,
- an instance of the ReuseInfo must be saved, and that
- same instance then used for delta serialization; furthermore, the original serialization
- (on the sender side)
- also must save an instance of the ReuseInfo and use this when deserializing the delta CAS.
- </para>
-
- <para>Form 4 may not be as efficient as form 6 in that it does not filter the CASes
- either by type systems nor by only sending reachable Feature Structure
- instances. But, it doesn't require a ReuseInfo object when doing delta serialization or
- deserialization,
- so it may be more convenient to use when saving
- delta CASes to files (as opposed to the other use case of
- a remote service returning delta CASes to a remote client).</para>
- </section>
-
- <section id="ugr.ref.compress.use-cases">
- <title>Use Case cookbook</title>
- <para>
- Here are some use cases, together with a suggested approach and example of how to use the APIs.
- </para>
-
- <para>
- <emphasis role="strong">Save a CAS to an output stream, using form 4 (no type system filtering):</emphasis>
- </para>
- <programlisting>// set up an output stream. In this example, an internal byte array.
-ByteArrayOutputStream baos = new ByteArrayOutputStream(OUT_BFR_INIT_SZ);
-Serialization.serializeWithCompression(casSrc, baos);
- // or
-CasIOUtls.save(casSrc, baos, SerialFormat.COMPRESSED);
-</programlisting>
-
- <para><emphasis role="strong">Deserialize from a stream into an existing CAS:</emphasis></para>
- <programlisting>// assume the stream is a byte array input stream
-// For example, one could be created
-// from the above ByteArrayOutputStream as follows:
-ByteArrayInputStream bais = new ByteArrayInputStream(baos.toByteArray());
-// Deserialize into a cas having the identical type system
-Serialization.deserializeCAS(cas, bais);
- // or
-CasIOUtils.load(bais, aCas);
-</programlisting>
-
-<para>Note that the <code>deserializeCAS(cas, inputStream)</code> method is a general way to
-deserialize into a CAS from an inputStream for all forms of binary serialized data
-(with exceptions as noted above).
-The method reads a common header, and based on what it finds, selects the appropriate
-deserialization routine.</para>
-
-<note><para>The <code>deserialization</code> method with just 2 arguments method doesn't support type filtering, or
-delta cas deserializating for form 6. To do those, see example below.
-</para>
-</note>
-
-<para><emphasis role="strong">Serialize to an output stream, filtering out some types and/or features:</emphasis>
-</para>
-<para>
-To do this, an additional input specifying the Type System of the target must
-be supplied; this Type System should be a subset of the source CAS's.
-The <code>out</code> parameter may be an OutputStream, a DataOutputStream, or a File.
-</para>
-
-<programlisting>// set up an output stream. In this example, an internal byte array.
-ByteArrayOutputStream baos = new ByteArrayOutputStream(OUT_BFR_INIT_SZ);
-Serialization.serializeWithCompression(cas, out, tgtTypeSystem);
-</programlisting>
-
-<para><emphasis role="strong">Deserialize with type filtering:</emphasis></para>
-<para>There are 2 type systems involved here: one is the receiving CAS, and the other is the type system
-used to decode the serialized form. This may optionally be stored with the serialized form:</para>
-<programlisting>CasIOUtils.save(cas, out, SerialFormat.COMPRESSED_FILTERED_TS);
-</programlisting>
-<para>and/or it can be supplied at load time. Here's two examples of suppling this at load time:</para>
-<programlisting>CasIOUtils.load(input, cas, typeSystem);
-CasIOUtils.load(input, type_system_serialized_form_input, cas);
-</programlisting>
-
-<para>The reuseInfo should be null unless
-deserializing a delta CAS, in which case, it must be the reuse info captured when
-the original CAS was serialized out.
-If the target type system is identical to the one in the CAS, you may pass null for it.
-If a delta cas is not being received, you must pass null for the reuseInfo.
-</para>
-<programlisting>ByteArrayInputStream bais = new ByteArrayInputStream(baos.toByteArray());
-Serialization.deserializeCAS(cas, bais, tgtTypeSystem, reuseInfo);
-</programlisting>
-</section>
-
-
-</chapter>
\ No newline at end of file
diff --git a/uima-docbook-references/src/docbook/ref.config.xml b/uima-docbook-references/src/docbook/ref.config.xml
deleted file mode 100644
index 270f9d799..000000000
--- a/uima-docbook-references/src/docbook/ref.config.xml
+++ /dev/null
@@ -1,292 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
-<!ENTITY imgroot "images/references/ref.config/">
-<!ENTITY tp "ugr.ref.config.">
-<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >
-%uimaents;
-]>
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-<chapter id="ugr.ref.config">
- <title>UIMA Setup and Configuration</title>
- <titleabbrev>Setup and Configuration</titleabbrev>
-
- <section id="ugr.ref.config.properties">
- <title>UIMA JVM Configuration Properties</title>
-
- <para> Some updates change UIMA's behavior between released versions. For example, sometimes an error check
- is enhanced, and this can cause something that previously incorrect but not checked, to now signal an error.
- Often, users will want these kinds of things to be ignored, at least for a while, to give them time to
- analyze and correct the issues.
- </para>
-
- <para>
- To enable users to gradually address these issues, there are some global JVM properties
- for UIMA that can restore earlier behaviors, in some cases.
- These are detailed in the table below. Additionally, there are other JVM properties that can
- be used in checking and optimizing some performance trade-offs, such as the automatic index protection.
- For the most part, you don't need to assign any values to these properties,
- just define them. For example to disable the enhanced check that insures you
- don't add a subtype of AnnotationBase to the wrong View, you could disable this by
- adding the JVM argument <code>-Duima.disable_enhanced_check_wrong_add_to_index</code>.
- This would remove the enhanced
- checking for this, added in version 2.7.0 (the previously existing partial checking is
- still there, though).
- </para>
- </section>
-
- <section id="ugr.ref.config.protect-index">
- <title>Configuring index protection</title>
-
- <para>A new feature in version 2.7.0 optionally can include checking for invalid feature updates
- which could corrupt indexes. Because this checking can slightly slow down performance, there are
- global JVM properties to control it. The suggested way to operation with these is as follows.
- <itemizedlist>
- <listitem><para>At the beginning, run with automatic protection enabled (the default), but
- turn on explicit reporting (<code>-Duima.report_fs_update_corrupts_index</code>)</para></listitem>
- <listitem><para>For all reported instances, examine your code to see if you can restructure to
- do the updates before adding the FS to the indexes. Where you cannot, surround the code doing
- these updates with a try / finally or block form of <code>protectIndexes()</code>,
- which is described in
- <xref linkend="ugr.ref.cas.updating_indexed_feature_structures"/> (and also is similarly available with JCas).
- </para></listitem>
- <listitem><para>After no further reports, for maximum performance, leave in the protections
- you may have installed in the above step, and then disable the reporting and runtime checking,
- using the JVM argument
- <code>-Duima.disable_auto_protect_indexes</code>, and removing (if present)
- <code>-Duima.report_fs_update_corrupts_index</code>.</para></listitem>
- </itemizedlist>
- One additional JVM property, <code>-Duima.throw_exception_when_fs_update_corrupts_index</code>,
- is intended to be used in automated build / testing configurations. It causes the framework to throw
- a UIMARuntimeException if an update outside of a <code>protectIndexes</code> block occurs
- that could corrupt the indexes,
- rather than "recovering" this.
- </para>
- </section>
-
- <section id="ugr.ref.config.property-table">
- <title>Properties Table</title>
-
- <para>This table describes the various JVM defined properties; specify these on the Java command line
- using -Dxxxxxx, where the xxxxxx is one of
- the properties starting with <code>uima.</code> from the table below.</para>
- <informaltable frame="all" rowsep="1" colsep="1">
- <tgroup cols="3">
- <colspec colnum="1" colname="Title" colwidth="1*"/>
- <colspec colnum="2" colname="Description" colwidth="3*"/>
- <colspec colnum="3" colname="Version" colwidth= "0.5*"/>
-
- <spanspec spanname="fullwidth" namest="Title" nameend="Version" align="center"/>
-
- <tbody>
- <row>
- <entry><emphasis role="bold">Title</emphasis></entry>
- <entry><emphasis role="bold">Property Name & Description</emphasis></entry>
- <entry><emphasis role="bold">Since Version</emphasis></entry>
- </row>
-
-
- <!-- ******************************************************************************* -->
- <row>
- <entry><para>Use built-in Java Logger as default back-end</para></entry>
-
- <entry><para><code>uima.use_jul_as_default_uima_logger</code></para>
-
- <para>See <ulink url="https://issues.apache.org/jira/browse/UIMA-5381">UIMA-5381</ulink>.
- The standard UIMA logger uses an slf4j implementation, which, in turn hooks up to
- a back end implementation based on what can be found in the class path (see slf4j documentation).
- If no backend implementation is found, the slf4j default is to use a NOP logger back end
- which discards all logging.</para>
-
- <para>When this flag is specified, the behavior of the UIMA logger
- is altered to use the built-in-to-Java logging implementation
- as the back end for the UIMA logger.
- </para></entry>
- <entry><para>3.0.0</para></entry>
- </row>
-
- <!-- ******************************************************************************* -->
- <!--
- <row>
- <entry><para>Allow duplicate addToIndexes for identical Feature Structures</para></entry>
-
- <entry><para><code>uima.allow_duplicate_add_to_indexes</code> (default is false)</para>
-
- <para>See <ulink url="https://issues.apache.org/jira/browse/UIMA-4135">UIMA-4135</ulink>
- and <ulink url="https://issues.apache.org/jira/browse/UIMA-3399">UIMA-3399</ulink>.
- As of version 2.7.0, adding a particular Feature Structure
- to the indexes more than once is ignored. The old behavior
- may be restored by this property.</para></entry>
- <entry><para>2.7.0</para></entry>
- </row>
- -->
-
- <!-- ******************************************************************************* -->
- <!--
- <row>
- <entry><para>adding Annotation to wrong View</para></entry>
-
- <entry><para><code>uima.disable_enhanced_check_wrong_add_to_index</code></para>
-
- <para>See <ulink url="https://issues.apache.org/jira/browse/UIMA-4099">UIMA-4099</ulink>.
- Feature Structures which are subtypes of AnnotationBase
- may only be added to the View corresponding to their
- Sofa reference. From version 2.7.0, there is additional
- checking of this which can be disabled if needed
- for backward compatibility.</para></entry>
- <entry><para>2.7.0</para></entry>
- </row>
- -->
-
- <!-- ******************************************************************************* -->
- <row>
- <entry><para>XML: enable doctype declarations</para></entry>
- <entry><para><code>uima.xml.enable.doctype_decl</code> (default is false)</para>
-
- <para>See <ulink url="https://issues.apache.org/jira/browse/UIMA-6064">UIMA-6064</ulink>
- Normally, this is turned off to avoid exposure to malicious XML; see
- <ulink url="https://www.owasp.org/index.php/XML_External_Entity_(XXE)_Processing">
- XML External Entity processing vulnerability</ulink>.
- </para>
- </entry>
-
- <entry><para>2.10.4, 3.1.0</para></entry>
- </row>
-
- <row>
- <entry spanname="fullwidth"><emphasis role="bold">Index protection properties</emphasis></entry>
- </row>
- <!-- ******************************************************************************* -->
- <row>
- <entry><para>Report Illegal Index-key Feature Updates</para></entry>
-
- <entry><para><code>uima.report_fs_update_corrupts_index</code> (default is not to report)</para>
-
- <para>See <ulink url="https://issues.apache.org/jira/browse/UIMA-4135">UIMA-4135</ulink>.
- Updating Features which are used in Set and Sorted
- indexes as "keys" may corrupt the indexes, if the Feature Structure (FS)
- has been added to the indexes. To update these, you must first
- completely remove the FS from the indexes in all views, then do the updates, and then
- add it back. UIMA now checks for this (unless specifically disabled, see below),
- and if this property is set, will log WARN messages for each occurrence unless
- the user does explicit <code>protectIndexes</code> (see CAS JavaDocs for CAS / JCas <code>protectIndexes</code> methods), if this
- property is defined.</para>
- <para>To scan the logs for these reports, search for instances of lines having the string
- <code>While FS was in the index, the feature</code></para>
-
- <para>Specifying this property overrides <code>uima.disable_auto_protect_indexes</code>.</para>
-
- <para>Users would run with this property defined, and then for high performance,
- would use the report to manually change their code to avoid the problem or
- to wrap the updates with a <code>protectIndexes</code> kind of protection (see the
- reference manual, in the CAS or JCas chapters, for examples of user code doing this,
- and then run with the protection turned off (see below).
-
- </para></entry>
-
- <entry><para>2.7.0</para></entry>
- </row>
-
- <!-- ******************************************************************************* -->
- <row>
- <entry><para>Throw exception on illegal Index-key Feature Updates</para></entry>
-
- <entry><para><code>uima.exception_when_fs_update_corrupts_index</code> (default is false)</para>
-
- <para>See <ulink url="https://issues.apache.org/jira/browse/UIMA-4150">UIMA-4150</ulink>.
- Throws a UIMARuntimeException if an Indexed FS feature used as a key in one or more
- indexes is updated, outside of an explicit <code>protectIndexes</code> block.. \
- This is intended for use in automated build and test environments,
- to provide a strong signal if this kind of mistake gets into the build.
- If it is not set, then the other properties specify if corruption should be checked for,
- recovered automatically, and / or reported</para>
-
- <para>Specifying this property also forces <code>uima.report_fs_update_corrupts_index</code>
- to true even if it was set to false.</para>
-
- </entry>
-
- <entry><para>2.7.0</para></entry>
- </row>
-
- <!-- ******************************************************************************* -->
- <row>
- <entry><para>Disable the index corruption checking</para></entry>
-
- <entry><para><code>uima.disable_auto_protect_indexes</code></para>
-
- <para>See <ulink url="https://issues.apache.org/jira/browse/UIMA-4135">UIMA-4135</ulink>.
- After you have fixed all reported issues identified with the above report,
- you may set this property to omit this check, which may slightly improve
- performance.</para>
- <para>Note that this property is ignored if the <code>-Dexception_when_fs_update_corrupts_index</code>
- or <code>-Dreport_fs_update_corrupts_index</code></para>
- </entry>
-
- <entry><para>2.7.0</para></entry>
- </row>
-
-
- <row>
- <entry spanname="fullwidth"><emphasis role="bold">Measurement / Tracing properties</emphasis></entry>
- </row>
- <!-- ******************************************************************************* -->
-
- <row>
- <entry><para>Trace Feature Structure Creation/Updating</para></entry>
-
- <entry><para><code>uima.trace_fs_creation_and_updating</code></para>
- <para>This causes a trace file to be produced in the current working directory.
- The file has one line for each Feature Structure that is created, and include
- information on the cas/cas-view, and the features that are set for the Feature Structure.
- There is, additionally, one line for each Feature Structure update.
- Updates that occur next-to trace information for the same Feature Structure are combined.
- </para>
-
- <para>This can generate a lot of output, and definitely slows down execution.</para>
- </entry>
-
- <entry><para>2.10.1</para></entry>
- </row>
-
-
- <row>
- <entry><para>Measure index flattening optimization</para></entry>
-
- <entry><para><code>uima.measure.flatten_index</code></para>
-
- <para>See <ulink url="https://issues.apache.org/jira/browse/UIMA-4357">UIMA-4357</ulink>.
- This creates a short report to System.out when Java is shutdown.
- The report has some statistics about the automatic management of
- flattened index creation and use.</para>
-
- </entry>
-
- <entry><para>2.8.0</para></entry>
- </row>
- -->
-
- </tbody>
- </tgroup>
- </informaltable>
- <para>Some additional global flags intended for helping v3 migration are documented in the V3 user's guide.</para>
- </section>
-
-</chapter>
\ No newline at end of file
diff --git a/uima-docbook-references/src/docbook/ref.javadocs.xml b/uima-docbook-references/src/docbook/ref.javadocs.xml
deleted file mode 100644
index 97189406d..000000000
--- a/uima-docbook-references/src/docbook/ref.javadocs.xml
+++ /dev/null
@@ -1,89 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
-<!ENTITY imgroot "images/references/ref.javadocs/">
-<!ENTITY tp "ugr.ref.javadocs.">
-<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >
-%uimaents;
-]>
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-<chapter id="ugr.ref.javadocs">
- <title>Javadocs</title>
-
- <para>The details of all the public APIs for UIMA are contained in the API Javadocs. These are located in the docs/api
- directory; the top level to open in your browser is called <ulink url="api/index.html"/>.</para>
-
- <para>Eclipse supports the ability to attach the Javadocs to your project. The Javadoc should already be attached
- to the <literal>uimaj-examples</literal> project, if you followed the setup instructions in <olink
- targetdoc="&uima_docs_overview;"/> <olink
- targetdoc="&uima_docs_overview;" targetptr="ugr.ovv.eclipse_setup.example_code"/>. To attach
- Javadocs to your own Eclipse project, use the following instructions.</para>
-
- <note><para>As an alternative, you can add the UIMA source to the UIMA binary distribution; if you
- do this you not only will have the Javadocs automatically available (you can skip the following
- setup), you will have the ability to step through the UIMA framework code while debugging.
- To add the source, follow the instructions as described in the setup chapter:
- <olink targetdoc="&uima_docs_overview;"/>
- <olink targetdoc="&uima_docs_overview;" targetptr="ugr.ovv.eclipse_setup.adding_source"/>.</para></note>
-
- <para>To add the Javadocs, open a project which is referring to the UIMA APIs in its class path, and open the project properties. Then pick
- Java Build Path. Pick the "Libraries" tab and select one of the UIMA library entries (if you don't have, for
- instance, uima-core.jar in this list, it's unlikely your code will compile). Each library entry has a small ">"
- sign on its left - click that to expand the view to see the Javadoc location. If you highlight that and press edit - you
- can add a reference to the Javadocs, in the following dialog:
-
-
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata width="5.8in" format="JPG" fileref="&imgroot;image002.jpg"/>
- </imageobject>
- <textobject><phrase>Screenshot of attaching Javadoc to source in Eclipse</phrase></textobject>
- </mediaobject>
- </screenshot></para>
-
- <para>Once you do this, Eclipse can show you Javadocs for UIMA APIs as you work. To see the Javadoc for a UIMA API, you
- can hover over the API class or method, or select it and press shift-F2, or use the menu Navigate →
- Open External Javadoc, or open the Javadoc view (Window → Show View → Other
- → Java → Javadoc).</para>
-
- <para>In a similar manner, you can attach the source for the UIMA framework, if you download the source
- distribution. The source corresponding to particular
- releases is available from the Apache UIMA web site (<ulink url="http://uima.apache.org"/>) on the
- downloads page.</para>
-
- <section id="ugr.ref.javadocs.libraries">
- <title>Using named Eclipse User Libraries</title>
- <para>You can also create a named "user library" in Eclipse containing the UIMA Jars, and attach the Javadocs (or
- optionally, the sources); this named library is saved in the Eclipse workspace. Once created, it can be
- added to the classpath of newly created Eclipse projects.</para>
-
- <para>Use the menu option Project → Properties
- → Java Build Path, and then pick the Libraries tab, and click the Add Library button. Then select
- User Libraries, click "Next", and pick the library you created for the UIMA Jars.</para>
-
- <para>To create this library in the workspace,
- use the same menu picks as above, but after you select the User Libraries and click "Next", you can click the "New Library..."
- button to define your new library. You use the "Add Jars" button and multi-select all the Jars in the lib directory
- of the UIMA binary distribution. Then you add the Javadoc attachment for each Jar. The path to use is
- file:/ -- insert the path to your install of UIMA -- /docs/api. After you do this for the first Jar, you can
- copy this string to the clipboard and paste it into the rest of the Jars.</para>
- </section>
-</chapter>
\ No newline at end of file
diff --git a/uima-docbook-references/src/docbook/ref.jcas.xml b/uima-docbook-references/src/docbook/ref.jcas.xml
deleted file mode 100644
index 52158aeb2..000000000
--- a/uima-docbook-references/src/docbook/ref.jcas.xml
+++ /dev/null
@@ -1,677 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
-<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >
-%uimaents;
-]>
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-<chapter id="ugr.ref.jcas">
- <title>JCas Reference</title>
-
- <para>The CAS is a system for sharing data among annotators, consisting of data structures
- (definable at run time), sets of indexes over these data, metadata describing these, subjects of
- analysis, and a high
- performance serialization/deserialization mechanism. JCas provides Java approach to
- accessing CAS data, and is based on using generated, specific Java classes for each CAS
- type.</para>
-
- <para>Annotators process one CAS per call to their process method. During processing,
- annotators can retrieve feature structures from the passed in CAS, add new ones, modify
- existing ones, and use and update CAS indexes. Of course, an annotator can also use plain
- Java Objects in addition; but the data in the CAS is what is shared among annotators within
- an application.</para>
-
- <para>All the facilities present in the APIs for the CAS are available when using the JCas
- APIs; indeed, you can use the getCas() method to get the corresponding CAS object from a
- JCas (and vice-versa). The JCas APIs often have helper methods that make using this
- interface more convenient for Java developers.</para>
-
- <para>The data in the CAS are typed objects having fields. JCas uses a set of generated Java
- classes (each corresponding to a particular CAS type) with <quote>getter</quote> and
- <quote>setter</quote> methods for the features, plus a constructor so new instances can
- be made. The Java classes stores the data in the class instance.</para>
-
- <para>Users can modify the JCas generated
- Java classes by adding fields to them; this allows arbitrary non-CAS data to also be
- represented within the JCas objects, as well; however, the non-CAS data stored in the JCas
- object instances cannot be shared with annotators using the plain CAS, unless special
- provision is made - see the chapter in the v3 user's guide on storing arbitrary
- Java objects in the CAS.</para>
-
- <para>The JCas class Java source files are generated from XML type system descriptions. The
- JCasGen utility does the work of generating the corresponding Java Class Model for the CAS
- types. There are a variety of ways JCasGen can be run; these are described later. You
- include the generated classes with your UIMA component, and you can publish these classes
- for others who might want to use your type system.</para>
-
- <para>JCas classes are not required for all UIMA types. Those types which don't have
- corresponding JCas classes use the nearest JCas class corresponding to a type in their superchain.</para>
-
- <para>The specification of the type system in XML can be written using a conventional text
- editor, an XML editor, or using the Eclipse plug-in that supports editing UIMA
- descriptors.</para>
-
- <para>Changes to the type system are done by changing the XML and regenerating the
- corresponding Java Class Models. Of course, once you've published your type system
- for others to use, you should be careful that any changes you make don't adversely
- impact the users. Additional features can be added to existing types without breaking
- other code.</para>
-
- <para>A separate Java class is generated for each type; this type implements the CAS
- FeatureStructure interface, as well as having the special getters and setters for the
- included features. The generated Java classes have methods (getters and setters) for the
- fields as defined in the XML type specification. Descriptor comments are reflected in the
- generated Java code as Java-doc style comments.</para>
-
-
- <section id="ugr.ref.jcas.name_spaces">
- <title>Name Spaces</title>
-
- <para>Full Type names consist of a <quote>namespace</quote> prefix dotted with a simple
- name. Namespaces are used like packages to avoid collisions between types that are
- defined by different people at different times. The namespace is used as the Java
- package name for generated Java files.</para>
-
- <para>Type names used in the CAS correspond to the generated Java classes directly. If the
- CAS name is com.myCompany.myProject.ExampleClass, the generated Java class is in the
- package com.myCompany.myProject, and the class is ExampleClass.</para>
-
- <para>
- An exception to this rule is the built-in types
- starting with <literal>uima.cas </literal>and <literal>uima.tcas</literal>;
- these names are mapped to Java packages named
- <literal>org.apache.uima.jcas.cas</literal> and
- <literal>org.apache.uima.jcas.tcas</literal>.</para>
-
- </section>
-
- <section id="ugr.ref.jcas.use_of_description">
- <title>XML description element</title>
- <titleabbrev>Use of XML Description</titleabbrev>
-
- <para>Each XML type specification can have <description ...
- > tags. The description for a type will be copied into the generated Java code, as a
- Javadoc style comment for the class. When writing these descriptions in the XML type
- specification file, you might want to use html tags, as allowed in Javadocs.</para>
-
- <para>If you use the Component Description Editor, you can write the html tags normally,
- for instance, <quote><h1>My Title</h1></quote>. The Component
- Descriptor Editor will take care of coverting the actual descriptor source so that it
- has the leading <quote><</quote> character written as <quote>&lt;</quote>,
- to avoid confusing the XML type specification. For example, <p> would be written
- in the source of the descriptor as &lt;p>. Any characters used in the Javadoc
- comment must of course be from the character set allowed by the XML type specification.
- These specifications often start with the line <?xml version=<quote>1.0</quote>
- encoding=<quote>UTF-8</quote> ?>, which means you can use any of the UTF-8
- characters.</para>
-
- </section>
-
- <section id="ugr.ref.jcas.mapping_built_ins">
- <title>Mapping built-in CAS types to Java types</title>
-
- <para>The built-in primitive CAS types map to Java types as follows:</para>
-
-
- <programlisting>uima.cas.Boolean → boolean
-uima.cas.Byte → byte
-uima.cas.Short → short
-uima.cas.Integer → int
-uima.cas.Long → long
-uima.cas.Float → float
-uima.cas.Double → double
-uima.cas.String → String</programlisting>
-
- </section>
-
- <section id="ugr.ref.jcas.augmenting_generated_code">
- <title>Augmenting the generated Java Code</title>
-
- <para>The Java Class Models generated for each type can be augmented by the user. Typical
- augmentations include adding additional (non-CAS) fields and methods, and import
- statements that might be needed to support these. Commonly added methods include
- additional constructors (having different parameter signatures), and
- implementations of toString().</para>
-
- <para>To augment the code, just edit the generated Java source code for the class named the
- same as the CAS type. Here's an example of an additional method you might add; the
- various getter methods are retrieving values from the instance:</para>
-
-
- <programlisting>public String toString() { // for debugging
- return "XsgParse "
- + getslotName() + ": "
- + getheadWord().getCoveredText()
- + " seqNo: " + getseqNo()
- + ", cAddr: " + id
- + ", size left mods: " + getlMods().size()
- + ", size right mods: " + getrMods().size();
-}</programlisting>
-
- <!-- does not apply for v3
- <section id="ugr.ref.jcas.data_persistence">
- <title>Persistence of additional data</title>
- <para>If you add custom instance fields to JCas cover classes, these exist in the JCas cover object instance,
- but not in the CAS itself. Each time a CAS object is referenced (by an iterator, or by following a Feature
- Structure reference), a new JCas cover object instance may be created. If you need these values, you can (a)
- make them CAS values if possible, or (b) hold a reference to the the particular JCas cover object instance in
- your Java code. For some simple cases, setting the the performance tuning option JCAS_CACHE_ENABLE (see
- <olink targetdoc="&uima_docs_tutorial_guides;"/>
- <olink targetdoc="&uima_docs_tutorial_guides;" targetptr="tug.application.pto"/>)
- to true
- will cause the same JCas cover object that was previously used for a particular CAS Feature Structure to be
- reused. However, this capability won't work when other factors interfere with the ability to reuse the same
- object. Pear isolation is an example of this.</para>
- <para>Because of this, and because the JCas Cache holds on to the JCas cover objects beyond their useful life and
- prevents them from being garbage collected, it is normally recommended running with the
- JCAS_CACHE_ENABLE set to "false".</para>
- </section>
- -->
-
- <section id="ugr.ref.jcas.keeping_augmentations_when_regenerating">
- <title>Keeping hand-coded augmentations when regenerating</title>
-
- <para>If the type system specification changes, you have to re-run the JCasGen
- generator. This will produce updated Java for the Class Models that capture the
- changed specification. If you have previously augmented the source for these Java
- Class Models, your changes must be merged with the newly (re)generated Java source
- code for the Class Models. This can be done by hand, or you can run the version of JCasGen
- that is integrated with Eclipse, and use automatic merging that is done using Eclipse's EMF
- plug-in. You can obtain Eclipse and the needed EMF plug-in from <ulink
- url="http://www.eclipse.org/"/>.</para>
-
- <para>If you run the generator version that works without using Eclipse, it will not
- merge Java source changes you may have previously made; if you want them retained,
- you'll have to do the merging by hand.</para>
-
- <para>The Java source merging will keep additional constructors, additional fields,
- and any changes you may have made to the readObject method (see below). Merging will
- <emphasis>not</emphasis> delete classes in the target corresponding to deleted CAS types, which no longer
- are in the source – you should delete these by hand.</para>
-
- <warning><para>The merging supports Java 1.4 syntactic constructs only.
- JCasGen generates Java 1.4 code, so as long as any code you change here also sticks to
- only Java 1.4 constructs, the merge will work. If you use Java 5 or later specific syntax or constructs, the merge
- operation will likely fail to merge properly.</para></warning>
- </section>
-
- <section id="ugr.ref.jcas.additional_constructors">
- <title>Additional Constructors</title>
-
- <para>Any additional constructors that you add must include the JCas argument. The
- first line of your constructor is required to be</para>
-
-
- <programlisting>this(jcas); // run the standard constructor</programlisting>
-
- <para>where jcas is the passed in JCas reference. If the type you're defining
- extends <literal>uima.tcas.Annotation</literal>, JCasGen will automatically
- add a constructor which takes 2 additional parameters – the begin and end Java
- int values, and set the <literal>uima.tcas.Annotation</literal>
- <literal>begin</literal> and <literal>end</literal> fields.</para>
-
- <para>Here's an example: If you're defining a type MyType which has a
- feature parent, you might make an additional constructor which has an additional
- argument of parent:</para>
-
-
- <programlisting>MyType(JCas jcas, MyType parent) {
- this(jcas); // run the standard constructor
- setParent(parent); // set the parent field from the parameter
-}</programlisting>
-
- <section id="ugr.ref.jcas.using_readobject">
- <title>Using readObject</title>
-
- <para>Fields defined by augmenting the Java Class Model to include additional
- fields represent data that exist for this class in Java, in a local JVM (Java Virtual
- Machine), but do not exist in the CAS when it is passed to other environments (for
- example, passing to a remote annotator).</para>
-
- <para>A problem can arise when new instances are created, perhaps by the underlying
- system when it iterates over an index, which is: how to insure that any additional
- non-CAS fields are properly initialized. To allow for arbitrary initialization
- at instance creation time, an initialization method in the Java Class Model,
- called readObject is used. The generated default for this method is to do nothing,
- but it is one of the methods that you can modify – to do whatever
- initialization might be needed. It is called with 0 parameters, during the
- constructor for the object, after the basic object fields have been set up. It can
- refer to fields in the CAS using the getters and setters, and other fields in the Java
- object instance being initialized.</para>
-
- <para>A pre-existing CAS feature structure could exist if a CAS was being passed to
- this annotator; in this case the JCas system calls the readObject method when
- creating the corresponding Java instance for the first time for the CAS feature
- structure. This can happen at two points: when a new object is being returned from an
- iterator over a CAS index, or a getter method is getting a field for the first time
- whose value is a feature structure.</para>
-
- </section>
- </section>
-
- <section id="ugr.ref.jcas.modifying_generated_items">
- <title>Modifying generated items</title>
-
- <para>The following modifications, if made in generated items, will be preserved when
- regenerating.</para>
-
- <para>The public/private etc. flags associated with methods (getters and setters).
- You can change the default (<quote>public</quote>) if needed.</para>
-
- <para><quote>final</quote> or <quote>abstract</quote> can be added to the type
- itself, with the usual semantics.</para>
-
- </section>
- </section>
-
- <section id="ugr.ref.jcas.merging_types_from_other_specs">
- <title>Merging types</title>
- <titleabbrev>Merging Types</titleabbrev>
- <para>Type definitions are merged by the framework from all the components being run together.</para>
-
- <section id="ugr.ref.jcas.merging_types.aggregates_and_cpes">
- <title>Aggregate AEs and CPEs as sources of types</title>
-
- <para>When running aggregate AEs (Analysis Engines), or a set of AEs in a collection processing engine, the
- UIMA framework will build a merged type system (Note: this <quote>merge</quote> is merging types, not to be
- confused with merging Java source code, discussed above). This merged type system has all the types of every
- component used in the application. In addition, application code can use UIMA Framework APIs to read and merge
- type descriptions, manually.</para>
-
- <para>In most cases, each type system can have its own Java Class Models generated individually, perhaps at an
- earlier time, and the resulting class files (or .jar files containing these class files) can be put in the
- class path to enable JCas.</para>
-
- <para>However, it is possible that there may be multiple definitions of the same CAS type, each of which might
- have different features defined. In this case, the UIMA framework will create a merged type by accumulating
- all the defined features for a particular type into that type's type definition. However, the JCas
- classes for these types are not automatically merged, which can create some issues for JCas users, as
- discussed in the next section.</para>
-
- </section>
-
- <section id="ugr.ref.jcas.merging_types.jcasgen_support">
- <title>JCasGen support for type merging</title>
-
- <para>When there are multiple definitions of the same CAS type with different features defined, then JCasGen
- can be re-run on the merged type system, to create one set of JCas Class definitions for the merged types,
- which can then be shared by all the components.
- Directions for running JCasGen can be found in <olink
- targetdoc="&uima_docs_tools;"/> <olink
- targetdoc="&uima_docs_tools;" targetptr="ugr.tools.jcasgen"/>. This is typically done by the person who
- is assembling the Aggregate Analysis Engine or Collection Processing Engine. The resulting merged Java
- Class Model will then contain get and set methods for the complete set of features. These Java classes must
- then be made available in the class path, <emphasis>replacing</emphasis> the pre-merge versions of the
- classes.</para>
-
- <para>If hand-modifications were done to the pre-merge versions of the classes, these must be applied to the
- merged versions, as described in section <xref
- linkend="ugr.ref.jcas.keeping_augmentations_when_regenerating"/>, above. If just one of the
- pre-merge versions had hand-modifications, the source for this hand-modified version can be put into the
- file system where the generated output will go, and the -merge option for JCasGen will automatically
- merge the hand-modifications with the generated code. If
- <emphasis>both</emphasis> pre-merged versions had hand-modifications, then these modifications must
- be manually merged.</para>
-
- <para>An alternative to this is packaging the components as individual PEAR files, each with their own
- version of the JCas generated Classes. The Framework (as of release 2.2) can run PEAR files using the
- pear file descriptor, and supply each component with its particular version of the JCas generated class.</para>
-
- </section>
-
- <section id="ugr.ref.jcas.impact_of_type_merging_on_composability">
- <title>Impact of Type Merging on Composability of Annotators</title>
- <titleabbrev>Type Merging impacts on Composability</titleabbrev>
-
- <para>The recommended approach in UIMA is to build and maintain type systems as separate components, which are
- imported by Annotators. Using this approach, Type Merging does not occur because the Type System and its JCas
- classes are centrally managed and shared by the annotators.</para>
-
- <para>If you do choose to create a JCas Annotator that relies on Type Merging (meaning that your annotator
- redefines a Type that is already in use elsewhere, and adds its own features), this can negatively impact the
- reusability of your annotator, unless your component is used as a PEAR file.</para>
-
- <para>If not using PEAR file packaging isolation capability, whenever
- anyone wants to combine your annotator with another annotator that uses a different version of
- the same Type, they will need to be aware of all of the issues described in the previous section. They will need
- to have the know-how to re-run JCasGen and appropriately set up their classpath to include the merged Java
- classes and to not include the pre-merge classes. (To enable this, you should package these classes
- separately from other .jar files for your annotator, so that they can be more easily excluded.) And, if you
- have done hand-modifications to your JCas classes, the person assembling your annotator will need to
- properly merge those changes. These issues significantly complicate the task of combining annotators, and
- will cause your annotator not to be as easily reusable as other UIMA annotators. </para>
-
- </section>
-
- <section id="ugr.ref.jcas.documentannotation_issues">
- <title>Adding Features to DocumentAnnotation</title>
-
- <para>There is one built-in type, <literal>uima.tcas.DocumentAnnotation</literal>,
- to which applications can add additional features. (All other built-in types
- are "feature-final" and you cannot add additional features to them.) Frequently,
- additional features are added to <literal>uima.tcas.DocumentAnnotation</literal>
- to provide a place to store document-level metadata.</para>
-
- <para>For the same reasons mentioned in the previous section, adding features to
- DocumentAnnotation is not recommended if you are using JCas. Instead, it is recommended
- that you define your own type for storing your document-level metadata. You can create
- an instance of this type and add it to the indexes in the usual way. You can then
- retrieve this instance using the iterator returned from the method<literal>getAllIndexedFS(type)</literal>
- on an instance of a JFSIndexRepository object.
- (As of UIMA v2.1, you do not have to declare a custom index in your descriptor to
- get this to work).</para>
-
- <para>If you do choose to add features to DocumentAnnotation, there are additional issues to
- be aware of. The UIMA SDK provides the JCas cover class for the built-in definition of
- DocumentAnnotation, in the separate jar file <literal>uima-document-annotation.jar</literal>.
- If you add additional features to DocumentAnnotation, you must remove this jar file
- from your classpath, because you will not want to use the default JCas cover class.
- You will need to re-run JCasGen as described in <xref
- linkend="ugr.ref.jcas.merging_types.jcasgen_support"/>. JCasGen will generate a new cover
- class for DocumentAnnotation, which you must place in your classpath in lieu of the version
- in <literal>uima-document-annotation.jar</literal>.</para>
-
- <para>Also, this is the reason why the method <literal>JCas.getDocumentAnnotationFs()</literal> returns
- type <literal>TOP</literal>, rather than type <literal>DocumentAnnotation</literal>. Because the
- <literal>DocumentAnnotation</literal> class can be replaced by users, it is not part of
- <literal>uima-core.jar</literal> and so the core UIMA framework cannot have any references
- to it. In your code, you may <quote>cast</quote> the result of <literal>JCas.getDocumentAnnotationFs()</literal>
- to type <literal>DocumentAnnotation</literal>, which must be available on the classpath either via
- <literal>uima-document-annotation.jar</literal> or by including a custom version that you have generated using JCasGen.</para>
- </section>
-
- </section>
-
- <section id="ugr.ref.jcas.using_within_an_annotator">
- <title>Using JCas within an Annotator</title>
-
- <para>To use JCas within an annotator, you must include the generated Java classes output
- from JCasGen in the class path.</para>
-
- <para>An annotator written using JCas is built by defining a class for the annotator that
- extends JCasAnnotator_ImplBase. The process method for this annotator is
- written</para>
-
- <programlisting>public void process(JCas jcas)
- throws AnalysisEngineProcessException {
- ... // body of annotator goes here
-}</programlisting>
-
- <para>The process method is passed the JCas instance to use as a parameter.</para>
-
- <para>The JCas reference is used throughout the annotator to refer to the particular JCas
- instance being worked on. In pooled or multi-threaded implementations, there will be a
- separate JCas for each thread being (simultaneously) worked on.</para>
-
- <para>You can do several kinds of operations using the JCas APIs: create new feature
- structures (instances of CAS types) (using the new operator), access existing feature
- structures passed to your annotator in the JCas (for example, by using the next method of
- an iterator over the feature structures), get and set the fields of a particular
- instance of a feature structure, and add and remove feature structure instances from
- the CAS indexes. To support iteration, there are also functions to get and use indexes
- and iterators over the instances in a JCas.</para>
-
- <section id="ugr.ref.jcas.new_instances">
- <title>Creating new instances using the Java <quote>new</quote> operator</title>
- <titleabbrev>Creating new instances</titleabbrev>
-
- <para>The new operator creates new instances of JCas types. It takes at least one
- parameter, the JCas instance in which the type is to be created. For example, if there
- was a type Meeting defined, you can create a new instance of it using:
-
- <programlisting>Meeting m = new Meeting(jcas);</programlisting></para>
-
- <para>Other variations of constructors can be added in custom code; the single
- parameter version is the one automatically generated by JCasGen. For types that are
- subtypes of Annotation, JCasGen also generates an additional constructor with
- additional <quote>begin</quote> and <quote>end</quote> arguments.</para>
-
- </section>
- <section id="ugr.ref.jcas.getters_and_setters">
- <title>Getters and Setters</title>
-
- <para>If the CAS type Meeting had fields location and time, you could get or set these by
- using getter or setter methods. These methods have names formed by splicing together
- the word <quote>get</quote> or <quote>set</quote> followed by the field name, with
- the first letter of the field name capitalized. For instance
-
- <programlisting>getLocation()</programlisting></para>
-
- <para>The getter forms take no parameters and return the value of the field; the setter
- forms take one parameter, the value to set into the field, and return void.</para>
-
- <para>There are built-in CAS types for arrays of integers, strings, floats, and
- feature structures. For fields whose values are these types of arrays, there is an
- alternate form of getters and setters that take an additional parameter, written as
- the first parameter, which is the index in the array of an item to get or set.</para>
-
- </section>
-
- <section id="ugr.ref.jcas.obtaining_refs_to_indexes">
- <title>Obtaining references to Indexes</title>
-
- <para>The only way to access instances (not otherwise referenced from other
- instances) passed in to your annotator in its JCas is to use an iterator over some
- index. Indexes in the CAS are specified in the annotator descriptor. Indexes have a
- name; text annotators have a built-in, standard index over all annotations.</para>
-
- <para>To get an index, first get the JFSIndexRepository from the JCas using the method
- jcas.getJFSIndexRepository(). Here are the calls to get indexes:</para>
-
-
- <programlisting>JFSIndexRepository ir = jcas.getJFSIndexRepository();
-
-ir.getIndex(name-of-index) // get the index by its name, a string
-ir.getIndex(name-of-index, Foo.type) // filtered by specific type
-
-ir.getAnnotationIndex() // get AnnotationIndex
-jcas.getAnnotationIndex() // get directly from jcas
-ir.getAnnotationIndex(Foo.type) // filtered by specific type</programlisting>
-jcas.getAnnotationIndex(Foo.class) // better
-
- <para>For convenience, the getAnnotationIndex method is available directly on the JCas object
- instance; the implementation merely forwards to the associated index repository.</para>
-
- <para>Filtering types have to be a subtype of the type specified for this index in its
- index specification. They can be written as either Foo.type or if you have an instance
- of Foo, you can write</para>
-
- <programlisting>fooInstance.getClass()</programlisting>
-
- <para>Foo is (of course) an example of the name of the type.</para>
-
- </section>
- <section id="ugr.ref.jcas.adding_removing_instances_to_indexes">
- <title>Adding (and removing) instances to (from) indexes</title>
- <titleabbrev>Updating Indexes</titleabbrev>
-
- <para>CAS indexes are maintained automatically by the CAS. But you must add any
- instances of feature structures you want the index to find, to the indexes by using the
- call:</para>
-
- <programlisting>myInstance.addToIndexes();</programlisting>
-
- <para>Do this after setting all features in the instance <emphasis role="bold-italic">which could be used in indexing</emphasis>,
- for example, in determining the sorting order.
- See <xref linkend="ugr.ref.cas.updating_indexed_feature_structures"/> for details
- on updating indexed feature structures.
- </para>
-
- <para>When writing a Multi-View component, you may need to index instances in multiple
- CAS views. The methods above use the indexes associated with the current JCas object.
- There is a variation of the <literal>addToIndexes / removeFromIndexes</literal> methods which
- takes one argument: a reference to a JCas object holding the view in which you want to
- index this instance.
- <programlisting>myInstance.addToIndexes(anotherJCas)
-myInstance.removeFromIndexes(anotherJCas)</programlisting>
- </para>
-
- <para>
- You can also explicitly add instances to other views using the addFsToIndexes method on
- other JCas (or CAS) objects. For instance, if you had 2 other CAS views (myView1 and
- myView2), in which you wanted to index myInstance, you could write:</para>
-
- <programlisting>myInstance.addToIndexes(); //addToIndexes used with the new operator
-myView1.addFsToIndexes(myInstance); // index myInstance in myView1
-myView2.addFsToIndexes(myInstance); // index myInstance in myView2</programlisting>
-
- <para>
- The rules for determining which index to use with a particular JCas object are designed to
- behave the way most would think they should; if you need specific behavior, you can always
- explicitly designate which view the index adding and removing operations should work on.
- </para>
-
- <para>
- The rules are:
- If the instance is a subtype of AnnotationBase, then the view is the view associated with the
- annotation as specified in the feature holding the view reference in AnnotationBase.
- Otherwise, if the instance was created using the "new" operator, then the view is the view passed to the
- instance's constructor.
- Otherwise, if the instance was created by getting a feature value from some other instance, whose range
- type is a feature structure, then the view is the same as the referring instance.
- Otherwise, if the instance was created by any of the Feature Structure Iterator operations over some index,
- then it is the view associated with the index.
- </para>
-
- <para>As of release 2.4.1, there are two efficient bulk-remove methods to remove all instances of a given type,
- or all instances of a given type and its subtypes.
- These are invoked on an instance of an IndexRepository,
- for a particular view. For example, to remove all instances of Token from a particular JCas instance:
- </para>
- <programlisting>jcas.removeAllIncludingSubtypes(Token.type) or
-jcas.removeAllIncludingSubtypes(aTokenInstance.getTypeIndexID()) or
-jcas.getFsIndexRepository().
- removeAllIncludingSubtypes(jcas.getCasType(Token.type))
-</programlisting>
-
- </section>
-
- <section id="ugr.ref.jcas.using_iterators">
- <title>Using Iterators</title>
-
- <para>This chapter describes obtaining and using iterators. However, it is recommended that instead
- you use the select framework, described in a chapter in the version 3 user's guide.</para>
-
- <para>Once you have an index obtained from the JCas, you can get an iterator from the
- index; here is an example:</para>
-
-
- <programlisting>FSIndexRepository ir = jcas.getFSIndexRepository();
-FSIndex myIndex = ir.getIndex("myIndexName");
-FSIterator myIterator = myIndex.iterator();
-
-JFSIndexRepository ir = jcas.getJFSIndexRepository();
-FSIndex myIndex = ir.getIndex("myIndexName", Foo.type); // filtered
-FSIterator myIterator = myIndex.iterator();</programlisting>
-
- <para>Iterators work like normal Java iterators, but are augmented to support
- additional capabilities. Iterators are described in the CAS Reference, <olink
- targetdoc="&uima_docs_ref;"
- targetptr="ugr.ref.cas.indexes_and_iterators"/>.</para>
-
- </section>
-
- <section id="ugr.ref.jcas.class_loaders">
- <title>Class Loaders in UIMA</title>
-
- <para>The basic concept of a UIMA application includes assembling engines into a flow.
- The application made up of these Engines are run within the UIMA Framework, either by
- the Collection Processing Manager, or by using more basic UIMA Framework
- APIs.</para>
-
- <para>The UIMA Framework exists within a JVM (Java Virtual Machine). A JVM has the
- capability to load multiple applications, in a way where each one is isolated from the
- others, by using a separate class loader for each application. For instance, one set
- of UIMA Framework Classes could be shared by multiple sets of application - specific
- classes, even if these application-specific classes had the same names but were
- different versions.</para>
-
- <section id="ugr.ref.jcas.class_loaders.optional">
- <title>Use of Class Loaders is optional</title>
-
- <para>The UIMA framework will use a specific ClassLoader, based on how
- ResourceManager instances are used. Specific ClassLoaders are only created if
- you specify an ExtensionClassPath as part of the ResourceManager. If you do not
- need to support multiple applications within one UIMA framework within a JVM,
- don't specify an ExtensionClassPath; in this case, the classloader used
- will be the one used to load the UIMA framework - usually the overall application
- class loader.</para>
-
- <para>Of course, you should not run multiple UIMA applications together, in this
- way, if they have different class definitions for the same class name. This
- includes the JCas <quote>cover</quote> classes. This case might arise, for
- instance, if both applications extended
- <literal>uima.tcas.DocumentAnnotation</literal> in differing,
- incompatible ways. Each application would need its own definition of this class,
- but only one could be loaded (unless you specify ExtensionClassPath in the
- ResourceManager which will cause the UIMA application to load its private
- versions of its classes, from its classpath).</para>
- </section>
- </section>
-
- <section id="ugr.ref.jcas.accessing_jcas_objects_outside_uima_components">
- <title>Issues accessing JCas objects outside of UIMA Engine Components</title>
-
- <para>If you are using the ExtensionClassPaths, the JCas cover classes are loaded
- under a class loader created by the ResourceManager part of the UIMA Framework.
- If you reference the same JCas
- classes outside of any UIMA component, for instance, in top level application code,
- the JCas classes used by that top level application code also must be in the class path
- for the application code.</para>
-
- <para>Alternatively, you could do all the JCas processing inside a UIMA component (and do no
- processing using JCas outside of the UIMA pipeline).</para>
-
- </section>
- </section>
-
- <section id="ugr.ref.jcas.setting_up_classpath">
- <title>Setting up Classpath for JCas</title>
-
- <para>The JCas Java classes generated by JCasGen are typically compiled and put into a JAR
- file, which, in turn, is put into the application's class path.</para>
-
- <para>This JAR file must be generated from the application's merged type system.
- This is most conveniently done by opening the top level descriptor used by the
- application in the Component Descriptor Editor tool, and pressing the Run-JCasGen
- button on the Type System Definition page.</para>
-
- </section>
-
- <section id="ugr.ref.jcas.pear_support">
- <title>PEAR isolation</title>
- <para>
- As of version 2.2, the framework supports component descriptors which are PEAR descriptors.
- These descriptors define components plus include information on the class path needed to
- run them. The framework uses the class path information to set up a localized class path, just
- for code running within the PEAR context. This allows PEAR files requiring different
- versions of common code to work well together, even if the class names in the different versions
- have the same names.
- </para>
-
- <para>The mechanism used to switch the class loaders when entering a PEAR-packaged annotator in
- a flow depends on the framework knowing if JCas is being used within that annotator code. The
- framework will know this if the particular view being passed has had a previous call to
- getJCas(), or if the particular annotator is marked as a JCas-using one (by having it extend the
- class <code>JCasAnnotator_ImplBase).</code></para>
-
- </section>
-
-</chapter>
\ No newline at end of file
diff --git a/uima-docbook-references/src/docbook/ref.json.xml b/uima-docbook-references/src/docbook/ref.json.xml
deleted file mode 100644
index 3bcf68b7c..000000000
--- a/uima-docbook-references/src/docbook/ref.json.xml
+++ /dev/null
@@ -1,682 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
-<!ENTITY imgroot "images/references/ref.json/">
-<!ENTITY tp "ugr.ref.json.">
-<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >
-%uimaents;
-]>
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-<chapter id="ugr.ref.json">
- <title>JSON Serialization of CASs and UIMA Description objects</title>
- <titleabbrev>JSON support</titleabbrev>
-
- <section id="ugr.ref.json.overview">
- <title>JSON serialization support overview</title>
-
- <para>Applications are moving to the "cloud", and new applications are being rapidly developed that are hooking
- things up using various mashup techniques. New standards and conventions are emerging to support this kind
- of application development, such as REST services.
- JSON is now a popular way for services to communicate;
- its popularity is rising (in 2014) while XML is falling.</para>
-
- <para>Starting with version 2.7.0, JSON style serialization (but not (yet) deserialization)
- for CASs and UIMA descriptions is supported.
- The exact format of the serialization is configurable in several aspects.
- The implementation is built on top of the Jackson JSON generation library.
- </para>
-
- <para>The next section discusses serialization for CASes, while a later section describes serialization
- of description objects, such as type system descriptions.</para>
- </section>
-
- <section id="ug.ref.json.cas">
- <title>JSON CAS Serialization</title>
-
- <para>CASs primarily consist of collections of Feature Structures (FSs). Similar to XMI serialization, JSON
- serialization skips serializing unreachable FSs, outputting only those FSs that are found in the indexes (these are called
- <emphasis>roots</emphasis>), plus all of
- the FSs that are referenced via some chain of references, from the roots.
- </para>
-
- <para>To support the kinds of things users do with FSs,
- the serialized form may be augmented to include additional information beyond the FSs.</para>
- <para>For traditional UIMA implementations, the serialized formats mostly assumed that the receivers had access to
- a type system description, which specified details of the types of each feature value. For JSON serialization,
- some of this information can be including directly in the serialization.</para>
-
- <para>This abbreviated type system information is one kind of additional information that can be included;
- here's a summary list of the various kinds of additional information you can add to the serialization:</para>
- <itemizedlist>
- <listitem>
- <para>having a way to identify which fields in a FS should be treated as references to other FSs, or
- as representing serialized binary data from UIMA byte arrays.</para>
- </listitem>
- <listitem>
- <para>something like XML namespaces to allow the use of short type names in the serialization while handling name
- collisions</para>
- </listitem>
- <listitem>
- <para>enough of the UIMA type hierarchy to allow the common operation of iterating over a type together
- with all of its subtypes</para>
- </listitem>
- <listitem><para>A way to identify which FSs were "added-to-the-indexes" (separately, per CAS View)
- and therefore serve as roots when
- iterating over types.</para>
- </listitem>
- <listitem><para>An identification of the associated type system definition</para></listitem>
- </itemizedlist>
-
- <para>Simple JSON serialization does not have a convention for supporting these, but many extensions do.
- We borrow some of the concepts in the JSON-LD (linked data) standard in providing this
- additional information.</para>
-
- <section id="ug.ref.json.cas.bigpic">
- <title>The Big Picture</title>
-
- <para>CAS JSON serialization consists of several parts: an optional _context, the set of Feature Structures,
- and (if doing a delta serialization) information about changes to what was indexed.</para>
-
- <figure id="ug.ref.json.fig.bigpic">
- <title>The major sections of JSON serialization</title>
- <mediaobject>
- <imageobject>
- <imagedata width="3.5in" format="PNG" fileref="&imgroot;big_picture2.png"/>
- </imageobject>
- <textobject><phrase>The big picture showing the parts of serialization, with the _context optional.</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
- <para>The serializer can be configured to omit
- the _context or parts of the _context for cases where that information isn't needed. The index changes
- information is only included if Delta CAS serialization is specified. Note that Delta CAS support
- is incomplete; so this information is just for planning purposes.</para>
- </section>
-
- <section id="ug.ref.json.cas.context">
- <title>The _context section</title>
- <para>The _context section has entries for each used type as well as some special additional entries.
- Each entry for a type has multiple sub-entries, identified
- by a key-name. Each sub-entry can be selectively omitted if not needed.
-
-
- <itemizedlist>
- <listitem><para><emphasis role="bold">_type_system</emphasis> - a URI of the type system information</para></listitem>
- <listitem><para><emphasis role="bold">_types</emphasis> - information about each used type
- <itemizedlist>
- <listitem><para><emphasis role="bold">_id</emphasis> - the type's fully qualified UIMA type name</para></listitem>
- <listitem><para><emphasis role="bold">_feature_types</emphasis> - a map from features of this type to
- information about the type of the value of the feature</para></listitem>
- <listitem><para><emphasis role="bold">_subtypes</emphasis> - an array of used subtype short-names</para></listitem>
- </itemizedlist>
- </para></listitem>
- </itemizedlist>
- </para>
-
-
- <para>Here's an example:</para>
- <informalexample> <!-- does a keep-together -->
- <?dbfo keep-together="always" ?>
- <programlisting>"_context" : {
- "_type_system" : "URI to the type system information",
- "_types : {
- "A_Typical_User_or_built_in_Type" : {
- "_id" : "org.apache.uima.test.A_Typical_User_or_built_in_Type",
- "_feature_types" : [
- "sofa" : "_ref",
- "aFS" : "_ref",
- "an_array" : "_array",
- "a_byte_array" : "_byte_array"],
- "_subtypes" : [ "subtype1", "subtype2", ... ] },
- "Sofa" : {
- "_id" : "uima.cas.Sofa",
- "_feature_types" : {"sofaArray" : "_ref"} }
- }
-}</programlisting></informalexample>
-
- <para>The <emphasis role="bold">_type_system</emphasis> is an optional URI that references a UIMA type system description that
- defines the types for the CAS being serialized.</para>
-
- <para>In the <emphasis role="bold">_types</emphasis> section, the key (e.g. "Sofa" or "A_Typical_User_or_built_in_Type") is the "short" name
- for the type used in the serialization.
- It is either just
- the last segment of the full type name (e.g. for the type x.y.z.TypeName, it's TypeName), or,
- if name would collide with another type name if just the last segment
- was used (example: some.package.cname.Foo, and some.other.package.cname.Foo), then the key is made up of
- the next-to-last segment, with an optional suffixed incrementing integer in case of collisions on that name,
- a colon (:) and then the last name.</para>
-
- <blockquote><para>In this example, since the next to last segment of both names is
- "cname", one namespace name would be "cname", and the other would be "cname1". The keys in this case would be
- cname:Foo and cname1:Foo.</para></blockquote>
-
- <para>The value of the _id is the fully qualified name of the type.</para>
-
- <para>The <emphasis role="bold">_feature_types</emphasis> values of _ref, _array, and _byte_array indicate the corresponding values
- of the named features need special handling
- when deserailized.
- <itemizedlist>
- <listitem><para><emphasis role="bold">_ref</emphasis> - used when features are deserialized as numbers, but they are to be
- interpreted as references to other FSs whose <code>id</code> is the number. UIMA lists and arrays of
- FSs are marked with _ref; if the value is a JSON array, the elements of the array will be either
- numbers (to be interpreted as references), or embedded serializations of FSs.</para></listitem>
-
- <listitem><para><emphasis role="bold">_array</emphasis> - used when features are serialized as JSON
- arrays containing embedded values,
- unless the corresponding UIMA object has
- multiple references, in which case it is serialized as a FS reference which looks like a single number.
- If a feature is marked with _array, then a non-array, single number should be interpreted as the
- <code>id</code> of the feature structure that is the array or the first element of the list of items.
- This designation is used for both UIMA arrays and lists.</para>
-
- <para>This designation is for arrays and lists of primitive values, except for byte arrays.
- In the case of FS arrays and lists, the _ref designation is used instead of this to indicate that the
- resulting values in a JSON array that look like numbers should be interpreted as references.</para></listitem>
-
- <listitem><para><emphasis role="bold">_byte_array</emphasis> - _byte_array features are serialized numbers (if they are a
- reference to a separate object, or as strings (if embedded). The strings are to be decoded into
- binary byte arrays using the Base64 encoding (the standard one used by Jackson to serialize binary data).</para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- Note that single element arrays are <emphasis>not</emphasis> unwrapped, as in some other JSON serializations, to enable distinguishing
- references to arrays from embedded arrays.
- </para>
-
- <para><emphasis role="bold">_subtypes</emphasis> are a list of the type's used subtypes. A type is <emphasis>used</emphasis>
- if it is the type of a Feature Structure
- being serialized,
- or if it is in the supertype chain of some Feature Structure which is serialized. If a type has no
- used subtypes, this element is omitted.
- The names are represented as the "short" name. Users typically use this information
- to construct support for iterators over a type which includes all of its subtypes.</para>
-
-
-
- <!--
- <para>_supertypes are a list of the type's supertypes, in the natural nearest to farthest order.
- The list is truncated as soon as a type is mentioned which already (in a previous _supertypes)
- has had its supertypes enumerated.</para> -->
-
- <section id="ug.ref.json.cas.context.omit">
- <title>Omitting parts of the _context section</title>
- <para>It is possible to selectively omit some of the
- _context sections (or the entire _context), via configuration.
- Here's an example:</para>
-
- <informalexample> <!-- does a keep-together -->
-
- <programlisting>// make a new instance to hold the serialization configuration
-JsonCasSerializer jcs = new JsonCasSerializer();
-// Omit the expanded type names information
-jcs.setJsonContext(JsonContextFormat.omitExpandedTypeNames);</programlisting></informalexample>
-
- <para>See the Javadocs for <code>JsonContextFormat</code> for how to specify the parts.</para>
- </section>
-
- </section> <!-- of context -->
-
- <section id="ug.ref.json.cas.featurestructures">
- <title>Serializing Feature Structures</title>
-
- <para>Feature Structures themselves are represented as JSON objects consisting of field - value pairs, where the
- fields correspond to UIMA Features, and the values are the values of the features.
- </para>
-
- <para>The various kinds of values for a UIMA feature are represented by their natural JSON counterpart.
- UIMA primitive boolean values are represented by JSON true and false literals. UIMA Strings are
- represented as JSON strings. Numbers are represented by JSON numbers.
- Byte Arrays are represented by the Jackson standard binary encoding (base64 encoding), written as JSON strings.
- References to other Feature Structures are also represented as JSON integer numbers, the values of which are
- interpreted as ids of the referred-to
- FSs. These ids are treated in the same manner as the xmi:ids of XMI Serialization. Arrays and Lists when
- embedded (see following section) are represented as JSON arrays using the [] notation.</para>
-
- <para>Besides the feature values defined for a Feature Structure, an additional special feature
- may be serialized: _type.
- The _type is the type name, written using the short format. This is automatically included when the type cannot
- easily be
- inferred from other contextual information.
- </para>
-
- <para>Here's an example, with some comments which, since JSON doesn't support comments, are just here for explanation:</para>
- <informalexample> <!-- does a keep-together -->
- <programlisting>{ "_type" : "Annotation", // _type may be omitted
- "feat1" : true, // boolean value represented as true or false
- "feat2" : 123, // could be a number or a reference to FS with id 123
- "feat3" : "b3axgh"//could be a string or a base64 encoded byte array
-}</programlisting></informalexample>
-
-
- <section id="ug.ref.json.cas.featurestructures.embedding">
- <title>Embedding normally referenced values</title>
-
- <para>Consider a FS which has a feature that refers to another FS. This can be serialized in one of two ways:</para>
- <itemizedlist spacing="compact">
- <listitem><para>the value of the feature can be coded as an <code>id</code> (a number), where the number is the <code>id</code> of the
- referred-to FS.</para></listitem>
- <listitem><para>The value of the feature can be coded as the serialization of the referred-to FS.</para></listitem>
- </itemizedlist>
-
- <para>
- This second way of encoding is often done by JSON style serializations, and is called "embedding". Referred-to
- FSs may be embedded if there are no other references to the embedded FS. Multiple references may arise due to
- having a FS referenced as a "root" in some CAS View, or being used as a value in a FS feature.</para>
-
- <para>Following the XMI conventions, UIMA arrays and lists which are
- identified as singly referenced by either the static or dynamic method (see below) are embedded
- directly as the value of a feature. In this case, the JSON serialization writes out the value of the feature
- as a JSON array. Otherwise, the value is written out as a FS reference, and a separate serialization occurs of
- the list elements or the array.</para>
-
- <para>In addition to arrays and lists, FSs which are identifed as singly referenced from another FS are
- serialized as the embedded value of the referring feature.
- This is also done (when using the dynamic method) for singly referenced rooted instances.
- </para>
- <para>
- If a FS is multiply referenced, the serialization in these
- cases is just the numeric value of the <code>id</code> of the FS.</para>
- </section>
-
- <section id="ug.ref.json.cas.featurestructures.dynamicstatic">
- <title>Dynamic vs Static multiple-references and embedding</title>
-
- <para>There are two methods of determining if a particular FS or list or array can be embedded.
-
- <itemizedlist>
- <listitem><para><emphasis role="bold">dynamic</emphasis> - calculates at serilization time whether or not there
- are multiple references to a given FS.</para></listitem>
- <listitem><para><emphasis role="bold">static</emphasis> - looks in the type system definition to see if
- the feature is marked with <multipleReferencesAllowed>.
- <itemizedlist spacing="compact">
- <listitem><para><code>multipleReferencesAllowed</code> false → use the embedded style</para></listitem>
- <listitem><para><code>multipleReferencesAllowed</code> true → use separate objects</para></listitem>
- </itemizedlist>
- Note that since this flag is not available for
- references to FSs from View indexes, any FS that is indexed in any view is considered (if using static mode)
- to be multipleReferencesAllowed.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>Delta serialization only supports the static method; this mode is forced on if delta serialization
- is specified.</para>
-
- <para>Dynamic embedding is enabled by default for JSON, but may be disabled via configuration.</para>
- </section>
-
- <section id="ug.ref.json.cas.featurestructures.embeddedArraysLists">
- <title>Embedded Arrays and Lists</title>
-
- <para>When static embedding is being used, a case can arise where some feature is marked to have only
- singly referenced FS values, but that value may actually be multiply referenced. This is detected during
- serialization, and an message is issued if an error handler has been specified to the serializer.
- The serialization continues, however. In the case of an Array, the value of the array is embedded
- in the serialization and the fact that these were referring to the same object is lost.
- In the case of a list, if any element in the list
- has multiple references (for example, if the list has back-references, loops, etc.),
- the serialization of the list is truncated at the point where the multiple reference
- occurs.</para>
-
- <blockquote><para>Note that you can correctly serialize arbitrarily linked complex list structures created
- using the built-in list types only if you use dynamic embedding, or
- specify <code>multipleReferencesAllowed</code> = true.</para></blockquote>
-
-
- <para>Embedded list or array values are both serialized using the JSON array notation; as a result, these
- alternative representations are not distinguised in the JSON serialization.</para>
- </section> <!-- end of embedded Arraylists-->
-
- <section id="ug.ref.json.cas.featurestructures.null">
- <title>Omitting null values</title>
-
- <para>Following the conventions established in XMI serialization, features with <code>null</code> values have their
- key-value pairs omitted from the FS serialization when the type of the feature value is:
- </para>
- <itemizedlist spacing="compact">
- <listitem>
- <para>a Feature Structure Reference</para>
- </listitem>
- <listitem>
- <para>a String ( whose value is <code>null</code>, not "" (a 0-length String))</para>
- </listitem>
- <listitem>
- <para>an embedded Array or List (where the entire array and/or list is <code>null</code>)</para>
- </listitem>
- </itemizedlist>
-
- <note><para>Inside arrays or lists of FSs, references which are being serialized
- as references have a <code>null</code> reference coded as the number 0; references which are embedded are serialized as
- <code>null</code>.</para></note>
-
- <para>Configuring the serializer with <code>setOmit0Values(true)</code> causes
- additional primitive features (byte/short/int/long/float/double) to be omitted, when their values are 0 or 0.0</para>
-
- </section>
-
- </section>
-
- </section>
-
- <section id="ug.ref.json.cas.featurestructures.organization">
- <title>Organizing the Feature Structures</title>
-
- <para>The set of all FSs being serialized is divided into two parts. The first part represents
- all FSs that are root FSs, in that they were in one or more indexes at the time of serialization. The second part
- represents feature structures that are multiply referenced, or are referenced via a chain of references from the
- root FSs. The same feature structure can appear in both lists. The elements in the second part are actual
- serialized FSs, whereas, the elements in the first part are either references to the corresponding FSs in the
- second part, if they exist, or the actual embedded serialized FSs. Actual embedded serialized FSs only
- exist once in the two parts.</para>
-
- <informalexample> <!-- does a keep-together -->
- <programlisting>"_views" : {
- "_InitialView" : {
- "theFirstType" : [ { ... fs1 ...}, 123, 456, { ... fsn ...} ]
- "anotherType" : [ { ... fs1 ...}, ... { ... fsn ...} ]
- ... // more types which have roots in view "12"
- },
- "AnotherView" : {
- "theFirstType" : [ { ... fsv1 ...}, 123, { ... fsvn ...} ]
- "anotherType" : [ { ... fsv1 ...}, ... { ... fsvn ...} ]
- ... // more types which have roots in view "25"
- },
- ... // more views
-},
-
-"_referenced_fss" : {
- "12" : {"_type" : "Sofa", "sofaNum" : 1, "sofaID" : "_InitialView" },
- "25" : {"_type" : "Sofa", "sofaNum" : 2, "sofaID" : "AnotherView" },
-
- "123" : { ... fs-123 ... },
- "456" : { ... fs-456 ... },
- ...
-}</programlisting></informalexample>
-
- <para>The first part map is made up of multiple maps, one for each separate CAS View.
- The outer map is keyed by the <code>id</code> of the corresponding SofaFS (or 0, if there is no corresponding SofaFS).
- For each view, the value is a map whose key is a used Type, and the values are an array of instances
- of FSs of that type which were found in some index; these are the "root" FSs. Only root instances
- of a particular type are included in this array.
- </para>
-
-
- <para>The second part map has keys which are the <code>id</code> value of the FSs, and values which are
- a map of key-value pairs corresponding to the feature-values of that FS.
- In this case, the _type extra feature is added to record the type.</para>
-
- <!--
- <para>
- FSs can be referenced either from being the value of some Feature in an FS, or
- by being in one or more indexes at the time of serialization.
- If there are more than 1 of these kinds of references, then the FS is
- multiply referenced. All FSs that are multiply referenced are not "embedded" at their reference points;
- instead each reference point has a value which is the <code>id</code> of that FS, and which can be used as the "key"
- in the _referenced_fss map to obtain the actual serialized form of the FS.</para>
- -->
-
- <para>The _views map, keyed by view and type name, has all the FSs (as an JSON array) for that type that were in
- one or more indexes in any View. If a FS in this array is not multiply referenced (using dynamic mode),
- then it is embedded here. Otherwise, only the reference (a simple number representing the <code>id</code> of that FS) is serialized for that FS.</para>
-
- <!--
- <para>Here's a picture of what the _types map would look like with two views, with Sofa ids of 22 and 99.</para>
-
- <figure>
- <title>Feature Structure Organization</title>
- <mediaobject>
- <imageobject>
- <imagedata width="2.5in" format="PNG" fileref="&imgroot;multi.view.png"/>
- </imageobject>
- <textobject><phrase>Multi-view serialized Feature Structures</phrase></textobject>
- </mediaobject>
- </figure>
- -->
-
- </section> <!-- of representing the collection of FSs -->
-
- <!--
- <section id="ug.ref.json.cas.casviews">
- <title>CAS Views</title>
- <para>The last section in a JSON CAS serialization is the _cas_views.
- This contains for each view, an array of IDs of FSs that the serializing application added to its indexes.
- These arrays are stored in a map, with the key being the <code>id</code> for the Sofa FS associated with the view, or
- "0" for the edge case where no Sofa has (yet) been created for the initial view (this is an edge case that
- normally will not occur). For
- delta-cas serialization (where only changes are being serialized), this array is replaced with a map
- of 3 keys: "added-members", "deleted-members", and "reindexed-members",
- the values of which are arrays of IDs of FSs which were added, removed, or reindexed by the application
- doing the serializing.</para>
-
- <para>In some cases, the receiving application may only want to index FSs
- that the serializing application had indexed, but otherwise, this information is not of much use
- to that application, as that application would likely have its own indexing needs. .</para>
-
- </section> <!- - end of cas views - ->
- -->
- <!--
- <section id="ug.ref.json.cas.xmidiff">
- <title>Differences with XMI serialization</title>
-
- <para>JSON serialization shares the same implementation core with XMI serialization,
- except of course for serializing in JSON formats vs XMI/XML formats.
- One area where it differs is in the treatment of so-called out-of-type-system data.</para>
-
- <para>XMI deserialization can be specified with a "lenient" flag, which allows the incoming data to
- include types and features which are not present in the type system being deserialized into. These
- data are called "out-of-type-system" data (oots). The XMI serialization merges the oots data back into the
- the output serialization (if not doing a delta-cas serialization), thus preserving types and features in the
- serialization it doesn't have definitions for.</para>
-
- <para>
- JSON serialization doesn't support this, mainly because there's no type information available for the
- oots data, and the JSON _context information for these types can't be generated.</para>
- -->
-
-
-
- <section id="ug.ref.json.cas.features">
- <title>Additional JSON CAS Serialization features</title>
-
- <para>JSON serialization also supports several additional features, including:</para>
- <itemizedlist>
- <!--
- <listitem>
- <para>)Delta CAS: only serializes changes since the mark was set</para>
- </listitem>
- -->
- <listitem>
- <para>Type and feature filtering: only types and features that exist in a specified type system description
- are serialized.</para>
- </listitem>
- <listitem>
- <para>An ErrorHandler; this will be called in various error situations, including when
- serializing in static mode an array or list value for a feature marked <code>multipleReferencesAllowed = false</code>
- is found to have multiple references.</para>
- </listitem>
- <listitem>
- <para>A switch to control omitting of numeric features that have 0 values (default is to include these).
- See the <code>setOmit0Values(true_or_false)</code> method in JsonCasSerializer.</para>
- </listitem>
- <listitem>
- <para>a pretty printing flag (default is not to do pretty-printing)</para>
- </listitem>
- </itemizedlist>
- <para>See the Javadocs for JsonCasSerializer for details.</para>
-
- <section id="ugr.ref.json.delta">
- <title>Delta CAS</title>
-
- <note><para>Delta CAS support is incomplete, and is not supported as of release 2.7.0, but may
- be supported in later releases. The information here is just for planning purposes.</para></note>
-
- <para><emphasis role="bold">_delta_cas</emphasis> is present only when a delta CAS serialization is being performed.
- This serializes just the
- changes in the CAS since a Mark was set; so for cases where a large CAS is deserialized into a service, which
- then does a relatively small amount of additions and modifications, only those changes are serialized.
- The values of the keys are arrays of the ids of FSs that were added to the indexes,
- removed from the indexes, or reindexed.</para>
-
- <para>This mode requires the static embeddability mode. When specified, a <code>_delta_cas</code> key-value
- is added to the serialization at the end,
- which lists the FSs (by <code>id</code>) that were added, removed, or reindexed, since the mark was set.
- Additional extra information, created when the CAS was previously deserialized and the mark set,
- must be passed to the serializer, in the form of an instance of <code>XmiSerializationSharedData</code>,
- or JsonSerializationSharedData (not yet defined as of release 2.7.0).</para>
-
- <para>Here's what the last part of the serialization looks like, when Delta CAS is specified:
- <informalexample> <!-- does a keep-together -->
- <programlisting>"_delta_cas" : {
- "added_members" : [ 123, ... ],
- "deleted_members" : [ 456, ... ],
- "reindexed_members" : [] }</programlisting></informalexample>
- </para>
-
-
- </section>
- </section>
-
-
- <section id="ugr.ref.json.usage">
- <title>Using JSON CAS serialization</title>
-
- <para>The support is built on top the Jackson JSON serialization
- package. We follow Jackson conventions for configuring.</para>
-
- <para>The serialization APIs are in the JsonCasSerializer class.</para>
-
- <para>Although there are some static short-cut methods for common use cases, the basic operations needed
- to serialize a CAS as JSON are:</para>
-
- <itemizedlist>
- <listitem>
- <para>Make an instance of the <code>JsonCasSerializer</code> class. This will serve to collect configuration information.</para>
- </listitem>
- <listitem>
- <para>Do any additional configuration needed. See the Javadocs for details.
- The following objects can be configured:</para>
- <itemizedlist>
- <listitem>
- <para>The <code>JsonCasSerializer</code> object: here you can specify the kind of JSON formatting, what to serialize,
- whether or not delta serialization is wanted, prettyprinting, and more.</para>
- </listitem>
- <listitem>
- <para>The underlying <code>JsonFactory</code> object from Jackson. Normally, you won't need to configure this.
- If you do, you can create your own instance of this object and configure it and use it in the
- serialization.</para>
- </listitem>
- <listitem>
- <para>The underlying <code>JsonGenerator</code> from Jackson. Normally, you won't need to configure this.
- If you do, you can get the instance the serializer will be using and configure that.</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>Once all the configuration is done, the serialize(...) call is done in this class,
- which will create a one-time-use
- inner class where the actual serialization is done. The serialize(...) method is thread-safe, in that the same
- JsonCasSerializer instance (after it has been configured) can kick off multiple
- (identically configured) serializations
- on different threads at the same time.</para>
- <para>The serialize call follows the Jackson conventions, taking one of 3 specifications of where to serialize to:
- a Writer, an OutputStream, or a File.</para>
- </listitem>
- </itemizedlist>
-
- <para>Here's an example:</para>
- <informalexample> <!-- does a keep-together -->
- <programlisting>JsonCasSerializer jcs = new JsonCasSerializer();
-jcs.setPrettyPrint(true); // do some configuration
-StringWriter sw = new StringWriter();
-jcs.serialize(cas, sw); // serialize into sw</programlisting></informalexample>
-
- <para>The JsonCasSerializer class also has some static convenience methods for JSON serialization, for the
- most common configuration cases; please see the Javadocs for details. These are named jsonSerialize, to
- distinguish them from the non-static serialize methods.</para>
-
- <para>Many of the common configuration methods generally return the instance, so they can be chained together.
- For example, if <code>jcs</code> is an instance of the JsonCasSerializer, you can write
- <code>jcs.setPrettyPrint(true).setOmit0values(true);</code> to configure both of these.</para>
-
- <!-- of configuring -->
-
- </section> <!-- of JSON Cas Serialization -->
-
- <section id="ugr.ref.json.descriptionserialization">
- <title>JSON serialization for UIMA descriptors</title>
-
- <para>UIMA descriptors are things like analysis engine descriptors, type system descriptors, etc.
- UIMA has an internal form for these, typically named UIMA <emphasis>description</emphasis>s;
- these can be serialized out as XML using a <code>toXML</code> method.
- JSON support adds the ability to serialize these a JSON objects, as well. It may be of use, for example,
- to have the full type system description for a UIMA pipeline available in JSON notation.
- </para>
-
- <para>The class JsonMetaDataSerializer defines a set of static methods that serialize UIMA description objects
- using a toJson method that takes as an argument the description object to be serialized, and the standard
- set of serialiization targets that Jackson supports (File, Writer, or OutputStream). There is also
- an optional prettyprint flag (default is no prettyprinting).</para>
-
- <para>The resulting JSON serialization is just a straight-forward serialization of the description object,
- having the same fields as the XML serialization of it.</para>
-
- <para>Here's what a small TypeSystem description looks like, serialized:</para>
-
- <informalexample> <!-- does a keep-together -->
- <programlisting>{"typeSystemDescription" :
- {"name" : "casTestCaseTypesystem",
- "description" : "Type system description for CAS test cases.",
- "version" : "1.0",
- "vendor" : "Apache Software Foundation",
- "types" : [
- {"typeDescription" :
- {"name" : "Token",
- "description" : "",
- "supertypeName" : "uima.tcas.Annotation",
- "features" : [
- {"featureDescription" :
- {"name" : "type",
- "description" : "",
- "rangeTypeName" :
- "TokenType" } },
- {"featureDescription" :
- {"name" : "tokenFloatFeat",
- "description" : "",
- "rangeTypeName" : "uima.cas.Float" } } ] } },
- {"typeDescription" :
- {"name" : "TokenType",
- "description" : "",
- "supertypeName" : "uima.cas.TOP" } } ] } }</programlisting></informalexample>
-
- <para>Here's a sample of code to serialize a UIMA description object held in the variable <code>tsd</code>, with
- and without pretty printing:</para>
-
-
- <informalexample> <!-- does a keep-together -->
- <programlisting>StringWriter sw = new StringWriter();
-JsonMetaDataSerializer.toJSON(tsd, sw); // no prettyprinting
-
-sw = new StringWriter();
-JsonMetaDataSerializer.toJSON(tsd, sw, true); // prettyprinting</programlisting></informalexample>
- </section>
-
-</chapter>
\ No newline at end of file
diff --git a/uima-docbook-references/src/docbook/ref.pear.xml b/uima-docbook-references/src/docbook/ref.pear.xml
deleted file mode 100644
index 47fb02d3b..000000000
--- a/uima-docbook-references/src/docbook/ref.pear.xml
+++ /dev/null
@@ -1,1016 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
-<!ENTITY imgroot "images/references/ref.pear/" >
-<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >
-%uimaents;
-]>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
--->
-<chapter id="ugr.ref.pear">
- <title>PEAR Reference</title>
-
- <para>
- A PEAR (Processing Engine ARchive) file is a standard package
- for UIMA components. This chapter describes the PEAR 1.0 structure and
- specification.
- </para>
-
- <para>
- The PEAR package can be used for distribution and reuse by other
- components or applications. It also allows applications and
- tools to manage UIMA components automatically for verification,
- deployment, invocation, testing, etc.
- </para>
-
- <para>
- Currently, there is an Eclipse plugin and a command line tool
- available to create PEAR packages for standard UIMA components.
- Please refer to
- <olink targetdoc="&uima_docs_tools;"/>
- <olink targetdoc="&uima_docs_tools;"
- targetptr="ugr.tools.pear.packager" />
- for more information about these tools.
- </para>
-
- <para>
- PEARs distributed to new targets can be installed at those targets.
- UIMA includes a tool for installing PEARs; see
- <olink targetdoc="&uima_docs_tools;"/>
- <olink targetdoc="&uima_docs_tools;"
- targetptr="ugr.tools.pear.installer"/> for
- more information about installing PEARs.
- </para>
-
- <para>
- An installed PEAR can be used as a component within a UIMA pipeline,
- by specifying the pear descriptor that is created when
- installing the pear. See
- <olink targetdoc="&uima_docs_ref;"
- targetptr="ugr.ref.pear.specifier"/>.
- </para>
-
- <section id="ugr.ref.pear.packaging_a_component">
- <title>Packaging a UIMA component</title>
-
- <para>
- For the purpose of describing the process of creating a PEAR
- file and its internal structure, this section describes the
- steps used to package a UIMA component as a valid PEAR file.
- The PEAR packaging process consists of the following steps:
-
- <itemizedlist>
- <listitem>
- <para>
- <xref
- linkend="ugr.ref.pear.creating_pear_structure" />
- </para>
- </listitem>
-
- <listitem>
- <para>
- <xref
- linkend="ugr.ref.pear.populating_pear_structure" />
- </para>
- </listitem>
-
- <listitem>
- <para>
- <xref
- linkend="ugr.ref.pear.creating_installation_descriptor" />
- </para>
- </listitem>
-
- <listitem>
- <para>
- <xref
- linkend="ugr.ref.pear.packaging_into_1_file" />
- </para>
- </listitem>
- </itemizedlist>
- </para>
-
- <section id="ugr.ref.pear.creating_pear_structure">
- <title>Creating the PEAR structure</title>
-
- <para>
- The first step in the PEAR creation process is to create
- a PEAR structure. The PEAR structure is a structured
- tree of folders and files, including the following
- elements:
-
- <itemizedlist>
- <listitem>
- <para>
- Required Elements:
-
- <itemizedlist>
- <listitem>
- <para>
- The
- <emphasis role="bold">
- metadata
- </emphasis>
- folder which contains the PEAR
- installation descriptor and
- properties files.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The installation descriptor (
- <emphasis role="bold">
- metadata/install.xml
- </emphasis>
- )
- </para>
- </listitem>
-
- <listitem>
- <para>
- A UIMA analysis engine
- descriptor and its required
- code, delegates (if any), and
- resources
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
-
- <listitem>
- <para>
- Optional Elements:
-
- <itemizedlist>
- <listitem>
- <para>
- The desc folder to contain
- descriptor files of analysis
- engines, delegates analysis
- engines (all levels), and other
- components (Collection Readers,
- CAS Consumers, etc).
- </para>
- </listitem>
-
- <listitem>
- <para>
- The src folder to contain the
- source code
- </para>
- </listitem>
-
- <listitem>
- <para>
- The bin folder to contain
- executables, scripts, class
- files, dlls, shared libraries,
- etc.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The lib folder to contain jar
- files.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The doc folder containing
- documentation materials,
- preferably accessible through an
- index.html.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The data folder to contain data
- files (e.g. for testing).
- </para>
- </listitem>
-
- <listitem>
- <para>
- The conf folder to contain
- configuration files.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The resources folder to contain
- other resources and
- dependencies.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Other user-defined folders or
- files are allowed, but should be
- avoided.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- </itemizedlist>
- </para>
-
- <figure id="ugr.ref.pear.fig.pear_structure">
- <title>The PEAR Structure</title>
- <mediaobject>
- <imageobject>
- <imagedata width="3in" format="JPG"
- fileref="&imgroot;image002.jpg" />
- </imageobject>
- <textobject>
- <phrase>diagram of the PEAR structure</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
- </section>
- <section id="ugr.ref.pear.populating_pear_structure">
- <title>Populating the PEAR structure</title>
-
- <para>
- After creating the PEAR structure, the component's
- descriptor files, code files, resources files, and any
- other files and folders are copied into the
- corresponding folders of the PEAR structure. The
- developer should make sure that the code would work with
- this layout of files and folders, and that there are no
- broken links. Although it is strongly discouraged, the
- optional elements of the PEAR structure can be replaced
- by other user defined files and folder, if required for
- the component to work properly.
- </para>
- <note>
- <para>
- The PEAR structure must be self-contained. For
- example, this means that the component must run
- properly independently from the PEAR root folder
- location. If the developer needs to use an absolute
- path in configuration or descriptor files, then
- he/she should put these files in the
- <quote>conf</quote>
- or
- <quote>desc</quote>
- and replace the path of the PEAR root folder with
- the string
- <quote>$main_root</quote>
- . The tools that deploy and use PEAR files should
- localize the files in the
- <quote>conf</quote>
- and
- <quote>desc</quote>
- folders by replacing the string
- <quote>$main_root</quote>
- with the local absolute path of the PEAR root
- folder. The
- <quote>$main_root</quote>
- macro can also be used in the Installation
- descriptor (install.xml)
- </para>
- </note>
-
- <para>
- Currently there are three types of component packages
- depending on their deployment:
- </para>
-
- <section id="ugr.ref.pear.package_type.standard">
- <title>Standard Type</title>
-
- <para>
- A component package with the
- <emphasis role="bold">standard</emphasis>
- type must be a valid Analysis Engine, and all the
- required files to deploy it locally must be included
- in the PEAR package.
- </para>
-
- </section>
- <section id="ugr.ref.pear.package_type.service">
- <title>Service Type</title>
-
- <para>
- A component package with the
- <emphasis role="bold">service</emphasis>
- type must be deployable locally as a supported UIMA
- service (e.g. Vinci). In this case, all the required
- files to deploy it locally must be included in the
- PEAR package.
- </para>
-
- </section>
- <section id="ugr.ref.pear.package_type.network">
- <title>Network Type</title>
-
- <para>
- A component package with the network type is not
- deployed locally but rather in the
- <quote>remote</quote>
- environment. It's accessed as a network AE
- (e.g. Vinci Service). The component owner has the
- responsibility to start the service and make sure
- it's up and running before it's used by
- others (like a webmaster that makes sure the web
- site is up and running). In this case, the PEAR
- package does not have to contain files required for
- deployment, but must contain the network AE
- descriptor (see
- <olink targetdoc="&uima_docs_tutorial_guides;"
- /> <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;"
- /> <olink targetdoc="&uima_docs_tutorial_guides;"
- targetptr="ugr.tug.application.remote_services" />
- .
- </para>
-
- </section>
- </section>
-
- <section id="ugr.ref.pear.creating_installation_descriptor">
- <title>Creating the installation descriptor</title>
-
- <para>
- The installation descriptor is an xml file called
- install.xml under the metadata folder of the PEAR
- structure. It's also called InsD. The InsD XML file
- should be created in the UTF-8 file encoding. The InsD
- should contain the following sections:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <OS>: This section is used to specify
- supported operating systems
- </para>
- </listitem>
-
- <listitem>
- <para>
- <TOOLKITS>: This section is used to
- specify toolkits, such as JDK, needed by the
- component.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <SUBMITTED_COMPONENT>: This is the most
- important section in the Installation
- Descriptor. It's used to specify required
- information about the component. See
- <xref
- linkend="ugr.ref.pear.installation_descriptor" />
- for detailed information about this section.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <INSTALLATION>: This section is explained
- in section
- <xref linkend="ugr.ref.pear.installing" />
- .
- </para>
- </listitem>
- </itemizedlist>
-
- </section>
-
- <section id="ugr.ref.pear.installation_descriptor">
- <title>
- Documented template for the installation descriptor:
- </title>
- <titleabbrev>Installation Descriptor: template</titleabbrev>
-
- <para>
- The following is a sample
- <quote>documented template</quote>
- which describes content of the installation descriptor
- install.xml:
- </para>
-
-
- <programlisting><![CDATA[<? xml version="1.0" encoding="UTF-8"?>
-<!-- Installation Descriptor Template -->
-<COMPONENT_INSTALLATION_DESCRIPTOR>
- <!-- Specifications of OS names, including version, etc. -->
- <OS>
- <NAME>OS_Name_1</NAME>
- <NAME>OS_Name_2</NAME>
- </OS>
- <!-- Specifications of required standard toolkits -->
- <TOOLKITS>
- <JDK_VERSION>JDK_Version</JDK_VERSION>
- </TOOLKITS>
-
- <!-- There are 2 types of variables that are used in the InsD:
- a) $main_root , which will be substituted with the real path to the
- main component root directory after installing the
- main (submitted) component
- b) $component_id$root, which will be substituted with the real path
- to the root directory of a given delegate component after
- installing the given delegate component -->
-
- <!-- Specification of submitted component (AE) -->
- <!-- Note: submitted_component_id is assigned by developer; -->
- <!-- XML descriptor file name is set by developer. -->
- <!-- Important: ID element should be the first in the -->
- <!-- SUBMITTED_COMPONENT section. -->
- <!-- Submitted component may include optional specification -->
- <!-- of Collection Reader that can be used for testing the -->
- <!-- submitted component. -->
- <!-- Submitted component may include optional specification -->
- <!-- of CAS Consumer that can be used for testing the -->
- <!-- submitted component. -->
-
- <SUBMITTED_COMPONENT>
- <ID>submitted_component_id</ID>
- <NAME>Submitted component name</NAME>
- <DESC>$main_root/desc/ComponentDescriptor.xml</DESC>
-
- <!-- deployment options: -->
- <!-- a) "standard" is deploying AE locally -->
- <!-- b) "service" is deploying AE locally as a service, -->
- <!-- using specified command (script) -->
- <!-- c) "network" is deploying a pure network AE, which -->
- <!-- is running somewhere on the network -->
-
- <DEPLOYMENT>standard | service | network</DEPLOYMENT>
-
- <!-- Specifications for "service" deployment option only -->
- <SERVICE_COMMAND>$main_root/bin/startService.bat</SERVICE_COMMAND>
- <SERVICE_WORKING_DIR>$main_root</SERVICE_WORKING_DIR>
- <SERVICE_COMMAND_ARGS>
-
- <ARGUMENT>
- <VALUE>1st_parameter_value</VALUE>
- <COMMENTS>1st parameter description</COMMENTS>
- </ARGUMENT>
-
- <ARGUMENT>
- <VALUE>2nd_parameter_value</VALUE>
- <COMMENTS>2nd parameter description</COMMENTS>
- </ARGUMENT>
-
- </SERVICE_COMMAND_ARGS>
-
- <!-- Specifications for "network" deployment option only -->
-
- <NETWORK_PARAMETERS>
- <VNS_SPECS VNS_HOST="vns_host_IP" VNS_PORT="vns_port_No" />
- </NETWORK_PARAMETERS>
-
- <!-- General specifications -->
-
- <COMMENTS>Main component description</COMMENTS>
-
- <COLLECTION_READER>
- <COLLECTION_ITERATOR_DESC>
- $main_root/desc/CollIterDescriptor.xml
- </COLLECTION_ITERATOR_DESC>
-
- <CAS_INITIALIZER_DESC>
- $main_root/desc/CASInitializerDescriptor.xml
- </CAS_INITIALIZER_DESC>
- </COLLECTION_READER>
-
- <CAS_CONSUMER>
- <DESC>$main_root/desc/CASConsumerDescriptor.xml</DESC>
- </CAS_CONSUMER>
-
- </SUBMITTED_COMPONENT>
- <!-- Specifications of the component installation process -->
- <INSTALLATION>
- <!-- List of delegate components that should be installed together -->
- <!-- with the main submitted component (for aggregate components) -->
- <!-- Important: ID element should be the first in each -->
-
- <!-- DELEGATE_COMPONENT section. -->
- <DELEGATE_COMPONENT>
- <ID>first_delegate_component_id</ID>
- <NAME>Name of first required separate component</NAME>
- </DELEGATE_COMPONENT>
-
- <DELEGATE_COMPONENT>
- <ID>second_delegate_component_id</ID>
- <NAME>Name of second required separate component</NAME>
- </DELEGATE_COMPONENT>
-
- <!-- Specifications of local path names that should be replaced -->
- <!-- with real path names after the main component as well as -->
- <!-- all required delegate (library) components are installed. -->
- <!-- <FILE> and <REPLACE_WITH> values may use the $main_root or -->
- <!-- one of the $component_id$root variables. -->
- <!-- Important: ACTION element should be the first in each -->
- <!-- PROCESS section. -->
-
- <PROCESS>
- <ACTION>find_and_replace_path</ACTION>
- <PARAMETERS>
- <FILE>$main_root/desc/ComponentDescriptor.xml</FILE>
- <FIND_STRING>../resources/dict/</FIND_STRING>
- <REPLACE_WITH>$main_root/resources/dict/</REPLACE_WITH>
- <COMMENTS>Specify actual dictionary location in XML component
- descriptor
- </COMMENTS>
- </PARAMETERS>
- </PROCESS>
-
- <PROCESS>
- <ACTION>find_and_replace_path</ACTION>
- <PARAMETERS>
- <FILE>$main_root/desc/DelegateComponentDescriptor.xml</FILE>
- <FIND_STRING>
-local_root_directory_for_1st_delegate_component/resources/dict/
- </FIND_STRING>
- <REPLACE_WITH>
- $first_delegate_component_id$root/resources/dict/
- </REPLACE_WITH>
- <COMMENTS>
- Specify actual dictionary location in the descriptor of the 1st
- delegate component
- </COMMENTS>
- </PARAMETERS>
- </PROCESS>
-
- <!-- Specifications of environment variables that should be set prior
- to running the main component and all other reused components.
- <VAR_VALUE> values may use the $main_root or one of the
- $component_id$root variables. -->
-
- <PROCESS>
- <ACTION>set_env_variable</ACTION>
- <PARAMETERS>
- <VAR_NAME>env_variable_name</VAR_NAME>
- <VAR_VALUE>env_variable_value</VAR_VALUE>
- <COMMENTS>Set environment variable value</COMMENTS>
- </PARAMETERS>
- </PROCESS>
-
- </INSTALLATION>
-</COMPONENT_INSTALLATION_DESCRIPTOR>]]></programlisting>
-
- <section id="ugr.ref.pear.installation_descriptor.submitted_component">
- <title>The SUBMITTED_COMPONENT section</title>
-
- <para>The SUBMITTED_COMPONENT section of the installation descriptor
- (install.xml) is used to specify required information about the UIMA component.
- Before explaining the details, let's clarify the concept of component ID and
- <quote>macros</quote> used in the installation descriptor. The component ID
- element should be the <emphasis role="bold">first element </emphasis>in the
- SUBMITTED_COMPONENT section.</para>
-
- <para>The component id is a string that uniquely identifies the component. It should
- use the JAVA naming convention (e.g.
- com.company_name.project_name.etc.mycomponent).</para>
-
- <para>Macros are variables such as $main_root, used to represent a string such as the
- full path of a certain directory.</para>
-
- <para>The values of these macros are defined by the PEAR installation process, when the
- PEAR is installed, and represent the values local to that particular installation.
- The values are stored in the <literal>metadata/PEAR.properties</literal> file that is
- generated during PEAR installation.
- The tools and applications that use and deploy PEAR files replace these macros with
- the corresponding values in the local environment as part of the deployment
- process in the files included in the conf and desc folders.</para>
-
- <para>Currently, there are two types of macros:</para>
-
- <itemizedlist>
-
- <listitem><para>$main_root, which represents the local absolute
- path of the main component root directory after deployment. </para></listitem>
-
- <listitem><para>$<emphasis>component_id</emphasis>$root, which
- represents the local absolute path to the root directory of the component which
- has <emphasis>component_id </emphasis> as component ID. This component could
- be, for instance, a delegate component. </para></listitem></itemizedlist>
-
- <para>For example, if some part of a descriptor needs to have a path to the data
- subdirectory of the PEAR, you write <literal>$main_root/data</literal>. If
- your PEAR refers to a delegate component having the ID
- <quote><literal>my.comp.Dictionary</literal></quote>, and you need to
- specify a path to one of this component's subdirectories, e.g.
- <literal>resource/dict</literal>, you write
- <literal>$my.comp.Dictionary$root/resources/dict</literal>. </para>
-
- </section>
- <section id="ugr.ref.pear.installation_descriptor.id_name_desc">
- <title>The ID, NAME, and DESC tags</title>
-
- <para>These tags are used to specify the component ID, Name, and descriptor path
- using the corresponding tags as follows:
-
-
- <programlisting><![CDATA[<SUBMITTED_COMPONENT>
- <ID>submitted_component_id</ID>
- <NAME>Submitted component name</NAME>
- <DESC>$main_root/desc/ComponentDescriptor.xml</DESC>]]></programlisting></para>
-
- </section>
- <section id="ugr.ref.pear.installation_descriptor.deployment_type">
- <title>Tags related to deployment types</title>
-
- <para>As mentioned before, there are currently three types of PEAR packages,
- depending on the following deployment types</para>
- <section
- id="ugr.ref.pear.installation_descriptor.deployment_type.standard">
- <title>Standard Type</title>
-
- <para>A component package with the <emphasis role="bold">standard</emphasis>
- type must be a valid UIMA Analysis Engine, and all the required files to deploy it
- must be included in the PEAR package. This deployment type should be specified as
- follows:
-
-
- <programlisting><![CDATA[<DEPLOYMENT>standard</DEPLOYMENT>]]></programlisting></para>
- </section>
- <section
- id="ugr.ref.pear.installation_descriptor.deployment_type.service">
- <title>Service Type</title>
-
- <para>A component package with the <emphasis role="bold">service</emphasis>
- type must be deployable locally as a supported UIMA service (e.g. Vinci). The
- installation descriptor must include the path for the executable or script to
- start the service including its arguments, and the working directory from where
- to launch it, following this template:
-
-
- <programlisting><![CDATA[<DEPLOYMENT>service</DEPLOYMENT>
-<SERVICE_COMMAND>$main_root/bin/startService.bat</SERVICE_COMMAND>
-<SERVICE_WORKING_DIR>$main_root</SERVICE_WORKING_DIR>
-<SERVICE_COMMAND_ARGS>
- <ARGUMENT>
- <VALUE>1st_parameter_value</VALUE>
- <COMMENTS>1st parameter description</COMMENTS>
- </ARGUMENT>
- <ARGUMENT>
- <VALUE>2nd_parameter_value</VALUE>
- <COMMENTS>2nd parameter description</COMMENTS>
- </ARGUMENT>
-</SERVICE_COMMAND_ARGS>]]></programlisting></para>
-
- </section>
- <section
- id="ugr.ref.pear.installation_descriptor.deployment_type.network">
- <title>Network Type</title>
-
- <para>A component package with the network type is not deployed locally, but
- rather in a <quote>remote</quote> environment. It's accessed as a
- network AE (e.g. Vinci Service). In this case, the PEAR package does not have to
- contain files required for deployment, but must contain the network AE
- descriptor. The <DESC> tag in the installation descriptor (See section
- 2.3.2.1) must point to the network AE descriptor. Here is a template in the case of
- Vinci services:
-
-
- <programlisting><![CDATA[<DEPLOYMENT>network</DEPLOYMENT>
-<NETWORK_PARAMETERS>
- <VNS_SPECS VNS_HOST="vns_host_IP" VNS_PORT="vns_port_No" />
-</NETWORK_PARAMETERS>]]></programlisting></para>
- </section>
- </section>
- <section
- id="ugr.ref.pear.installation_descriptor.collection_reader_cas_consumer">
- <title>The Collection Reader and CAS Consumer tags</title>
-
- <para>These sections of the installation descriptor are used by any specific
- Collection Reader or CAS Consumer to be used with the packaged analysis
- engine.</para>
-
- </section>
- <section id="ugr.ref.pear.installation_descriptor.installation">
- <title>The INSTALLATION section</title>
-
- <para>The <INSTALLATION> section specifies the external dependencies of
- the component and the operations that should be performed during the PEAR package
- installation.</para>
-
- <para>The component dependencies are specified in the
- <DELEGATE_COMPONENT> sub-sections, as shown in the installation
- descriptor template above.</para>
-
- <para>Important: The ID element should be the first element in each
- <DELEGATE_COMPONENT> sub-section.</para>
-
- <para>The <INSTALLATION> section may specify the following operations:
-
- <itemizedlist><listitem><para>Setting environment variables that are
- required to run the installed component.
- </para>
- <para>This is also how you specify additional classpaths
- for a Java component - by specifying the setting of an environmental variable
- named CLASSPATH. The <literal>buildComponentClasspath</literal> method
- of the PackageBrowser class builds a classpath string from what it finds in
- the CLASSPATH specification here, plus adds a classpath entry for all
- Jars in the <literal>lib</literal> directory. Because of this, there is no need
- to specify Class Path entries for Jars in the lib directory, when using
- the Eclipse plugin pear packager or the Maven Pear Packager.</para>
-
- <blockquote><para>When specifying the value of the CLASSPATH environment
- variable, use the semicolon ";" as the separator character, regardless of the
- target Operating System conventions. This delimiter will be replaced with
- the right one for the Operating System during PEAR installation.</para>
- </blockquote>
-
- <para>If your component needs to set the UIMA datapath you must specify the necessary
- datapath setting using an environment variable with the key <literal>uima.datapath</literal>.
- When such a key is specified the <literal>getComponentDataPath</literal> method of the
- PackageBrowser class will return the specified datapath settings for your component.
- </para>
-
- <warning><para>Do not put UIMA Framework Jars into the lib directory of your
- PEAR; doing so will cause system failures due to class loading issues.</para></warning>
- </listitem>
- <listitem><para>Note that you can use <quote>macros</quote>, like
- $main_root or $component_id$root in the VAR_VALUE element of the
- <PARAMETERS> sub-section.</para></listitem>
-
- <listitem><para>Finding and replacing string expressions in files.</para>
- </listitem>
-
- <listitem><para>Note that you can use the <quote>macros</quote> in the FILE
- and REPLACE_WITH elements of the <PARAMETERS> sub-section. </para>
- </listitem></itemizedlist></para>
-
- <para>Important: the ACTION element always should be the 1st element in each
- <PROCESS> sub-section.</para>
-
- <para>By default, the PEAR Installer will try to process every file in the desc and
- conf directories of the PEAR package in order to find the <quote>macros</quote>
- and replace them with actual path expressions. In addition to this, the installer
- will process the files specified in the
- <INSTALLATION> section.</para>
-
- <para>Important: all XML files which are going to be processed should be created
- using UTF-8 or UTF-16 file encoding. All other text files which are going to be
- processed should be created using the ASCII file encoding.</para>
- </section>
- </section>
-
- <section id="ugr.ref.pear.packaging_into_1_file">
- <title>Packaging the PEAR structure into one file</title>
-
- <para>The last step of the PEAR process is to simply <emphasis role="bold">
- zip</emphasis> the content of the PEAR root folder (<emphasis role="bold">not
- including the root folder itself</emphasis>) to a PEAR file with the extension <quote>.pear</quote>.</para>
-
- <para>To do this you can either use the PEAR packaging tools that are described in <quote><olink targetdoc="&uima_docs_tools;"
- /> <olink targetdoc="&uima_docs_tools;"
- targetptr="ugr.tools.pear.packager"/></quote> or you can use the PEAR packaging API that is shown below.</para>
-
- <para>
- To use the PEAR packaging API you first have to create the necessary information for the PEAR package:
- <programlisting> //define PEAR data
- String componentID = "AnnotComponentID";
- String mainComponentDesc = "desc/mainComponentDescriptor.xml";
- String classpath ="$main_root/bin;";
- String datapath ="$main_root/resources;";
- String mainComponentRoot = "/home/user/develop/myAnnot";
- String targetDir = "/home/user/develop";
- Properties annotatorProperties = new Properties();
- annotatorProperties.setProperty("sysProperty1", "value1");</programlisting>
-
- To create a complete PEAR package in one step call:
- <programlisting>PackageCreator.generatePearPackage(
- componentID, mainComponentDesc, classpath, datapath,
- mainComponentRoot, targetDir, annotatorProperties);</programlisting>
- The created PEAR package has the file name <componentID>.pear and is located in the <targetDir>.
- </para>
- <para>
- To create just the PEAR installation descriptor in the main component root directory call:
- <programlisting>PackageCreator.createInstallDescriptor(componentID, mainComponentDesc,
- classpath, datapath, mainComponentRoot, annotatorProperties);</programlisting>
-
- To package a PEAR file with an existing installation descriptor call:
- <programlisting>PackageCreator.createPearPackage(componentID, mainComponentRoot,
- targetDir);</programlisting>
- The created PEAR package has the file name <componentID>.pear and is located in the <targetDir>.
- </para>
-
- </section>
- </section>
- <section id="ugr.ref.pear.installing">
- <title>Installing a PEAR package</title>
-
- <para>The installation of a PEAR package can be done using
- the PEAR installer tool (see <olink targetdoc="&uima_docs_tools;"
- /> <olink targetdoc="&uima_docs_tools;"
- targetptr="ugr.tools.pear.installer"/>, or by an application using
- the PEAR APIs, directly. </para>
-
- <para>During the PEAR installation the PEAR file is extracted to the installation directory and the PEAR macros
- in the descriptors are updated with the corresponding path. At the end of the installation the PEAR verification
- is called to check if the installed PEAR package can be started successfully. The PEAR verification use the classpath,
- datapath and the system property settings of the PEAR package to verify the PEAR content. Necessary Java library
- path settings for native libararies, PATH variable settings or system environment variables cannot be recognized
- automatically and the use must take care of that manually.</para>
-
- <note><para>By default the PEAR packages are not installed directly to the specified installation directory. For each PEAR
- a subdirectory with the name of the PEAR's ID is created where the PEAR package is installed to. If the PEAR installation
- directory already exists, the old content is automatically deleted before the new content is installed.</para></note>
-
- <section id="ugr.ref.pear.installing_pear_using_API">
- <title>Installing a PEAR file using the PEAR APIs</title>
-
- <para>The example below shows how to use the PEAR APIs to install a
- PEAR package and access the installed PEAR package data. For more details about the PackageBrowser API,
- please refer to the Javadocs for the org.apache.uima.pear.tools package.
-
- <programlisting>File installDir = new File("/home/user/uimaApp/installedPears");
-File pearFile = new File("/home/user/uimaApp/testpear.pear");
-boolean doVerification = true;
-
-try {
- // install PEAR package
- PackageBrowser instPear = PackageInstaller.installPackage(
- installDir, pearFile, doVerification);
-
- // retrieve installed PEAR data
- // PEAR package classpath
- String classpath = instPear.buildComponentClassPath();
- // PEAR package datapath
- String datapath = instPear.getComponentDataPath();
- // PEAR package main component descriptor
- String mainComponentDescriptor = instPear
- .getInstallationDescriptor().getMainComponentDesc();
- // PEAR package component ID
- String mainComponentID = instPear
- .getInstallationDescriptor().getMainComponentId();
- // PEAR package pear descriptor
- String pearDescPath = instPear.getComponentPearDescPath();
-
- // print out settings
- System.out.println("PEAR package class path: " + classpath);
- System.out.println("PEAR package datapath: " + datapath);
- System.out.println("PEAR package mainComponentDescriptor: "
- + mainComponentDescriptor);
- System.out.println("PEAR package mainComponentID: "
- + mainComponentID);
- System.out.println("PEAR package specifier path: " + pearDescPath);
-
- } catch (PackageInstallerException ex) {
- // catch PackageInstallerException - PEAR installation failed
- ex.printStackTrace();
- System.out.println("PEAR installation failed");
- } catch (IOException ex) {
- ex.printStackTrace();
- System.out.println("Error retrieving installed PEAR settings");
- }</programlisting></para>
-
- <para>
- To run a PEAR package after it was installed using the PEAR API see the example below. It use the
- generated PEAR specifier that was automatically created during the PEAR installation.
- For more details about the APIs please refer to the Javadocs.
-
-
- <programlisting>File installDir = new File("/home/user/uimaApp/installedPears");
-File pearFile = new File("/home/user/uimaApp/testpear.pear");
-boolean doVerification = true;
-
-try {
-
- // Install PEAR package
- PackageBrowser instPear = PackageInstaller.installPackage(
- installDir, pearFile, doVerification);
-
- // Create a default resouce manager
- ResourceManager rsrcMgr = UIMAFramework.newDefaultResourceManager();
-
- // Create analysis engine from the installed PEAR package using
- // the created PEAR specifier
- XMLInputSource in =
- new XMLInputSource(instPear.getComponentPearDescPath());
- ResourceSpecifier specifier =
- UIMAFramework.getXMLParser().parseResourceSpecifier(in);
- AnalysisEngine ae =
- UIMAFramework.produceAnalysisEngine(specifier, rsrcMgr, null);
-
- // Create a CAS with a sample document text
- CAS cas = ae.newCAS();
- cas.setDocumentText("Sample text to process");
- cas.setDocumentLanguage("en");
-
- // Process the sample document
- ae.process(cas);
- } catch (Exception ex) {
- ex.printStackTrace();
- }</programlisting></para>
-
- </section>
-
- </section>
-
- <section id="ugr.ref.pear.specifier">
- <title>PEAR package descriptor</title>
-
- <para>
- To run an installed PEAR package directly in the UIMA framework the <literal>pearSpecifier</literal>
- XML descriptor can be used. Typically during the PEAR installation such an specifier is automatically generated
- and contains all the necessary information to run the installed PEAR package. Settings for system environment
- variables, system PATH settings or Java library path settings cannot be recognized
- automatically and must be set manually when the JVM is started.
- </para>
-
- <note><para>The PEAR may contain specifications for "environment variables" and their settings.
- When such a PEAR is run
- directly in the UIMA framework, those settings (except for Classpath and Data Path) are converted
- to Java System properties, and set to the specified values. Java cannot set true environmental variables;
- if such a setting is needed, the application would need to arrange to do this prior to invoking Java.</para>
-
- <para>The Classpath and Data Path settings are used by UIMA to configure a special Resource Manager
- that is used when code from this PEAR is being run.</para></note>
-
- <para>
- The generated PEAR descriptor
- is located in the component root directory of the installed PEAR package and has a filename like
- <componentID>_pear.xml.
- </para>
- <para>
- The PEAR package descriptor looks like:
- </para>
- <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<pearSpecifier xmlns="http://uima.apache.org/resourceSpecifier">
- <pearPath>/home/user/uimaApp/installedPears/testpear</pearPath>
- <pearParameters> <!-- optional -->
- <nameValuePair> <!-- any number, repeated -->
- <name>param1</name>
- <value><string>stringVal1</string></value>
- </nameValuePair>
- </pearParameters>
- <parameters> <!-- optional legacy string-valued parameters -->
- <parameter> <!-- any number, repeated -->
- <name>name-of-the-parameter</name>
- <value>string-value</value>
- </parameter>
- </parameters>
-</pearSpecifier>]]></programlisting>
- <para>
- The <literal>pearPath</literal> setting in the descriptor must point to the component root directory
- of the installed PEAR package.
- </para>
- <note>
- <!--para> should now be possible (11/2008)
- When a PEAR descriptor is used within an aggregate AE as primitive AE, it is not possible to
- override the PEAR AE configuration parameter settings with the aggregate AE descriptor.
- </para-->
- <para>
- It is not possible to share resources between PEAR Analysis Engines that are instantiated using the PEAR
- descriptor. The PEAR runtime created for each PEAR descriptor has its own specific ResourceManager
- (unless exactly the same Classpath and Data Path are being used).
- </para>
- </note>
-
- <para>The optional <literal>pearParameters</literal> section, if used, specifies parameter values,
- which are used to customize / override parameter values in the PEAR descriptor. The format
- for parameter values used here is the same as in component parameters (see
- <olink targetdoc="&uima_docs_ref;" targetptr="ugr.ref.aes.configuration_parameter_settings"/>).
- External Settings overrides continue to work for PEAR descriptors, and have precedence, if specified.
- </para>
-
- <para>Additionally, there can be a <literal>parameters</literal> section. This section supports
- only string-valued parameters. Up to Apache UIMA version 2.10.4, this was the only way of
- providing PEAR parameters. Starting with Apache UIMA version 2.10.4, this way of specifying
- parameters is deprecated and should no longer be used. Support for will eventually be removed
- in a future version of Apache UIMA. Parameters set in the <literal>pearParameters</literal> have
- precedence over parameters defined in <literal>parameters</literal> section. For the time being,
- both sections can be present simultaneously in a PEAR specifier.
- </para>
-
- </section>
-
-</chapter>
\ No newline at end of file
diff --git a/uima-docbook-references/src/docbook/ref.resources.xml b/uima-docbook-references/src/docbook/ref.resources.xml
deleted file mode 100644
index b845ad3cd..000000000
--- a/uima-docbook-references/src/docbook/ref.resources.xml
+++ /dev/null
@@ -1,186 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
-<!ENTITY imgroot "images/references/ref.resources/">
-<!ENTITY tp "ugr.ref.resources.">
-<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >
-%uimaents;
-]>
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-<chapter id="ugr.ref.resources">
- <title>UIMA Resources</title>
- <titleabbrev>UIMA Resources</titleabbrev>
-
- <section id="ugr.ref.resources.overview">
- <title>What is a UIMA Resource?</title>
- <para>UIMA uses the term <code>Resource</code> to describe all UIMA components
- that can be acquired by an application or by other resources.</para>
-
- <figure id="ref.resource.fig.kinds">
- <title>Resource Kinds</title>
- <mediaobject>
- <imageobject>
- <imagedata width="3in" format="PNG" fileref="&imgroot;res_resource_kinds.png"/>
- </imageobject>
- <textobject><phrase>Resource Kinds, a partial list</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
- <para>There are many kinds of resources; here's a list of the main kinds:
- <variablelist>
-
- <varlistentry>
- <term><emphasis role="strong">Annotator</emphasis></term>
- <listitem><para>a user written component, receives a CAS, does some processing, and returns the possibly
- updated CAS. Variants include CollectionReaders, CAS Consumers, CAS Multipliers.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="strong">Flow Controller</emphasis></term>
- <listitem><para>a user written component controlling the flow of CASes within an aggregate.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="strong">External Resource</emphasis></term>
- <listitem><para>a user written component. Variants include:
- <itemizedlist spacing="compact">
- <listitem><para>Data - includes special lifecycle call to load data</para></listitem>
- <listitem><para>Parameterized - allows multiple instantiations with simple string parameter variants;
- example: a dictionary, that has variants in content for different languages</para></listitem>
- <listitem><para>Configurable - supports configuration from the XML specifier</para></listitem>
- </itemizedlist>
- </para></listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- <section id="ugr.ref.resources.resource-inner-implementations">
- <title>Resource Inner Implementations</title>
-
- <para>Many of the resource kinds include in their specification a (possibly optional) element, which is
- the name of a Java class which implements the resource. We will call this class the "inner implementation".</para>
-
- <para>The UIMA framework creates instances of Resource from resource specifiers, by calling
- the framework's <code>produceResource(specifier, additional_parameters)</code> method.
- This call produces a instance of Resource. </para>
-
- <blockquote>
- <para>
- For example, calling produceResource on an AnalysisEngineDescription produces an instance of
- AnalysisEngine. This, in turn will have a reference to the user-written inner implementation class.
- specified by the <code>annotatorImplementationName</code>.
- </para>
- <para>External resource descriptors may include an <code>implementationName</code> element.
- Calling produceResource on a ExternalResourceDescription produces an instance of Resource;
- the resource obtained by subsequent calls to <code>getResource(...)</code>
- is dependent on the particular descriptor, and may be an instance of
- the inner implementation class.
- </para>
- </blockquote>
-
- <para>For external resources, each resource specifier kind handles the case where
- the inner implementation is omitted. If it is supplied, the named class must implement
- the interface specified in the bindings for this resource. In addition, the particular specifier kind may
- further restrict the kinds of classes the user supplies as the implementationName.
- </para>
-
- <para>Some examples of this further restriction:
- <variablelist>
- <varlistentry>
- <term><emphasis role="strong">customResource</emphasis></term>
- <listitem><para>the class must also implement the Resource interface</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="strong">dataResource</emphasis></term>
- <listitem><para>the class must also implement the SharedResourceObject interface</para></listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- </section>
-
- </section>
-
- <section id="ugr.ref.resources.sharing-across-pipelines">
- <title>Sharing Resources, even across pipelines</title>
- <titleabbrev>Sharing Resources</titleabbrev>
- <para>UIMA applications run one or more UIMA Pipelines. Each pipeline has a top-level Analysis Engine, which
- may be an aggregation of many other Analysis Engine components. The UIMA framework instantiates Annotator
- resources as specified to configure the pipelines.</para>
-
- <para>Sometimes, many identical pipelines are created (for example,
- in order to exploit multi-core hardware by processing multiple CASes in parallel). In this case, the framework
- would produce multiple instances of those Annotation resources; these are implemented as multiple instances
- of the same Java class.</para>
-
- <para>Sets of External Resources plus a CAS Pool and UIMA Extension ClassLoader are set up and kept,
- per instance of a ResourceManager;
- this instance serves to allow sharing of these items across one or more pipelines.
-
- <itemizedlist>
- <listitem>
- <para>The UIMA Extension ClassLoader (if specified) is used to find the resources to be loaded
- by the framework</para>
- </listitem>
- <listitem>
- <para>The <code>External Resources</code> are specified by a pipeline's resource configuration.</para>
- </listitem>
- <listitem>
- <para>The CAS Pool is a pool of CASs all with identical type systems and index definitions, associated
- with a pipeline.</para>
- </listitem>
- </itemizedlist> </para>
-
- <para>When setting up a pipeline, the UIMA Framework's <code>produceResource</code>
- or one of its specialized variants is called, and a new
- ResourceManager being created and used for that pipeline. However, in many cases, it may be advantageous to
- share the same Resources across multiple pipelines; this is easily doable by passing a common instance of the
- ResourceManager to the pipeline creation methods (using the additional parameters of the produceResource method).</para>
-
- <para>
- To handle additional use cases, the ResourceManager has a <code>copy()</code> method which creates a copy of the
- Resource Manager instance. The new instance is created with a null CAS Manager; if you want to share the
- the CAS Pool, you have to copy the CAS Manager: <code>newRM.setCasManager(originalRM.getCasManager())</code>.
- You also may set the Extension Class Loader in the new instance (PEAR wrappers use this to allow
- PEARs to have their own classpath). See the Javadocs for details.
- </para>
-
- </section>
-
- <section id="ugr.ref.resources.external-resource-multiple-parameterized-instances">
- <title>External Resources support for multiple Parameterized Instances</title>
- <para>A typical external resource gets a single instantiation, shared with all users of a particular
- ResourceManager.
- Sometimes, multiple instantiations may be useful (of the same resource). The framework supports this for
- ParameterizedDataResources. There's one kind supplied with UIMA - the fileLanguageResourceSpecifier.
- This works by having each call to getResource(name, extra_keys[]) use the extra keys to select a particular
- instance. On the first call for a particular instance, the named resource uses the extra keys to
- initialize a new instance by calling its <code>load</code> method with a data resource derived from the
- extra keys by the named resource.
- </para>
-
- <para>For example, the fileLanguageResourceSpecifier uses the language code and goes through
- a process with lots of defaulting and fall back to find a resource to load, based on the language code.
- </para>
-
- </section>
-
-</chapter>
\ No newline at end of file
diff --git a/uima-docbook-references/src/docbook/ref.xmi.xml b/uima-docbook-references/src/docbook/ref.xmi.xml
deleted file mode 100644
index 03e5e85b5..000000000
--- a/uima-docbook-references/src/docbook/ref.xmi.xml
+++ /dev/null
@@ -1,381 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
-<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >
-%uimaents;
-]>
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-<chapter id="ugr.ref.xmi">
- <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
- <literal>org.apache.uima.cas.impl.XmiCasSerializer</literal> and
- <literal>org.apache.uima.cas.impl.XmiCasDeserializer</literal>.</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>
-
- <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;"
- /> <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="1"/>
- ...
-</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 = "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="1" begin="14" end="19" myFeature="bar"/>
- ...
-</xmi:XMI></programlisting>
- 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="1">
- <begin>14</begin>
- <end>19</end>
- <myFeature>bar</myFeature>
- </myproj:Foo>
- ...
-</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="1" begin="14" end="19" myFeature="bar"/>
- <myproj:Baz xmi:id="2" myFoo="1"/>
- ...
-</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>
-
- </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>
-
- <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>
- </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>
- 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>
-
- <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="10" head="2" tail="11"/>
-<cas:NonEmptyIntegerList xmi:id="11" head="4" tail="12"/>
-<cas:NonEmptyIntegerList xmi:id="12" head="6" tail="13"/>
-<cas:EmptyIntegerList xmi:id"13"/></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>
-
- <para>When a feature is specified in the descriptor without a multipleReferencesAllowed attribute, or with the
- attribute specified as <code>false</code>, but the framework discovers multiple references during
- serialization, it will issue a message to the log say that it discovered this (look for the phrase
- "serialized in duplicate"). The serialization will continue, but the multiply-referenced items will
- be serialized in duplicate.</para>
- </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 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>
-
- <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>
- </section>
-
- <section id="ugr.ref.xmi.linking_to_ecore_type_system">
- <title>Linking an XMI Document to its Ecore Type System</title>
- <titleabbrev>Linking XMI docs to Ecore Type System</titleabbrev>
-
- <para>If the CAS Type System has been saved to an Ecore file (as described in <olink
- targetdoc="&uima_docs_tutorial_guides;"/> <olink
- targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.xmi_emf"/>), 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>
-
- <section id="ugr.ref.xmi.delta">
- <title>Delta CAS XMI Format</title>
- <titleabbrev>Delta CAS XMI Format</titleabbrev>
- <para>
- The Delta CAS XMI serialization format is designed primarily to reduce the overhead serialization when calling annotators
- configured as services. Only Feature Structures and Views that are new or modified by the service
- are serialized and returned by the service.
- </para>
- <para>
- The classes <literal>org.apache.uima.cas.impl.XmiCasSerializer</literal> and
- <literal>org.apache.uima.cas.impl.XmiCasDeserializer</literal> support serialization of only the modifications to the CAS.
- A caller is expected to set a marker to indicate the point from which changes to the CAS are to be tracked.
- </para>
- <para>
- A Delta CAS XMI document contains only the Feature Structures and Views that have been added or modified.
- The new and modified Feature Structures are represented in exactly the format as in a complete CAS serialization.
- The <literal> cas:View </literal> element has been extended with three additional attributes to represent modifications to
- View membership. These new attributes are <literal>added_members</literal>, <literal>deleted_members</literal> and
- <literal>reindexed_members</literal>. For example:
- </para>
- <programlisting><cas:View sofa="1" added_members="63 77"
- deleted_member="7 61" reindexed_members="39" /></programlisting>
- <para>
- Here the integers 63, 77 represent xmi:id fields of the objects that have been newly added members to this View,
- 7 and 61 are xmi:id fields of the objects that have been removed from this view and 39 is the xmi:id of an object to be reindexed in this view.
- </para>
- </section>
-</chapter>
\ No newline at end of file
diff --git a/uima-docbook-references/src/docbook/ref.xml.component_descriptor.xml b/uima-docbook-references/src/docbook/ref.xml.component_descriptor.xml
deleted file mode 100644
index 95d31e07f..000000000
--- a/uima-docbook-references/src/docbook/ref.xml.component_descriptor.xml
+++ /dev/null
@@ -1,2520 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
-<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >
-<!ENTITY tp "ugr.ref.xml.component_descriptor.">
-%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.xml.component_descriptor">
- <title>Component Descriptor Reference</title>
-
- <para>This chapter is the reference guide for the UIMA SDK's Component Descriptor XML
- schema. A <emphasis>Component Descriptor</emphasis> (also sometimes called a
- <emphasis>Resource Specifier</emphasis> in the code) is an XML file that either (a)
- completely describes a component, including all information needed to construct the
- component and interact with it, or (b) specifies how to connect to and interact with an
- existing component that has been published as a remote service.
- <emphasis>Component</emphasis> (also called <emphasis>Resource</emphasis>) is a
- general term for modules produced by UIMA developers and used by UIMA applications. The
- types of Components are: Analysis Engines, Collection Readers, CAS
- Initializers<footnote><para>This component is deprecated and should not be use in new
- development.</para></footnote>, CAS Consumers, and Collection Processing Engines.
- However, Collection Processing Engine Descriptors are significantly different in
- format and are covered in a separate chapter, <olink targetdoc="&uima_docs_ref;"
- targetptr="ugr.ref.xml.cpe_descriptor"/>.</para>
-
- <para><xref linkend="&tp;notation"/> describes the notation used in this
- chapter.</para>
-
- <para><xref linkend="&tp;imports"/> describes the UIMA SDK's
- <emphasis>import</emphasis> syntax, used to allow XML descriptors to import
- information from other XML files, to allow sharing of information between several XML
- descriptors.</para>
-
- <para><xref linkend="&tp;aes"/> describes the XML format for <emphasis>Analysis Engine
- Descriptors</emphasis>. These are descriptors that completely describe Analysis
- Engines, including all information needed to construct and interact with them.</para>
-
- <para><xref linkend="&tp;collection_processing_parts"/> describes the XML format for
- <emphasis>Collection Processing Component Descriptors</emphasis>. This includes
- Collection Iterator, CAS Initializer, and CAS Consumer Descriptors.</para>
-
- <para><xref linkend="&tp;service_client"/> describes the XML format for
- <emphasis>Service Client Descriptors</emphasis>, which specify how to connect to and
- interact with resources deployed as remote services.</para>
-
- <para><xref linkend="&tp;custom_resource_specifiers"/> describes the XML format for
- <emphasis>Custom Resource Specifiers</emphasis>, which allow you to plug in your
- own Java class as a UIMA Resource.</para>
-
- <section id="&tp;notation">
- <title>Notation</title>
-
- <para>This chapter uses an informal notation to specify the syntax of Component
- Descriptors. The formal syntax is defined by an XML schema definition, which is
- contained in the file <literal>resourceSpecifierSchema.xsd</literal>,
- located in the <literal>uima-core.jar</literal> file.</para>
-
- <para>The notation used in this chapter is:</para>
-
- <itemizedlist><listitem><para>An ellipsis (...) inside an element body indicates
- that the substructure of that element has been omitted (to be described in another
- section of this chapter). An example of this would be:
-
-
- <programlisting><analysisEngineMetaData>
-...
-</analysisEngineMetaData></programlisting>
- An ellipsis immediately after an element indicates that the element type may be may be
- repeated arbitrarily many times. For example:
-
-
- <programlisting><parameter>[String]</parameter>
-<parameter>[String]</parameter>
-...</programlisting>
- indicates that there may be arbitrarily many parameter elements in this
- context.</para></listitem>
-
- <listitem><para>Bracketed expressions (e.g. <literal>[String]</literal>)
- indicate the type of value that may be used at that location.</para></listitem>
-
- <listitem><para>A vertical bar, as in <literal>true|false</literal>, indicates
- alternatives. This can be applied to literal values, bracketed type names, and
- elements.</para></listitem>
-
- <listitem><para>Which elements are optional and which are required is specified in
- prose, not in the syntax definition. </para></listitem></itemizedlist>
- </section>
-
- <section id="&tp;imports">
- <title>Imports</title>
-
- <para>The UIMA SDK defines a particular syntax for XML descriptors to import information
- from other XML files. When one of the following appears in an XML descriptor:
-
-
- <programlisting><import location="[URL]" /> or
-<import name="[Name]" /></programlisting>
- it indicates that information from a separate XML file is being imported. Note that
- imports are allowed only in certain places in the descriptor. In the remainder of this
- chapter, it will be indicated at which points imports are allowed.</para>
-
- <para>If an import specifies a <literal>location</literal> attribute, the value of
- that attribute specifies the URL at which the XML file to import will be found. This can be
- a relative URL, which will be resolved relative to the descriptor containing the
- <literal>import</literal> element, or an absolute URL. Relative URLs can be written
- without a protocol/scheme (e.g., <quote>file:</quote>), and without a host machine
- name. In this case the relative URL might look something like
- <literal>org/apache/myproj/MyTypeSystem.xml.</literal></para>
-
- <para>An absolute URL is written with one of the following prefixes, followed by a path
- such as <literal>org/apache/myproj/MyTypeSystem.xml</literal>:
-
- <itemizedlist spacing="compact"><listitem><para>file:/ ← has no network
- address</para></listitem>
- <listitem><para>file:/// ← has an empty network address</para></listitem>
- <listitem><para>file://some.network.address/</para></listitem>
- </itemizedlist></para>
-
- <para>For more information about URLs, please read the javadoc information for the Java
- class <quote>URL</quote>.</para>
-
- <para>If an import specifies a <literal>name</literal> attribute, the value of that
- attribute should take the form of a Java-style dotted name (e.g.
- <literal>org.apache.myproj.MyTypeSystem</literal>). An .xml file with this name
- will be searched for in the classpath or datapath (described below). As in Java, the dots
- in the name will be converted to file path separators. So an import specifying the
- example name in this paragraph will result in a search for
- <literal>org/apache/myproj/MyTypeSystem.xml</literal> in the classpath or
- datapath.</para>
-
- <para id="&tp;datapath">The datapath works similarly to the classpath but can be set programmatically
- through the resource manager API. Application developers can specify a datapath
- during initialization, using the following code:
-
-
- <programlisting>
-ResourceManager resMgr = UIMAFramework.newDefaultResourceManager();
-resMgr.setDataPath(yourPathString);
-AnalysisEngine ae =
- UIMAFramework.produceAnalysisEngine(desc, resMgr, null);
-</programlisting></para>
-
- <para>The default datapath for the entire JVM can be set via the
- <literal>uima.datapath</literal> Java system property, but this feature should
- only be used for standalone applications that don't need to run in the same JVM as
- other code that may need a different datapath.</para>
-
- <para>The value of a name or location attribute may be parameterized with references to external
- override variables using the <literal>${variable-name}</literal> syntax.
- <programlisting><import location="Annotator${with}ExternalOverrides.xml" /></programlisting>
- If a variable is undefined the value is left unmodified and a warning message identifies the missing
- variable.</para>
-
- <para>Previous versions of UIMA also supported XInclude. That support didn't work in
- many situations, and it is no longer supported. To include other files, please use
- <import>.</para>
-
- <!--
- <para>The UIMA SDK also supports XInclude, a W3C candidate recommendation,
- to include XML files within other XML files. However, it is recommended that the import syntax be used instead, as it
- is more flexible and better supports tool developers.</para>
-
- <note><para>UIMA tools for editing XML
- descriptors do not support the use of xi:include because they cannot correctly
- determine what parts of a descriptor are updatable, and what parts are included
- from other files. They do support the
- use of <import>.
- </para></note>
-
- <para>To use XInclude, you first must include the XInclude
- namespace in your document's root element, e.g.:</para>
-
- <programlisting><analysisEngineDescription xmlns="http://uima.apache.org/resourceSpecifier" xmlns:xi="http://www.w3.org/2001/XInclude"></programlisting>
-
- <para>Then, you can include a file using the syntax <literal><xi:include
- href="[URL]"/></literal></para>
-
- <para>where [URL] can be any relative or absolute URL referring
- to another XML document. The referred-to
- document must be a valid XML document, meaning that it must consist of exactly
- one root element and must define all of the namespace prefixes that it uses. The default namespace (generally <literal>http://uima.apache.org/resourceSpecifier</literal>) will be
- inherited from the parent document. When UIMA parses the XML document, it will automatically replace the <literal><xi:include> </literal>element with the entire XML document
- referred to by the href. For more
- information on XInclude see
- <a href="http://www.w3.org/TR/xinclude/">http://www.w3.org/TR/xinclude/</a>.</para>
- -->
-
- </section>
-
- <section id="&tp;type_system">
- <title>Type System Descriptors</title>
-
- <para>A Type System Descriptor is used to define the types and features that can be
- represented in the CAS. A Type System Descriptor can be imported into an Analysis Engine
- or Collection Processing Component Descriptor.</para>
-
- <para>The basic structure of a Type System Descriptor is as follows:
-
-
- <programlisting><![CDATA[<typeSystemDescription xmlns="http://uima.apache.org/resourceSpecifier">
-
- <name> [String] </name>
- <description>[String]</description>
- <version>[String]</version>
- <vendor>[String]</vendor>
-
- <imports>
- <import ...>
- ...
- </imports>
-
- <types>
- <typeDescription>
- ...
- </typeDescription>
-
- ...
-
- </types>
-
-</typeSystemDescription>]]></programlisting></para>
-
- <para>All of the subelements are optional.</para>
-
- <section id="&tp;type_system.imports">
- <title>Imports</title>
-
- <para>The <literal>imports</literal> section allows this descriptor to import
- types from other type system descriptors. The import syntax is described in <xref
- linkend="&tp;imports"/>. A type system may import any number of other type
- systems and then define additional types which refer to imported types. Circular
- imports are allowed.</para>
- </section>
-
- <section id="&tp;type_system.types">
- <title>Types</title>
-
- <para>The <literal>types</literal> element contains zero or more
- <literal>typeDescription</literal> elements. Each
- <literal>typeDescription</literal> has the form:
-
-
- <programlisting><![CDATA[<typeDescription>
- <name>[TypeName]</name>
- <description>[String]</description>
- <supertypeName>[TypeName]</supertypeName>
- <features>
- ...
- </features>
-</typeDescription>]]></programlisting></para>
-
- <para>The name element contains the name of the type. A
- <literal>[TypeName]</literal> is a dot-separated list of names, where each name
- consists of a letter followed by any number of letters, digits, or underscores.
- <literal>TypeNames</literal> are case sensitive. Letter and digit are as defined
- by Java; therefore, any Unicode letter or digit may be used (subject to the character
- encoding defined by the descriptor file's XML header). The name following the
- final dot is considered to be the <quote>short name</quote> of the type; the
- preceding portion is the namespace (analogous to the package.class syntax used in
- Java). Namespaces beginning with uima are reserved and should not be used. Examples
- of valid type names are:</para>
-
- <itemizedlist spacing="compact"><listitem><para>test.TokenAnnotation</para>
- </listitem>
-
- <listitem><para>org.myorg.TokenAnnotation</para></listitem>
-
- <listitem><para>com.my_company.proj123.TokenAnnotation </para></listitem>
- </itemizedlist>
-
- <para>These would all be considered distinct types since they have different
- namespaces. Best practice here is to follow the normal Java naming conventions of
- having namespaces be all lowercase, with the short type names having an initial
- capital, but this is not mandated, so <literal>ABC.mYtyPE</literal> is an allowed
- type name. While type names without namespaces (e.g.
- <literal>TokenAnnotation</literal> alone) are allowed, but discouraged because
- naming conflicts can then result when combining annotators that use different
- type systems.</para>
-
- <para>The <literal>description</literal> element contains a textual description
- of the type. The <literal>supertypeName</literal> element contains the name of the
- type from which it inherits (this can be set to the name of another user-defined type,
- or it may be set to any built-in type which may be subclassed, such as
- <literal>uima.tcas.Annotation</literal> for a new annotation
- type or <literal>uima.cas.TOP</literal> for a new type that is not
- an annotation). All three of these elements are required.</para>
-
- </section>
-
- <section id="&tp;type_system.features">
- <title>Features</title>
-
- <para>The <literal>features</literal> element of a
- <literal>typeDescription</literal> is required only if the type we are specifying
- introduces new features. If the <literal>features</literal> element is present,
- it contains zero or more <literal>featureDescription</literal> elements, each of
- which has the form:</para>
-
-
- <programlisting><![CDATA[<featureDescription>
- <name>[Name]</name>
- <description>[String]</description>
- <rangeTypeName>[Name]</rangeTypeName>
- <elementType>[Name]</elementType>
- <multipleReferencesAllowed>true|false</multipleReferencesAllowed>
-</featureDescription>]]></programlisting>
-
- <para>A feature's name follows the same rules as a type short name – a letter
- followed by any number of letters, digits, or underscores. Feature names are case
- sensitive.</para>
-
- <para>The feature's <literal>rangeTypeName</literal> specifies the type of
- value that the feature can take. This may be the name of any type defined in your type
- system, or one of the predefined types. All of the predefined types have names that are
- prefixed with <literal>uima.cas</literal> or <literal>uima.tcas</literal>,
- for example:
-
-
- <programlisting>uima.cas.TOP
-uima.cas.String
-uima.cas.Long
-uima.cas.FSArray
-uima.cas.StringList
-uima.tcas.Annotation.</programlisting>
- For a complete list of predefined types, see the CAS API documentation.</para>
-
- <para>The <literal>elementType</literal> of a feature is optional, and applies only
- when the <literal>rangeTypeName</literal> is
- <literal>uima.cas.FSArray</literal> or <literal>uima.cas.FSList</literal>
- The <literal>elementType</literal> specifies what type of value can be assigned as
- an element of the array or list. This must be the name of a non-primitive type. If
- omitted, it defaults to <literal>uima.cas.TOP</literal>, meaning that any
- FeatureStructure can be assigned as an element the array or list. Note: depending on
- the CAS Interface that you use in your code, this constraint may or may not be
- enforced.
- Note: At run time, the elementType is available from a runtime Feature object
- (using the <literal>a_feature_object.getRange().getComponentType()</literal> method)
- only when specified for the <literal>uima.cas.FSArray</literal> ranges; it isn't
- available for <literal>uima.cas.FSList</literal> ranges.
- </para>
-
-
- <para>The <literal>multipleReferencesAllowed</literal> feature is optional, and
- applies only when the <literal>rangeTypeName</literal> is an array or list type (it
- applies to arrays and lists of primitive as well as non-primitive types). Setting
- this to false (the default) indicates that this feature has exclusive ownership of
- the array or list, so changes to the array or list are localized. Setting this to true
- indicates that the array or list may be shared, so changes to it may affect other
- objects in the CAS. Note: there is currently no guarantee that the framework will
- enforce this restriction. However, this setting may affect how the CAS is
- serialized.</para>
-
- </section>
-
- <section id="&tp;type_system.string_subtypes">
- <title>String Subtypes</title>
-
- <para>There is one other special type that you can declare – a subset of the String
- type that specifies a restricted set of allowed values. This is useful for features
- that can have only certain String values, such as parts of speech. Here is an example of
- how to declare such a type:</para>
-
-
- <programlisting><![CDATA[<typeDescription>
- <name>PartOfSpeech</name>
- <description>A part of speech.</description>
- <supertypeName>uima.cas.String</supertypeName>
- <allowedValues>
- <value>
- <string>NN</string>
- <description>Noun, singular or mass.</description>
- </value>
- <value>
- <string>NNS</string>
- <description>Noun, plural.</description>
- </value>
- <value>
- <string>VB</string>
- <description>Verb, base form.</description>
- </value>
- ...
- </allowedValues>
-</typeDescription>]]></programlisting>
-
- </section>
- </section>
-
- <section id="&tp;aes">
- <title>Analysis Engine Descriptors</title>
-
- <para>Analysis Engine (AE) descriptors completely describe Analysis Engines. There
- are two basic types of Analysis Engines – <emphasis>Primitive</emphasis> and
- <emphasis>Aggregate</emphasis>. A <emphasis>Primitive</emphasis> Analysis
- Engine is a container for a single <emphasis>annotator</emphasis>, where as an
- <emphasis>Aggregate</emphasis> Analysis Engine is composed of a collection of other
- Analysis Engines. (For more information on this and other terminology, see <olink
- targetdoc="&uima_docs_overview;"/> <olink
- targetdoc="&uima_docs_overview;" targetptr="ugr.ovv.conceptual"/>).</para>
-
- <para>Both Primitive and Aggregate Analysis Engines have descriptors, and the two types
- of descriptors have some similarities and some differences. <xref linkend="&tp;aes.primitive"/>
- discusses Primitive Analysis Engine descriptors. <xref linkend="&tp;aes.aggregate"/> then
- describes how Aggregate Analysis Engine descriptors are different.</para>
-
- <section id="&tp;aes.primitive">
- <title>Primitive Analysis Engine Descriptors</title>
-
- <section id="&tp;aes.primitive.basic">
- <title>Basic Structure</title>
-
-
- <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8" ?>
-<analysisEngineDescription
- xmlns="http://uima.apache.org/resourceSpecifier">
- <frameworkImplementation>org.apache.uima.java</frameworkImplementation>
-
- <primitive>true</primitive>
- <annotatorImplementationName> [String] </annotatorImplementationName>
-
- <analysisEngineMetaData>
- ...
- </analysisEngineMetaData>
-
- <externalResourceDependencies>
- ...
- </externalResourceDependencies>
-
- <resourceManagerConfiguration>
- ...
- </resourceManagerConfiguration>
-
-</analysisEngineDescription>]]></programlisting>
-
- <para>The document begins with a standard XML header. The recommended root tag is
- <literal><analysisEngineDescription></literal>, although
- <literal><taeDescription></literal> is also allowed for backwards
- compatibility.</para>
-
- <para>Within the root element we declare that we are using the XML namespace
- <literal>http://uima.apache.org/resourceSpecifier.</literal> It is
- required that this namespace be used; otherwise, the descriptor will not be able to
- be validated for errors.</para>
-
- <para> The first subelement,
- <literal><frameworkImplementation>,</literal> currently must have
- the value <literal>org.apache.uima.java</literal>, or
- <literal>org.apache.uima.cpp</literal>. In future versions, there may be
- other framework implementations, or perhaps implementations produced by other
- vendors.</para>
-
- <para>The second subelement, <literal><primitive>,</literal> contains
- the Boolean value <literal>true</literal>, indicating that this XML document
- describes a <emphasis>Primitive</emphasis> Analysis Engine.</para>
-
- <para>The next subelement,<literal>
- <annotatorImplementationName></literal> is how the UIMA framework
- determines which annotator class to use. This should contain a fully-qualified
- Java class name for Java implementations, or the name of a .dll or .so file for C++
- implementations.</para>
-
- <para>The <literal><analysisEngineMetaData></literal> object contains
- descriptive information about the analysis engine and what it does. It is
- described in <xref linkend="&tp;aes.metadata"/>.</para>
-
- <para>The <literal><externalResourceDependencies></literal> and
- <literal><resourceManagerConfiguration></literal> elements declare
- the external resource files that the analysis engine relies
- upon. They are optional and are described in <xref
- linkend="&tp;aes.primitive.external_resource_dependencies"/> and <xref
- linkend="&tp;aes.primitive.resource_manager_configuration"/>.</para>
-
- </section>
-
- <section id="&tp;aes.metadata">
- <title>Analysis Engine MetaData</title>
-
-
- <programlisting><![CDATA[<analysisEngineMetaData>
- <name> [String] </name>
- <description>[String]</description>
- <version>[String]</version>
- <vendor>[String]</vendor>
-
- <configurationParameters> ... </configurationParameters>
-
- <configurationParameterSettings>
- ...
- </configurationParameterSettings>
-
- <typeSystemDescription> ... </typeSystemDescription>
-
- <typePriorities> ... </typePriorities>
-
- <fsIndexCollection> ... </fsIndexCollection>
-
- <capabilities> ... </capabilities>
-
- <operationalProperties> ... </operationalProperties>
-
-</analysisEngineMetaData>]]></programlisting>
-
- <para>The <literal>analysisEngineMetaData</literal> element contains four
- simple string fields – <literal>name</literal>,
- <literal>description</literal>, <literal>version</literal>, and
- <literal>vendor</literal>. Only the <literal>name</literal> field is
- required, but providing values for the other fields is recommended. The
- <literal>name</literal> field is just a descriptive name meant to be read by
- users; it does not need to be unique across all Analysis Engines.</para>
-
- <para>Configuration parameters are described in
- <xref linkend="&tp;aes.configuration_parameters"/>.</para>
-
- <para>The other sub-elements –
- <literal>typeSystemDescription</literal>,
- <literal>typePriorities</literal>, <literal>fsIndexes</literal>,
- <literal>capabilities</literal> and
- <literal>operationalProperties</literal> are described in the following
- sections. The only one of these that is required is
- <literal>capabilities</literal>; the others are optional.</para>
-
- </section>
-
- <section id="&tp;aes.type_system">
- <title>Type System Definition</title>
-
-
- <programlisting><![CDATA[<typeSystemDescription>
-
- <name> [String] </name>
- <description>[String]</description>
- <version>[String]</version>
- <vendor>[String]</vendor>
-
- <imports>
- <import ...>
- ...
- </imports>
-
- <types>
- <typeDescription>
- ...
- </typeDescription>
-
- ...
-
- </types>
-
-</typeSystemDescription>]]></programlisting>
-
- <para>A <literal>typeSystemDescription</literal> element defines a type
- system for an Analysis Engine. The syntax for the element is described in <xref
- linkend="&tp;type_system"/>.</para>
-
- <para>The recommended usage is to <literal>import</literal> an external type
- system, using the import syntax described in <xref linkend="&tp;imports"/>
- of this chapter. For example:
-
-
- <programlisting><typeSystemDescription>
- <imports>
- <import location="MySharedTypeSystem.xml">
- </imports>
-</typeSystemDescription></programlisting></para>
-
- <para>This allows several AEs to share a single type system definition. The file
- <literal>MySharedTypeSystem.xml</literal> would then contain the full
- type system information, including the <literal>name</literal>,
- <literal>description</literal>, <literal>vendor</literal>,
- <literal>version</literal>, and <literal>types</literal>.</para>
-
- </section>
- <section id="&tp;aes.type_priority">
- <title>Type Priority Definition</title>
-
-
- <programlisting><![CDATA[<typePriorities>
- <name> [String] </name>
- <description>[String]</description>
- <version>[String]</version>
- <vendor>[String]</vendor>
-
- <imports>
- <import ...>
- ...
- </imports>
-
- <priorityLists>
- <priorityList>
- <type>[TypeName]</type>
- <type>[TypeName]</type>
- ...
- </priorityList>
-
- ...
-
- </priorityLists>
-</typePriorities>]]></programlisting>
-
- <para>The <literal><typePriorities></literal> element contains
- zero or more <literal><priorityList></literal> elements; each
- <literal><priorityList></literal> contains zero or more types.
- Like a type system, a type priorities definition may also declare a name,
- description, version, and vendor, and may import other type priorities. See
- <xref linkend="&tp;imports"/> for the import syntax.</para>
-
- <para>Type priority is used when iterating over feature structures in the CAS.
- For example, if the CAS contains a <literal>Sentence</literal> annotation
- and a <literal>Paragraph</literal> annotation with the same span of text
- (i.e. a one-sentence paragraph), which annotation should be returned first
- by an iterator? Probably the Paragraph, since it is conceptually
- <quote>bigger,</quote> but the framework does not know that and must be
- explicitly told that the Paragraph annotation has priority over the Sentence
- annotation, like this:
-
-
- <programlisting><typePriorities>
- <priorityList>
- <type>org.myorg.Paragraph</type>
- <type>org.myorg.Sentence</type>
- </priorityList>
-</typePriorities></programlisting></para>
-
- <para>All of the <literal><priorityList></literal> elements defined
- in the descriptor (and in all component descriptors of an aggregate analysis
- engine descriptor) are merged to produce a single priority list.</para>
-
- <para>Subtypes of types specified here are also ordered, unless overridden by
- another user-specified type ordering. For example, if you specify type A
- comes before type B, then subtypes of A will come before subtypes of B, unless
- there is an overriding specification which declares some subtype of B comes
- before some subtype of A.</para>
-
- <para>If there are inconsistencies between the priority list (type A declared
- before type B in one priority list, and type B declared before type A in
- another), the framework will throw an exception.</para>
-
- <para>User defined indexes may declare if they wish to use the type priority or
- not; see the next section.</para>
- </section>
-
- <section id="&tp;aes.index">
- <title>Index Definition</title>
-
-
- <programlisting><![CDATA[<fsIndexCollection>
-
- <name>[String]</name>
- <description>[String]</description>
- <version>[String]</version>
- <vendor>[String]</vendor>
-
- <imports>
- <import ...>
- ...
- </imports>
-
- <fsIndexes>
-
- <fsIndexDescription>
- ...
- </fsIndexDescription>
-
- <fsIndexDescription>
- ...
- </fsIndexDescription>
-
- </fsIndexes>
-
-</fsIndexCollection>]]></programlisting>
-
- <para>The <literal>fsIndexCollection</literal> element declares<emphasis> Feature Structure
- Indexes</emphasis>, each of which defined an index that holds feature structures of a given type.
- Information in the CAS is always accessed through an index. There is a built-in default annotation
- index declared which can be used to access instances of type
- <literal>uima.tcas.Annotation</literal> (or its subtypes), sorted based on their
- <literal>begin</literal> and <literal>end</literal> features, and the type priority ordering (if specified).
- For all other types, there is a
- default, unsorted (bag) index. If there is a need for a specialized index it must be declared in this
- element of the descriptor. See <olink targetdoc="&uima_docs_ref;"
- targetptr="ugr.ref.cas.indexes_and_iterators"/> for details on FS indexes.</para>
-
- <para>Like type systems and type priorities, an
- <literal>fsIndexCollection</literal> can declare a
- <literal>name</literal>, <literal>description</literal>,
- <literal>vendor</literal>, and <literal>version</literal>, and may
- import other <literal>fsIndexCollection</literal>s. The import syntax is
- described in <xref linkend="&tp;imports"/>.</para>
-
- <para>An <literal>fsIndexCollection</literal> may also define zero or more
- <literal>fsIndexDescription</literal> elements, each of which defines a
- single index. Each <literal>fsIndexDescription</literal> has the form:
-
-
- <programlisting><![CDATA[<fsIndexDescription>
-
- <label>[String]</label>
- <typeName>[TypeName]</typeName>
- <kind>sorted|bag|set</kind>
-
- <keys>
-
- <fsIndexKey>
- <featureName>[Name]</featureName>
- <comparator>standard|reverse</comparator>
- </fsIndexKey>
-
- <fsIndexKey>
- <typePriority/>
- </fsIndexKey>
-
- ...
-
- </keys>
-</fsIndexDescription>]]></programlisting></para>
-
- <para>The <literal>label</literal> element defines the name by which
- applications and annotators refer to this index. The
- <literal>typeName</literal> element contains the name of the type that will
- be contained in this index. This must match one of the type names defined in the
- <literal><typeSystemDescription></literal>.</para>
-
- <para>There are three possible values for the
- <literal><kind></literal> of index. Sorted indexes enforce an
- ordering of feature structures, based on defined keys. Bag indexes do
- not enforce ordering, and have no defined keys. Set indexes do not
- enforce ordering, but use defined keys to specify equivalence classes;
- addToIndexes will not add a Feature Structure to a set index if its keys
- match those of an entry of the same type already in the index.
- If the <literal><kind></literal>element is omitted, it will default to
- sorted, which is the most common type of index.</para>
-
- <para>Prior to version 2.7.0, the bag and sorted indexes stored duplicate entries for the
- same identical FS, if it was added to the indexes multiple times. As of version 2.7.0, this
- is changed; a second or subsequent add to index operation has no effect. This has the
- consequence that a remove operation now guarantees that the particular FS is removed
- (as opposed to only being able to say that one (of perhaps many duplicate entries) is removed).
- Since sending to remote annotators only adds entries to indexes at most once, this
- behavior is consistent with that.</para>
-
- <para>Note that even after this change, there is still a distinct difference in meaning for bag and set indexes.
- The set index uses equal defined key values plus the type of the Feature Structure to determine equivalence classes for Feature Structures, and
- will not add a Feature Structure if it has equal key values and the same type to an entry already in there.</para>
-
- <para>It is possible, however, that users may be depending on having multiple instances of
- the identical FeatureStructure in the indicies. Therefore, UIMA uses
- a JVM defined property,
- "uima.allow_duplicate_add_to_indexes", which (if defined whend UIMA is loaded) will restore the previous behavior.</para>
-
- <note><para>If duplicates are allowed, then the proper way to update an indexed Feature Structure is to
- <itemizedlist>
- <listitem><para>remove <emphasis role="bold">*all*</emphasis> instances of the FS to be
- updated </para></listitem>
- <listitem><para>update the features</para></listitem>
- <listitem><para>re-add the Feature Structure to the indexes (perhaps multiple times, depending on the
- details of your logic).</para></listitem>
- </itemizedlist></para></note>
-
- <note><para>There is usually no need to explicitly declare a Bag index in your descriptor.
- As of UIMA v2.1, if you do not declare any index for a type (or any of its
- supertypes), a Bag index will be automatically created if an instance of that type is added to the indexes.</para></note>
-
- <para>An Sorted or Set index may define zero or more <emphasis>keys</emphasis>. These keys
- determine the sort order of the feature structures within a sorted index, and
- partially determine equality for set indexes (the equality measure always includes testing that the types are the same).
- Bag indexes do not use keys, and
- equality is determined by Feature Structure identity (that is, two elements
- are considered equal if and only if they are exactly the same feature structure,
- located in the same place in the CAS). Keys are
- ordered by precedence – the first key is evaluated first, and
- subsequent keys are evaluated only if necessary.</para>
-
- <para>Each key is represented by an <literal>fsIndexKey</literal> element.
- Most <literal>fsIndexKeys</literal> contains a
- <literal>featureName</literal> and a <literal>comparator</literal>.
- The <literal>featureName</literal> must match the name of one of the
- features for the type specified in the
- <literal><typeName></literal> element for this index. The
- comparator defines how the features will be compared – a value of
- <literal>standard</literal> means that features will be compared using the
- standard comparison for their data type (e.g. for numerical types, smaller
- values precede larger values, and for string types, Unicode string
- comparison is performed). A value of <literal>reverse</literal> means that
- features will be compared using the reverse of the standard comparison (e.g.
- for numerical types, larger values precede smaller values, etc.). For Set
- indexes, the comparator direction is ignored – the keys are only used
- for the equality testing.</para>
-
- <para>Each key used in comparisons must refer to a feature whose range type is
- Boolean, Byte, Short, Integer, Long, Float, Double, or String.
- </para>
-
- <para>There is a second type of a key, one which contains only the
- <literal><typePriority/></literal>. When this key is used, it
- indicates that Feature Structures will be compared using the type priorities
- declared in the <literal><typePriorities></literal> section of the
- descriptor.</para>
-
- </section>
-
- <section id="&tp;aes.capabilities">
- <title>Capabilities</title>
-
-
- <programlisting><![CDATA[<capabilities>
- <capability>
-
- <inputs>
- <type allAnnotatorFeatures="true|false"[TypeName]</type>
- ...
- <feature>[TypeName]:[Name]</feature>
- ...
- </inputs>
-
- <outputs>
- <type allAnnotatorFeatures="true|false"[TypeName]</type>
- ...
- <feature>[TypeName]:[Name]</feature>
- ...
- </output>
-
- <inputSofas>
- <sofaName>[name]</sofaName>
- ...
- </inputSofas>
-
- <outputSofas>
- <sofaName>[name]</sofaName>
- ...
- </outputSofas>
-
- <languagesSupported>
- <language>[ISO Language ID]</language>
- ...
- </languagesSupported>
- </capability>
-
- <capability>
- ...
- </capability>
-
- ...
-
-</capabilities>]]></programlisting>
-
- <para>The capabilities definition is used by the UIMA Framework in several
- ways, including setting up the Results Specification for process calls,
- routing control for aggregates based on language, and as part of the Sofa
- mapping function.</para>
-
- <para>The <literal>capabilities</literal> element contains one or more
- <literal>capability</literal> elements. In Version 2 and onwards, only one
- capability set should be used (multiple sets will continue to work for a while,
- but they're not logically consistently supported).
- <!-- Because you can therefore
- declare multiple capability sets, you can use this to model component behavior
-
- that for a given set of inputs, produces a particular set of outputs. --></para>
-
- <para>Each <literal>capability</literal> contains
- <literal>inputs</literal>, <literal>outputs</literal>,
- <literal>languagesSupported, inputSofas, and outputSofas</literal>.
- Inputs and outputs element are required (though they may be empty);
- <literal><languagesSupported>, <inputSofas</literal>>,
- and <literal><outputSofas></literal> are optional.</para>
-
- <para>Both inputs and outputs may contain a mixture of type and feature
- elements.</para>
-
- <para><literal><type...></literal> elements contain the name of one
- of the types defined in the type system or one of the built in types. Declaring a
- type as an input means that this component expects instances of this type to be
- in the CAS when it receives it to process. Declaring a type as an output means
- that this component creates new instances of this type in the CAS.</para>
-
- <para>There is an optional attribute
- <literal>allAnnotatorFeatures</literal>, which defaults to false if
- omitted. The Component Descriptor Editor tool defaults this to true when a new
- type is added to the list of inputs and/or outputs. When this attribute is true,
- it specifies that all of the type's features are also declared as input or
- output. Otherwise, the features that are required as inputs or populated as
- outputs must be explicitly specified in feature elements.</para>
-
- <para><literal><feature...></literal> elements contain the
- <quote>fully-qualified</quote> feature name, which is the type name
- followed by a colon, followed by the feature name, e.g.
- <literal>org.myorg.TokenAnnotation:lemma</literal>.
- <literal><feature...></literal> elements in the
- <literal><inputs></literal> section must also have a corresponding
- type declared as an input. In output sections, this is not required. If the type
- is not specified as an output, but a feature for that type is, this means that
- existing instances of the type have the values of the specified features
- updated. Any type mentioned in a <literal><feature></literal>
- element must be either specified as an input or an output or both.</para>
-
- <para><literal>language </literal>elements contain one of the ISO language
- identifiers, such as <literal>en</literal> for English, or
- <literal>en-US</literal> for the United States dialect of English.</para>
-
- <para>The list of language codes can be found here: <ulink
- url="http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt"/>
- and the country codes here:
- <ulink
- url="http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html"/>
- </para>
-
- <para><literal><inputSofas></literal> and
- <literal><outputSofas></literal> declare sofa names used by this
- component. All Sofa names must be unique within a particular capability set. A
- Sofa name must be an input or an output, and cannot be both. It is an error to have a
- Sofa name declared as an input in one capability set, and also have it declared
- as an output in another capability set.</para>
-
- <para>A <literal><sofaName></literal> is written as a simple
- Java-style identifier, without any periods in the name, except that it may be
- written to end in <quote><literal>.*</literal></quote>. If written in this
- manner, it specifies a set of Sofa names, all of which start with the base name
- (the part before the .*) followed by a period and then an arbitrary Java
- identifier (without periods). This form is used to specify in the descriptor
- that the component could generate an arbitrary number of Sofas, the exact
- names and numbers of which are unknown before the component is run.</para>
-
- </section>
-
- <section id="&tp;aes.operational_properties">
- <title>OperationalProperties</title>
-
- <para>Components can specify specific operational properties that can be
- useful in deployment. The following are available:</para>
-
-
- <programlisting><![CDATA[<operationalProperties>
- <modifiesCas> true|false </modifiesCas>
- <multipleDeploymentAllowed> true|false </multipleDeploymentAllowed>
- <outputsNewCASes> true|false </outputsNewCASes>
-</operationalProperties>]]></programlisting>
-
- <para><literal>ModifiesCas</literal>, if false, indicates that this
- component does not modify the CAS. If it is not specified, the default value is
- true except for CAS Consumer components.</para>
-
- <para><literal>multipleDeploymentAllowed</literal>, if true, allows the
- component to be deployed multiple times to increase performance through
- scale-out techniques. If it is not specified, the default value is true,
- except for CAS Consumer and Collection Reader components.</para>
-
- <note><para>If you wrap one or more CAS Consumers inside an aggregate as the only
- components, you must explicitly specify in the aggregate the
- <literal>multipleDeploymentAllowed</literal> property as false (assuming the CAS Consumer
- components take the default here); otherwise the framework will complain about inconsistent
- settings for these.</para></note>
-
- <para><literal>outputsNewCASes</literal>, if true, allows the component to
- create new CASes during processing, for example to break a large artifact into
- smaller pieces. See <olink targetdoc="&uima_docs_tutorial_guides;"
- /> <olink targetdoc="&uima_docs_tutorial_guides;"
- targetptr="ugr.tug.cm"/> for details.</para>
- </section>
-
- <section id="&tp;aes.primitive.external_resource_dependencies">
- <title>External Resource Dependencies</title>
-
-
- <programlisting><![CDATA[<externalResourceDependencies>
- <externalResourceDependency>
- <key>[String]</key>
- <description>[String] </description>
- <interfaceName>[String]</interfaceName>
- <optional>true|false</optional>
- </externalResourceDependency>
-
- <externalResourceDependency>
- ...
- </externalResourceDependency>
-
- ...
-
-</externalResourceDependencies>]]></programlisting>
-
- <para>A primitive annotator may declare zero or more
- <literal><externalResourceDependency></literal> elements. Each
- dependency has the following elements:
-
- <itemizedlist><listitem><para><literal>key</literal> – the
- string by which the annotator code will attempt to access the resource. Must
- be unique within this annotator.</para></listitem>
-
- <listitem><para><literal>description</literal> – a textual
- description of the dependency.</para></listitem>
-
- <listitem><para><literal>interfaceName</literal> – the
- fully-qualified name of the Java interface through which the annotator
- will access the data. This is optional. If not specified, the annotator
- can only get an InputStream to the data.</para></listitem>
-
- <listitem><para><literal>optional</literal> – whether the
- resource is optional. If false, an exception will be thrown if no resource
- is assigned to satisfy this dependency. Defaults to false. </para>
- </listitem></itemizedlist></para>
-
- </section>
-
- <section id="&tp;aes.primitive.resource_manager_configuration">
- <title>Resource Manager Configuration</title>
-
-
- <programlisting><![CDATA[<resourceManagerConfiguration>
-
- <name>[String]</name>
- <description>[String]</description>
- <version>[String]</version>
- <vendor>[String]</vendor>
-
- <imports>
- <import ...>
- ...
- </imports>
-
- <externalResources>
-
- <externalResource>
- <name>[String]</name>
- <description>[String]</description>
- <fileResourceSpecifier>
- <fileUrl>[URL]</fileUrl>
- </fileResourceSpecifier>
- <implementationName>[String]</implementationName>
- </externalResource>
- ...
- </externalResources>
-
- <externalResourceBindings>
- <externalResourceBinding>
- <key>[String]</key>
- <resourceName>[String]</resourceName>
- </externalResourceBinding>
- ...
- </externalResourceBindings>
-
-</resourceManagerConfiguration>]]></programlisting>
-
- <para>This element declares external resources and binds them to
- annotators' external resource dependencies.</para>
-
- <para>The <literal>resourceManagerConfiguration</literal> element may
- optionally contain an <literal>import</literal>, which allows resource
- definitions to be stored in a separate (shareable) file. See <xref
- linkend="&tp;imports"/> for details.</para>
-
- <para>The <literal>externalResources</literal> element contains zero or
- more <literal>externalResource</literal> elements, each of which
- consists of:
-
- <itemizedlist><listitem><para><literal>name</literal> – the
- name of the resource. This name is referred to in the bindings (see below).
- Resource names need to be unique within any Aggregate Analysis Engine or
- Collection Processing Engine, so the Java-like
- <literal>org.myorg.mycomponent.MyResource</literal> syntax is
- recommended.</para></listitem>
-
- <listitem><para><literal>description</literal> – English
- description of the resource.</para></listitem>
-
- <listitem><para>Resource Specifier –
- Declares the location of the resource. There are different
- possibilities for how this is done (see below).</para></listitem>
-
- <listitem><para><literal>implementationName</literal> – The
- fully-qualified name of the Java class that will be instantiated from the
- resource data. This is optional; if not specified, the resource will be
- accessible as an input stream to the raw data. If specified, the Java class
- must implement the <literal>interfaceName</literal> that is
- specified in the External Resource Dependency to which it is bound.
- </para></listitem></itemizedlist></para>
-
- <para>One possibility for the resource specifier is a
- <literal><fileResourceSpecifier></literal>, as shown above. This
- simply declares a URL to the resource data. This support is built on the Java
- class URL and its method URL.openStream(); it supports the protocols
- <quote>file</quote>, <quote>http</quote> and <quote>jar</quote> (for
- referring to files in jars) by default, and you can plug in handlers for other
- protocols. The URL has to start with file: (or some other protocol). It is
- relative to either the classpath or the <quote>data path</quote>. The data
- path works like the classpath but can be set programmatically via
- <literal>ResourceManager.setDataPath()</literal>. Setting the Java
- System property <literal>uima.datapath</literal> also works.</para>
-
- <para><literal>file:com/apache.d.txt</literal> is a relative path;
- relative paths for resources are resolved using the classpath and/or the
- datapath. For the file protocol, URLs starting with file:/ or file:/// are
- absolute. Note that <literal>file://org/apache/d.txt</literal> is NOT an
- absolute path starting with <quote>org</quote>. The <quote>//</quote>
- indicates that what follows is a host name. Therefore if you try to use this URL
- it will complain that it can't connect to the host <quote>org</quote>
- </para>
-
- <para>The URL value may contain references to external override variables using the
- <literal>${variable-name}</literal> syntax,
- e.g. <literal>file:com/${dictUrl}.txt</literal>.
- If a variable is undefined the value is left unmodified and a warning message
- identifies the missing variable.
- </para>
-
- <para>Another option is a
- <literal><fileLanguageResourceSpecifier></literal>, which is
- intended to support resources, such as dictionaries, that depend on the
- language of the document being processed. Instead of a single URL, a prefix and
- suffix are specified, like this:
-
-
- <programlisting><![CDATA[<fileLanguageResourceSpecifier>
- <fileUrlPrefix>file:FileLanguageResource_implTest_data_</fileUrlPrefix>
- <fileUrlSuffix>.dat</fileUrlSuffix>
-</fileLanguageResourceSpecifier>]]></programlisting></para>
-
- <para>The URL of the actual resource is then formed by concatenating the prefix,
- the language of the document (as an ISO language code, e.g.
- <literal>en</literal> or <literal>en-US</literal>
- – see <xref linkend="&tp;aes.capabilities"/> for more
- information), and the suffix.</para>
-
- <para>A third option is a <literal>customResourceSpecifier</literal>, which allows
- you to plug in an arbitrary Java class. See <xref linkend="&tp;custom_resource_specifiers"/>
- for more information.</para>
-
- <para>The <literal>externalResourceBindings</literal> element declares
- which resources are bound to which dependencies. Each
- <literal>externalResourceBinding</literal> consists of:
-
- <itemizedlist><listitem><para><literal>key</literal> –
- identifies the dependency. For a binding declared in a primitive analysis
- engine descriptor, this must match the value of the
- <literal>key</literal> element of one of the
- <literal>externalResourceDependency</literal> elements. Bindings
- may also be specified in aggregate analysis engine descriptors, in which
- case a compound key is used
- – see <xref
- linkend="&tp;aes.aggregate.external_resource_bindings"/>
- .</para></listitem>
-
- <listitem><para><literal>resourceName</literal> – the name of
- the resource satisfying the dependency. This must match the value of the
- <literal>name</literal> element of one of the
- <literal>externalResource</literal> declarations. </para>
- </listitem></itemizedlist></para>
-
- <para>A given resource dependency may only be bound to one external resource;
- one external resource may be bound to many dependencies – to allow
- resource sharing.</para>
- </section>
-
- <section id="&tp;aes.environment_variable_references">
- <title>Environment Variable References</title>
-
- <para>In several places throughout the descriptor, it is possible to reference
- environment variables. In Java, these are actually references to Java system
- properties. To reference system environment variables from a Java analysis
- engine you must pass the environment variables into the Java virtual machine
- by using the <literal>−D</literal> option on the <literal>java</literal>
- command line.</para>
-
- <para>The syntax for environment variable references is
- <literal><envVarRef>[VariableName]</envVarRef></literal>
- , where [VariableName] is any valid Java system property name. Environment
- variable references are valid in the following places:
-
- <itemizedlist spacing="compact"><listitem><para>The value of a
- configuration parameter (String-valued parameters only)</para>
- </listitem>
-
- <listitem><para>The
- <literal><annotatorImplementationName></literal> element
- of a primitive AE descriptor</para></listitem>
-
- <listitem><para>The <literal><name></literal> element within
- <literal><analysisEngineMetaData></literal></para>
- </listitem>
-
- <listitem><para>Within a
- <literal><fileResourceSpecifier></literal> or
- <literal><fileLanguageResourceSpecifier></literal>
- </para></listitem></itemizedlist></para>
-
- <para>For example, if the value of a configuration parameter were specified as:
- <literal><string><envVarRef>TEMP_DIR</envVarRef>/temp.dat</string></literal>
- , and the value of the <literal>TEMP_DIR</literal> Java System property were
- <literal>c:/temp</literal>, then the configuration parameter's
- value would evaluate to <literal>c:/temp/temp.dat</literal>.</para>
-
- <note><para>The Component Descriptor Editor does not support
- environment variable references. If you need to, however, you
- can use the <code>source</code> tab view in the CDE to manually
- add this notation.
- </para></note>
-
- </section>
- </section>
- <section id="&tp;aes.aggregate">
- <title>Aggregate Analysis Engine Descriptors</title>
-
- <para>Aggregate Analysis Engines do not contain an annotator, but instead
- contain one or more component (also called <emphasis>delegate</emphasis>)
- analysis engines.</para>
-
- <para>Aggregate Analysis Engine Descriptors maintain most of the same structure
- as Primitive Analysis Engine Descriptors. The differences are:</para>
-
- <itemizedlist><listitem><para>An Aggregate Analysis Engine Descriptor
- contains the element
- <literal><primitive>false</primitive></literal> rather
- than <literal><primitive>true</primitive></literal>.
- </para></listitem>
-
- <listitem><para>An Aggregate Analysis Engine Descriptor must not include a
- <literal><annotatorImplementationName></literal>
- element.</para></listitem>
-
- <listitem><para>In place of the
- <literal><annotatorImplementationName></literal>, an Aggregate
- Analysis Engine Descriptor must have a
- <literal><delegateAnalysisEngineSpecifiers></literal>
- element. See <xref linkend="&tp;aes.aggregate.delegates"/>.</para>
- </listitem>
-
- <listitem><para>An Aggregate Analysis Engine Descriptor may provide a
- <literal><flowController></literal> element immediately
- following the
- <literal><delegateAnalysisEngineSpecifiers></literal>. <xref
- linkend="&tp;aes.aggregate.flow_controller"/>.</para></listitem>
-
- <listitem><para>Under the analysisEngineMetaData element, an Aggregate
- Analysis Engine Descriptor may specify an additional element --
- <literal><flowConstraints></literal>. See <xref
- linkend="&tp;aes.aggregate.flow_constraints"/>. Typically only one
- of <literal><flowController></literal> and
- <literal><flowConstraints></literal> are specified. If both are
- specified, the <literal><flowController></literal> takes
- precedence, and the flow controller implementation can use the information
- in specified in the <literal><flowConstraints></literal> as part of
- its configuration input.</para></listitem>
-
... 34721 lines suppressed ...