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 18:29:55 UTC
svn commit: r1766094 - in
/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references: ./
src/docbook/ src/docbook/images/references/ref.resources/ src/image-source/
Author: schor
Date: Fri Oct 21 18:29:54 2016
New Revision: 1766094
URL: http://svn.apache.org/viewvc?rev=1766094&view=rev
Log:
[UIMA-5151] merge
Added:
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/images/references/ref.resources/
- copied from r1766092, uima/uimaj/trunk/uima-docbook-references/src/docbook/images/references/ref.resources/
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/ref.resources.xml
- copied unchanged from r1766092, uima/uimaj/trunk/uima-docbook-references/src/docbook/ref.resources.xml
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/image-source/
- copied from r1766092, uima/uimaj/trunk/uima-docbook-references/src/image-source/
Modified:
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/ (props changed)
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/ref.cas.xml
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/ref.compress.xml
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/ref.xml.component_descriptor.xml
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/references.xml
Propchange: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Fri Oct 21 18:29:54 2016
@@ -1,4 +1,4 @@
/uima/uimaj/branches/depend-on-july-9-build-tools/uima-docbook-references:963167-964468
/uima/uimaj/branches/depend-on-parent-pom-4/uima-docbook-references:961329-961745
/uima/uimaj/branches/filteredCompress-uima-2498/uima-docbook-references:1436573-1462257
-/uima/uimaj/trunk/uima-docbook-references:1690273-1693269,1757296-1757568
+/uima/uimaj/trunk/uima-docbook-references:1690273-1766092
Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/ref.cas.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/ref.cas.xml?rev=1766094&r1=1766093&r2=1766094&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/ref.cas.xml (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/ref.cas.xml Fri Oct 21 18:29:54 2016
@@ -1028,8 +1028,8 @@ FSIterator it = cas.createFilteredIterat
<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 to external strings) the
- XCAS form of the CAS (XCAS is an XML serialization of the CAS). The XCAS form is used for
+ 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>
@@ -1107,4 +1107,30 @@ FSIterator it = cas.createFilteredIterat
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
Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/ref.compress.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/ref.compress.xml?rev=1766094&r1=1766093&r2=1766094&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/ref.compress.xml (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/ref.compress.xml Fri Oct 21 18:29:54 2016
@@ -112,7 +112,8 @@ under the License.
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">
@@ -147,6 +148,8 @@ under the License.
<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>
@@ -156,6 +159,8 @@ Serialization.serializeWithCompression(c
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
@@ -183,6 +188,15 @@ Serialization.serializeWithCompression(c
</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.
Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/ref.xml.component_descriptor.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/ref.xml.component_descriptor.xml?rev=1766094&r1=1766093&r2=1766094&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/ref.xml.component_descriptor.xml (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/ref.xml.component_descriptor.xml Fri Oct 21 18:29:54 2016
@@ -1510,20 +1510,20 @@ uima.tcas.Annotation.</programlisting>
<para>Configuration Parameters are made available to annotator
implementations and applications by the following interfaces:
<itemizedlist spacing="compact" mark="circle">
- <listitem>
+ <listitem><para>
<literal>AnnotatorContext</literal> <footnote><para>Deprecated; use
UimaContext instead.</para></footnote> (passed as an argument to the
- initialize() method of a version 1 annotator)
+ initialize() method of a version 1 annotator)</para>
</listitem>
- <listitem>
+ <listitem><para>
<literal>ConfigurableResource</literal> (every Analysis Engine
- implements this interface)
+ implements this interface)</para>
</listitem>
- <listitem>
+ <listitem><para>
<literal>UimaContext</literal> (passed
as an argument to the initialize() method of a version 2 annotator) (you can get
this from any resource, including Analysis Engines, using the method
- <literal>getUimaContext</literal>()).
+ <literal>getUimaContext</literal>()).</para>
</listitem>
</itemizedlist></para>
@@ -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);
@@ -1973,40 +1974,42 @@ uima.tcas.Annotation.</programlisting>
file using the UTF-8 character encoding, and written in a style similar to that
of Java properties files.
<itemizedlist spacing="compact" mark="circle">
- <listitem>
+ <listitem><para>
Leading whitespace is ignored.
- </listitem>
- <listitem>
+ </para></listitem>
+ <listitem><para>
Comment lines start with '#' or '!'.
- </listitem>
- <listitem>
+ </para></listitem>
+ <listitem><para>
The key and value are separated by whitespace, '=' or ':'.
- </listitem>
- <listitem>
+ </para></listitem>
+ <listitem><para>
Keys must contain at least one character and only letters, digits, or the characters '. / - ~ _'.
- </listitem>
- <listitem>
+ </para></listitem>
+ <listitem><para>
If a line ends with '\' it is extended with the following line (after removing any
leading whitespace.)
- </listitem>
+ </para></listitem>
+ <listitem><para>
Whitespace is trimmed from both keys and values.
- <listitem>
+ </para></listitem>
+ <listitem><para>
Duplicate key values are ignored – once a value is assigned to a key it cannot be changed.
- </listitem>
- <listitem>
+ </para></listitem>
+ <listitem><para>
Values may reference other settings using the syntax '${key}'.
- </listitem>
- <listitem>
+ </para></listitem>
+ <listitem><para>
Array values are represented as a list of strings separated by commas or line breaks,
and bracketed by the '[ ]' characters. The value must start with an '[' and is
terminated by the first unescaped ']' which must be at the end of a line.
The elements of an array (and hence the array size) may be indirectly specified using
the '${key}' syntax but the brackets '[ ]' must be explicitly specified.
- </listitem>
- <listitem>
+ </para></listitem>
+ <listitem><para>
In values the special characters '$ { } [ , ] \' are treated as regular characters if
preceeded by the escape character '\'.
- </listitem>
+ </para></listitem>
</itemizedlist>
<programlisting><![CDATA[
key1 : value1
Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/references.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/references.xml?rev=1766094&r1=1766093&r2=1766094&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/references.xml (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uima-docbook-references/src/docbook/references.xml Fri Oct 21 18:29:54 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>