You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by sc...@apache.org on 2016/10/21 17:55:49 UTC
svn commit: r1766090 - in /uima/uimaj/trunk/uima-docbook-references/src:
docbook/ docbook/images/references/ref.resources/ image-source/
Author: schor
Date: Fri Oct 21 17:55:49 2016
New Revision: 1766090
URL: http://svn.apache.org/viewvc?rev=1766090&view=rev
Log:
[UIMA-5151]add chapter on UIMA Resource to ref manual. Fix one too-long-line in a program listing
Added:
uima/uimaj/trunk/uima-docbook-references/src/docbook/images/references/ref.resources/
uima/uimaj/trunk/uima-docbook-references/src/docbook/images/references/ref.resources/res_resource_kinds.png (with props)
uima/uimaj/trunk/uima-docbook-references/src/docbook/ref.resources.xml
uima/uimaj/trunk/uima-docbook-references/src/image-source/
uima/uimaj/trunk/uima-docbook-references/src/image-source/diagrams.pptx (with props)
Modified:
uima/uimaj/trunk/uima-docbook-references/src/docbook/ref.xml.component_descriptor.xml
uima/uimaj/trunk/uima-docbook-references/src/docbook/references.xml
Added: uima/uimaj/trunk/uima-docbook-references/src/docbook/images/references/ref.resources/res_resource_kinds.png
URL: http://svn.apache.org/viewvc/uima/uimaj/trunk/uima-docbook-references/src/docbook/images/references/ref.resources/res_resource_kinds.png?rev=1766090&view=auto
==============================================================================
Binary file - no diff available.
Propchange: uima/uimaj/trunk/uima-docbook-references/src/docbook/images/references/ref.resources/res_resource_kinds.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: uima/uimaj/trunk/uima-docbook-references/src/docbook/ref.resources.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/trunk/uima-docbook-references/src/docbook/ref.resources.xml?rev=1766090&view=auto
==============================================================================
--- uima/uimaj/trunk/uima-docbook-references/src/docbook/ref.resources.xml (added)
+++ uima/uimaj/trunk/uima-docbook-references/src/docbook/ref.resources.xml Fri Oct 21 17:55:49 2016
@@ -0,0 +1,186 @@
+<?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 instantions 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
Modified: uima/uimaj/trunk/uima-docbook-references/src/docbook/ref.xml.component_descriptor.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/trunk/uima-docbook-references/src/docbook/ref.xml.component_descriptor.xml?rev=1766090&r1=1766089&r2=1766090&view=diff
==============================================================================
--- uima/uimaj/trunk/uima-docbook-references/src/docbook/ref.xml.component_descriptor.xml (original)
+++ uima/uimaj/trunk/uima-docbook-references/src/docbook/ref.xml.component_descriptor.xml Fri Oct 21 17:55:49 2016
@@ -1955,7 +1955,8 @@ uima.tcas.Annotation.</programlisting>
<literal>produceAnalysisEngine</literal> method. In this case the
Java system property <emphasis>UimaExternalOverrides</emphasis> is ignored.
<programlisting> // Construct an analysis engine that uses two settings files
- Settings extSettings = UIMAFramework.getResourceSpecifierFactory().createSettings();
+ Settings extSettings =
+ UIMAFramework.getResourceSpecifierFactory().createSettings();
for (String fname : new String[] { "externalOverride.settings",
"default.settings" }) {
FileInputStream fis = new FileInputStream(fname);
Modified: uima/uimaj/trunk/uima-docbook-references/src/docbook/references.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/trunk/uima-docbook-references/src/docbook/references.xml?rev=1766090&r1=1766089&r2=1766090&view=diff
==============================================================================
--- uima/uimaj/trunk/uima-docbook-references/src/docbook/references.xml (original)
+++ uima/uimaj/trunk/uima-docbook-references/src/docbook/references.xml Fri Oct 21 17:55:49 2016
@@ -35,4 +35,5 @@ under the License.
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ref.compress.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ref.json.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ref.config.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ref.resources.xml"/>
</book>
Added: uima/uimaj/trunk/uima-docbook-references/src/image-source/diagrams.pptx
URL: http://svn.apache.org/viewvc/uima/uimaj/trunk/uima-docbook-references/src/image-source/diagrams.pptx?rev=1766090&view=auto
==============================================================================
Binary file - no diff available.
Propchange: uima/uimaj/trunk/uima-docbook-references/src/image-source/diagrams.pptx
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream