Author: schor
Date: Thu Dec 20 14:36:56 2018
New Revision: 1849397
URL: http://svn.apache.org/viewvc?rev=1849397&view=rev
Log:
[UIMA-5937] update pom version and scm, merge doc updates, record merge
Modified:
uima/uv3/uima-as-v3/trunk/uima-as-docbooks/ (props changed)
uima/uv3/uima-as-v3/trunk/uima-as-docbooks/pom.xml
uima/uv3/uima-as-v3/trunk/uima-as-docbooks/src/docbook/async.monitoring.and.tuning.xml
uima/uv3/uima-as-v3/trunk/uima-as-docbooks/src/docbook/async.tools.xml
uima/uv3/uima-as-v3/trunk/uima-as-docbooks/src/docbook/ref.async.api.xml
Propchange: uima/uv3/uima-as-v3/trunk/uima-as-docbooks/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Thu Dec 20 14:36:56 2018
@@ -1,2 +1,3 @@
/uima/uima-as/branches/depend-on-parent-pom-4/uima-as-docbooks:961335-961760
/uima/uima-as/branches/mavenAlign/uima-as-docbooks:941450-944455
+/uima/uima-as/trunk/uima-as-docbooks:1786000-1846922
Modified: uima/uv3/uima-as-v3/trunk/uima-as-docbooks/pom.xml
URL:
http://svn.apache.org/viewvc/uima/uv3/uima-as-v3/trunk/uima-as-docbooks/pom.xml?rev=1849397&r1=1849396&r2=1849397&view=diff
==============================================================================
--- uima/uv3/uima-as-v3/trunk/uima-as-docbooks/pom.xml (original)
+++ uima/uv3/uima-as-v3/trunk/uima-as-docbooks/pom.xml Thu Dec 20 14:36:56 2018
@@ -24,7 +24,7 @@
<parent>
<groupId>org.apache.uima</groupId>
<artifactId>uima-as-parent</artifactId>
- <version>3.0.0-SNAPSHOT</version>
+ <version>3.0.1-SNAPSHOT</version>
<relativePath>../uima-as-parent/pom.xml</relativePath>
</parent>
@@ -43,13 +43,13 @@
element, and just changing the following two properties -->
<scm>
<connection>
-
scm:svn:http://svn.apache.org/repos/asf/uima/uima-as/trunk/uima-as-docbooks
+
scm:svn:http://svn.apache.org/repos/asf/uima/uv3/uima-as-v3/trunk/uima-as-docbooks
</connection>
<developerConnection>
-
scm:svn:https://svn.apache.org/repos/asf/uima/uima-as/trunk/uima-as-docbooks
+
scm:svn:https://svn.apache.org/repos/asf/uima/uv3/uima-as-v3/trunk/uima-as-docbooks
</developerConnection>
<url>
- http://svn.apache.org/viewvc/uima/uima-as/trunk/uima-as-docbooks
+ http://svn.apache.org/viewvc/uima/uv3/uima-as-v3/trunk/uima-as-docbooks
</url>
</scm>
Modified:
uima/uv3/uima-as-v3/trunk/uima-as-docbooks/src/docbook/async.monitoring.and.tuning.xml
URL:
http://svn.apache.org/viewvc/uima/uv3/uima-as-v3/trunk/uima-as-docbooks/src/docbook/async.monitoring.and.tuning.xml?rev=1849397&r1=1849396&r2=1849397&view=diff
==============================================================================
---
uima/uv3/uima-as-v3/trunk/uima-as-docbooks/src/docbook/async.monitoring.and.tuning.xml
(original)
+++
uima/uv3/uima-as-v3/trunk/uima-as-docbooks/src/docbook/async.monitoring.and.tuning.xml
Thu Dec 20 14:36:56 2018
@@ -896,7 +896,7 @@ under the License.
</section>
<section id="ugr.async.mt.jmx_disable">
- <title>Disabling JMX in UIMA-AS</title>
+ <title>Disabling JMX in UIMA-AS JUnit tests</title>
<para>When opening JMX RMI port is not possible due to security
concerns, the UIMA-AS can start
without JMX support. To disable JMX please add the following as a JVM
argument -Duima.as.enable.jmx=false
</para>
Modified: uima/uv3/uima-as-v3/trunk/uima-as-docbooks/src/docbook/async.tools.xml
URL:
http://svn.apache.org/viewvc/uima/uv3/uima-as-v3/trunk/uima-as-docbooks/src/docbook/async.tools.xml?rev=1849397&r1=1849396&r2=1849397&view=diff
==============================================================================
--- uima/uv3/uima-as-v3/trunk/uima-as-docbooks/src/docbook/async.tools.xml
(original)
+++ uima/uv3/uima-as-v3/trunk/uima-as-docbooks/src/docbook/async.tools.xml Thu
Dec 20 14:36:56 2018
@@ -99,6 +99,9 @@ under the License.
<listitem><para>-uimaEeDebug true causes various debugging things to
happen, including
<emphasis>not</emphasis> deleting the generated spring file generated
by running dd2spring.
This parameter only affects deployments specified using the -d
parameter that follow it in the command line sequence.</para></listitem>
+ <listitem><para>-TargetServiceId specifies identifier of a service
which should process a CAS. This
+ identifier must match service's identifier. By default a service is
launched with an IP:PID
+ identifier but the identifier can be an arbitrary
String.</para></listitem>
</itemizedlist>
</para>
<para>The source code for this is in the class
Modified:
uima/uv3/uima-as-v3/trunk/uima-as-docbooks/src/docbook/ref.async.api.xml
URL:
http://svn.apache.org/viewvc/uima/uv3/uima-as-v3/trunk/uima-as-docbooks/src/docbook/ref.async.api.xml?rev=1849397&r1=1849396&r2=1849397&view=diff
==============================================================================
--- uima/uv3/uima-as-v3/trunk/uima-as-docbooks/src/docbook/ref.async.api.xml
(original)
+++ uima/uv3/uima-as-v3/trunk/uima-as-docbooks/src/docbook/ref.async.api.xml
Thu Dec 20 14:36:56 2018
@@ -69,6 +69,7 @@ under the License.
optionally be launched as separate processes on the same machine. In
either case logging
and JMX monitoring for native services are integrated with the other
UIMA components in the JVM.
</para>
+
</section>
@@ -85,7 +86,7 @@ under the License.
<programlisting>UimaAsynchronousEngine uimaAsEngine =
new BaseUIMAAsynchronousEngine_impl();</programlisting>
- The following is a short introduction to some important methods on this
class.
+ The following is a short introduction to some important methods on this
interface.
<itemizedlist>
<listitem>
@@ -129,6 +130,13 @@ under the License.
</listitem>
<listitem>
+ <para><code>void sendCAS(CAS aCAS, String serviceTargetId)</code>:
Sends a given CAS for analysis to a
+ specific instance of a UIMA-AS Service. This instance is identified
by a serviceTargetId.
+ The application is notified of responses or timeouts via
<code>entityProcessComplete()</code> method.
+ </para>
+ </listitem>
+
+ <listitem>
<para><code>void setCollectionReader(CollectionReader
aCollectionReader)</code>:
Plugs in an instantiated CollectionReader instance to use. This
method must be called before
<code>initialize</code>.
@@ -173,6 +181,16 @@ under the License.
</para>
</listitem>
+ <listitem>
+ <para><code>void sendAndReceiveCAS(CAS aCAS,
List<AnalysisEnginePerformanceMetrics> componentMetricsList, String
serviceTargetId)</code>:
+ Send a CAS to a specified instance of UIMA-AS service and wait for
response. On success aCAS contains the analysis results and componentMetricsList
+ contains per Analysis Engine performance breakdown. This breakdown
shows how much time each Analysis Engine
+ took to analyze the CAS. The method throws an exception on error.
Note that this interface cannot be used
+ to interface to a CAS Multiplier service, because it will block
until the parent comes back, and any child
+ CASes will be ignored.
+ </para>
+ </listitem>
+
<listitem>
<para><code>String aHandle deploy( String aDeploymentDescriptor, Map
anApplicationContext)</code>:
Deploys the UIMA-AS
@@ -281,6 +299,11 @@ under the License.
<para>password:(Optional) to authenticate user with ActiveMQ
broker. Default = null </para>
</listitem>
+ <listitem>
+ <para>TargetServiceId:(Optional) to target specific service
instance. Default = null </para>
+ </listitem>
+
+
</itemizedlist></para>
</section>
@@ -310,8 +333,10 @@ under the License.
will contain result of analysis; on failure the CAS will be in the
same state as
before it was sent to a service and aStatus will contain the cause
of failure. When calling
this method, UIMA AS passes an object of type
<code>UimaASProcessStatus</code> as a second argument.
- This class extends <code>EntityProcessStatus</code> and provides 4
additional methods: <code>getCAS(),
- getCasReferenceId(), getParentCasReferenceId() &
getPerfomanceMetricsList().</code>
+ This class extends <code>EntityProcessStatus</code> and provides 5
additional methods: <code>getCAS(),
+ getCasReferenceId(),
getParentCasReferenceId(),getServiceTargetId(), &
getPerfomanceMetricsList().</code>
+ The getServiceTargetId() returns an id of a service
that this client targeted for processing
+ a CAS. Targeting is optional and typically used for
checking if a service is viable.
The last method provides the per component performance
breakdown as reported by the UIMA
Analysis Engine which includes the elapsed time each component
spent analyzing the CAS.
The <code>AnalysisEnginePerformanceMetrics</code> class provides
the following API:
@@ -412,12 +437,12 @@ uimaAsEngine.addStatusCallbackListener(n
The following code shows how to establish connection to an existing
service:
<programlisting>//create Map to pass server URI and Endpoint parameters
Map<String,Object> appCtx = new HashMap<String,Object>();
-// Add Broker URI on local machine
-appCtx.put(UimaAsynchronousEngine.ServerUri, "tcp://localhost:61616");
-// Add Queue Name
-appCtx.put(UimaAsynchronousEngine.Endpoint, "RoomNumberAnnotatorQueue");
-// Add the Cas Pool Size
-appCtx.put(UimaAsynchronousEngine.CasPoolSize, 2);
+ // Add Broker URI on local machine
+ appCtx.put(UimaAsynchronousEngine.ServerUri, "tcp://localhost:61616");
+ // Add Queue Name
+ appCtx.put(UimaAsynchronousEngine.Endpoint, "RoomNumberAnnotatorQueue");
+ // Add the Cas Pool Size
+ appCtx.put(UimaAsynchronousEngine.CasPoolSize, 2);
//initialize
uimaAsEngine.initialize(appCtx);
@@ -434,6 +459,7 @@ cas.setDocumentText("Some text to pass t
uimaAsEngine.sendCAS(cas);
</programlisting>
</para>
+
</section>
<section id="ugr.ref.async.api.usage_getresults">
@@ -490,6 +516,35 @@ uimaAsEngine.deploy(service, appCtx);
</section>
+<section id="ugr.ref.async.api.usage_targetservice">
+ <title>Targeting specific service instance with the Client API</title>
+ <para>
+ Service targeting allows an application client to send CASes to a
specific instance of UIMA-AS service. This new
+feature can be used to determine if a service is viable or not and is capable
of processing a CAS. When a service starts, it creates a
+listener on its input queue which handles messages containing property
'TargetServiceId'. By default, the
+property value has a format <IP>:<PID>. If an incoming message
contains the property with a value matching
+service <IP>:<PID>, the listener will dequeue the message and
process a CAS contained therein. Optionally, the
+UIMA-AS service deployer may choose a custom value for the 'TargetServiceId'
property. To override the default
+include -DTargetServiceId=<value> on the service command line. The
<value> may be an arbitrary string with
+no spaces.
+
+The following shows how a client can target specific instance of a service
deployed with a default targeting
+support:
+
+
+<programlisting>//get an empty CAS from the Cas pool
+CAS cas = uimaAsEngine.getCAS();
+// Initialize it with input data
+cas.setDocumentText("Some text to pass to this service.");
+// Send Cas to a service running on 127.0.0.1 with PID 4444.
+uimaAsEngine.sendCAS(cas, "127.0.0.1:4444");
+ </programlisting>
+The above example uses an asynchronous client API method. For synchronous
invocations use
+<para><code>sendAndReceiveCAS(cas, componentMetricsList,
"127.0.0.1:4444")</code></para>
+
+ </para>
+ </section>
+
<section id="ugr.ref.async.api.usage_undeployservice">
<title>Undeploying a Service with the Client API</title>
<para>
