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>