Author: schor
Date: Thu Dec 20 14:36:56 2018
New Revision: 1849397

[UIMA-5937] update pom version and scm, merge doc updates, record merge

    uima/uv3/uima-as-v3/trunk/uima-as-docbooks/   (props changed)

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 @@

Modified: uima/uv3/uima-as-v3/trunk/uima-as-docbooks/pom.xml
--- 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 @@
-    <version>3.0.0-SNAPSHOT</version>
+    <version>3.0.1-SNAPSHOT</version>
@@ -43,13 +43,13 @@
        element, and just changing the following two properties -->  

 Thu Dec 20 14:36:56 2018
@@ -896,7 +896,7 @@ under the License.
   <section id="">
-    <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 

Modified: uima/uv3/uima-as-v3/trunk/uima-as-docbooks/src/docbook/
--- uima/uv3/uima-as-v3/trunk/uima-as-docbooks/src/docbook/ 
+++ uima/uv3/uima-as-v3/trunk/uima-as-docbooks/src/docbook/ 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 
     <para>The source code for this is in the class 

--- uima/uv3/uima-as-v3/trunk/uima-as-docbooks/src/docbook/ref.async.api.xml 
+++ 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.
@@ -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 
+      The following is a short introduction to some important methods on this 
@@ -129,6 +130,13 @@ under the License.
+          <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 
             Plugs in an instantiated CollectionReader instance to use. This 
method must be called before
@@ -173,6 +181,16 @@ under the License.
+       <listitem>
+          <para><code>void sendAndReceiveCAS(CAS aCAS, 
List&lt;AnalysisEnginePerformanceMetrics> componentMetricsList, String 
+            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>
           <para><code>String aHandle deploy( String aDeploymentDescriptor, Map 
             Deploys the UIMA-AS
@@ -281,6 +299,11 @@ under the License.
             <para>password:(Optional) to authenticate user with ActiveMQ 
broker. Default = null </para>
+          <listitem>
+            <para>TargetServiceId:(Optional) to target specific service 
instance. Default = null </para>
+          </listitem>
@@ -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() &amp; 
+            This class extends <code>EntityProcessStatus</code> and provides 5 
additional methods: <code>getCAS(), 
+            getCasReferenceId(), 
getParentCasReferenceId(),getServiceTargetId(), &amp; 
+                       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 
         <programlisting>//create Map to pass server URI and Endpoint parameters
 Map&lt;String,Object&gt; appCtx = new HashMap&lt;String,Object&gt;();
-// 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);
@@ -434,6 +459,7 @@ cas.setDocumentText("Some text to pass t
   <section id="ugr.ref.async.api.usage_getresults">
@@ -490,6 +516,35 @@ uimaAsEngine.deploy(service, appCtx);
+<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 &lt;IP&gt;:&lt;PID&gt;. If an incoming message 
contains the property with a value matching
+service &lt;IP&gt;:&lt;PID&gt;, 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=&lt;value&gt; on the service command line. The 
&lt;value&gt; 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 
+<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 with PID 4444. 
+uimaAsEngine.sendCAS(cas, "");
+    </programlisting>
+The above example uses an asynchronous client API method. For synchronous 
invocations use 
+<para><code>sendAndReceiveCAS(cas, componentMetricsList, 
+    </para>
+  </section>
   <section id="ugr.ref.async.api.usage_undeployservice">
     <title>Undeploying a Service with the Client API</title>

Reply via email to