Author: burn
Date: Fri Feb 10 18:47:47 2012
New Revision: 1242881
URL: http://svn.apache.org/viewvc?rev=1242881&view=rev
Log:
UIMA-2370 Removed the 3-arg EntityProcessComplete callback by putting the list
of performance metrics in the UimaASProcessStatus object, accessed with
getPerformanceMetricsList. Updated documentation, and modified the pom to
generate Javadocs for the callback classes.
Modified:
uima/uima-as/trunk/uima-as-docbooks/src/docbook/ref.async.api.xml
uima/uima-as/trunk/uima-as/pom.xml
uima/uima-as/trunk/uimaj-as-core/src/main/java/org/apache/uima/aae/client/UimaASProcessStatus.java
uima/uima-as/trunk/uimaj-as-core/src/main/java/org/apache/uima/aae/client/UimaASProcessStatusImpl.java
uima/uima-as/trunk/uimaj-as-core/src/main/java/org/apache/uima/aae/client/UimaAsBaseCallbackListener.java
uima/uima-as/trunk/uimaj-as-core/src/main/java/org/apache/uima/aae/monitor/statistics/AnalysisEnginePerformanceMetrics.java
uima/uima-as/trunk/uimaj-as-jms/src/main/java/org/apache/uima/adapter/jms/client/BaseUIMAAsynchronousEngineCommon_impl.java
Modified: uima/uima-as/trunk/uima-as-docbooks/src/docbook/ref.async.api.xml
URL:
http://svn.apache.org/viewvc/uima/uima-as/trunk/uima-as-docbooks/src/docbook/ref.async.api.xml?rev=1242881&r1=1242880&r2=1242881&view=diff
==============================================================================
--- uima/uima-as/trunk/uima-as-docbooks/src/docbook/ref.async.api.xml (original)
+++ uima/uima-as/trunk/uima-as-docbooks/src/docbook/ref.async.api.xml Fri Feb
10 18:47:47 2012
@@ -309,38 +309,27 @@ under the License.
inform the application that a processCas request has completed. On
success aCAS object
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, the UIMA AS passes an object of type
<code>UimaASProcessStatus</code> as a second argument.
- It extends <code>EntityProcessStatus</code> and provides
<code>getCasReferenceId()</code>
- method to retrieve a unique
- id assigned to a CAS. To access this method the user code should
implement the following
- <programlisting>
- if ( aStatus instanceof UimaASProcessStatus ) {
- casReferenceId =
- ((UimaASProcessStatus)aStatus).getCasReferenceId();
- }
- </programlisting>
- </para>
- </listitem>
-
- <listitem>
- <para><code>entityProcessComplete(CAS aCas, EntityProcessStatus
aStatus, List<AnalysisEnginePerformanceMetrics>
componentMetricsList)</code>:
- Same as above with an additional <code>componentMetricsList</code>
argument. It provides per component performance breakdown as reported by UIMA
- aggregate. Useful for identifying how much time each component took
to analyze the CAS. The <code>AnalysisEnginePerformanceMetrics</code>
- class provides the following API:
- <itemizedlist>
- <listitem>
- <para><code>public String getName()</code>: identifies component
by name</para>
- </listitem>
- <listitem>
- <para><code>public String getUniqueName()</code>: identifies
component by unique name</para>
- </listitem>
- <listitem>
- <para><code>public long getAnalysisTime()</code>: time (in
millis) compnent spent analyzing the CAS</para>
- </listitem>
- <listitem>
- <para><code>public long getNumProcessed()</code>: total number
of CASes processed so far by the component</para>
- </listitem>
- </itemizedlist>
+ 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>
+ 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:
+ <itemizedlist>
+ <listitem>
+ <para><code>public String getName()</code>: identifies
component by name</para>
+ </listitem>
+ <listitem>
+ <para><code>public String getUniqueName()</code>: identifies
component by unique name</para>
+ </listitem>
+ <listitem>
+ <para><code>public long getAnalysisTime()</code>: time (in
millis) component spent analyzing the CAS</para>
+ </listitem>
+ <listitem>
+ <para><code>public long getNumProcessed()</code>: total number
of CASes processed so far by the component</para>
+ </listitem>
+ </itemizedlist>
+ See <xref linkend="ugr.ref.async.api.usage_getresults"></xref> for
a usage example.
</para>
</listitem>
@@ -444,24 +433,30 @@ uimaAsEngine.sendCAS(cas);
Asynchronous events resulting from the process Cas request are passed to
the registered listener.
<programlisting>
// Callback Listener. Receives event notifications from UIMA-AS.
-class MyStatusCallbackListener implements UimaASStatusCallbackListener {
+class MyStatusCallbackListener extends UimaAsBaseCallbackListener {
-// Method called when the processing of a Document is completed.
-public void entityProcessComplete(CAS aCas, EntityProcessStatus aStatus) {
- if (aStatus != null && aStatus.isException()) {
- List exceptions = aStatus.getExceptions();
- for (int i = 0; i < exceptions.size(); i++) {
- ((Throwable) exceptions.get(i)).printStackTrace();
+ // Method called when the processing of a Document is completed.
+ public void entityProcessComplete(CAS aCas, EntityProcessStatus aStatus) {
+ if (aStatus != null && aStatus.isException()) {
+ List exceptions = aStatus.getExceptions();
+ for (int i = 0; i < exceptions.size(); i++) {
+ ((Throwable) exceptions.get(i)).printStackTrace();
}
- uimaAsEngine.stop();
- return;
+ uimaAsEngine.stop();
+ return;
}
-// Process the retrieved Cas here
-// ...
+ // Process the retrieved Cas here
+ if ( aStatus instanceof UimaASProcessStatus ) {
+ String casReferenceId =
+ ((UimaASProcessStatus)aStatus).getCasReferenceId();
+ List<AnalysisEnginePerformanceMetrics> metrics =
+ ((UimaASProcessStatus)aStatus).getPerformanceMetricsList();
+ }
+ // ...
}
-// Add other required callback methods below...
+ // Add other required callback methods below...
}
</programlisting>
</para>
Modified: uima/uima-as/trunk/uima-as/pom.xml
URL:
http://svn.apache.org/viewvc/uima/uima-as/trunk/uima-as/pom.xml?rev=1242881&r1=1242880&r2=1242881&view=diff
==============================================================================
--- uima/uima-as/trunk/uima-as/pom.xml (original)
+++ uima/uima-as/trunk/uima-as/pom.xml Fri Feb 10 18:47:47 2012
@@ -392,26 +392,16 @@
../uimaj-as-core/src/main/java:../uimaj-as-activemq/src/main/java:../uimaj-as-camel/src/main/java:../uima-as-jms/src/main/java
</sourcepath>
<subpackages>org.apache.uima</subpackages>
- <excludePackageNames>
- *.uima.aae:
- *.aae.controller:
- *.aae.deploymentDescriptor:
- *.aae.error:
- *.aae.error.handler:
- *.aae.handler:
- *.aae.handler.input:
- *.aae.jmx:
- *.aae.message:
- *.aae.monitor:
- *.aae.monitor.statistics
- </excludePackageNames>
+
<excludePackageNames>*.aae.*</excludePackageNames>
<!-- add a few classes
in impl packages that are directly used by user code -->
<additionalparam>
${basedir}/../uimaj-as-core/src/main/java/org/apache/uima/aae/jmx/monitor/BasicUimaJmxMonitorListener.java
${basedir}/../uimaj-as-core/src/main/java/org/apache/uima/aae/jmx/monitor/JmxMonitorListener.java
${basedir}/../uimaj-as-core/src/main/java/org/apache/uima/aae/jmx/monitor/ServiceMetrics.java
${basedir}/../uimaj-as-core/src/main/java/org/apache/uima/aae/jmx/monitor/SingleLineUimaJmxMonitorListener.java
+
${basedir}/../uimaj-as-core/src/main/java/org/apache/uima/aae/monitor/statistics/AnalysisEnginePerformanceMetrics.java
${basedir}/../uimaj-as-core/src/main/java/org/apache/uima/aae/client/UimaAsynchronousEngine.java
+
${basedir}/../uimaj-as-core/src/main/java/org/apache/uima/aae/client/UimaAsBaseCallbackListener.java
${basedir}/../uimaj-as-core/src/main/java/org/apache/uima/aae/client/UimaASStatusCallbackListener.java
${basedir}/../uimaj-as-core/src/main/java/org/apache/uima/aae/client/UimaASProcessStatus.java
${basedir}/../uimaj-as-core/src/main/java/org/apache/uima/aae/error/ErrorResult.java
Modified:
uima/uima-as/trunk/uimaj-as-core/src/main/java/org/apache/uima/aae/client/UimaASProcessStatus.java
URL:
http://svn.apache.org/viewvc/uima/uima-as/trunk/uimaj-as-core/src/main/java/org/apache/uima/aae/client/UimaASProcessStatus.java?rev=1242881&r1=1242880&r2=1242881&view=diff
==============================================================================
---
uima/uima-as/trunk/uimaj-as-core/src/main/java/org/apache/uima/aae/client/UimaASProcessStatus.java
(original)
+++
uima/uima-as/trunk/uimaj-as-core/src/main/java/org/apache/uima/aae/client/UimaASProcessStatus.java
Fri Feb 10 18:47:47 2012
@@ -18,14 +18,46 @@
*/
package org.apache.uima.aae.client;
+import java.util.List;
+
+import org.apache.uima.aae.monitor.statistics.AnalysisEnginePerformanceMetrics;
import org.apache.uima.cas.CAS;
import org.apache.uima.collection.EntityProcessStatus;
+/**
+ * Contains information about the processing of a CAS by a UIMA-AS Analysis
Engine.
+ *
+ */
public interface UimaASProcessStatus extends EntityProcessStatus {
+ /**
+ * Gets the unique ID of the returned CAS
+ *
+ * @return the CAS ID
+ */
public String getCasReferenceId();
+ /**
+ * If the Analysis Engine has returned a new CAS this will get the unique ID
+ * of the input CAS that caused its creation.
+ * Will be null if the returned CAS is not new.
+ *
+ * @return the parent CAS ID or null if an input CAS has been returned
+ */
public String getParentCasReferenceId();
+ /**
+ * Gets the returned CAS
+ *
+ * @return the CAS
+ */
public CAS getCAS();
+
+ /**
+ * Gets a list of performance metrics containing, for each component in the
Analysis Engine,
+ * the performance breakdown reported by the AE
+ *
+ * @return a list of {@link AnalysisEnginePerformanceMetrics}
+ */
+ public List<AnalysisEnginePerformanceMetrics> getPerformanceMetricsList();
}
Modified:
uima/uima-as/trunk/uimaj-as-core/src/main/java/org/apache/uima/aae/client/UimaASProcessStatusImpl.java
URL:
http://svn.apache.org/viewvc/uima/uima-as/trunk/uimaj-as-core/src/main/java/org/apache/uima/aae/client/UimaASProcessStatusImpl.java?rev=1242881&r1=1242880&r2=1242881&view=diff
==============================================================================
---
uima/uima-as/trunk/uimaj-as-core/src/main/java/org/apache/uima/aae/client/UimaASProcessStatusImpl.java
(original)
+++
uima/uima-as/trunk/uimaj-as-core/src/main/java/org/apache/uima/aae/client/UimaASProcessStatusImpl.java
Fri Feb 10 18:47:47 2012
@@ -26,6 +26,7 @@ import java.util.Iterator;
import java.util.List;
import java.util.Map;
+import org.apache.uima.aae.monitor.statistics.AnalysisEnginePerformanceMetrics;
import org.apache.uima.cas.CAS;
import org.apache.uima.util.ProcessTrace;
@@ -52,6 +53,8 @@ public class UimaASProcessStatusImpl imp
private String parentCasId;
transient private CAS cas;
+
+ private List<AnalysisEnginePerformanceMetrics> performanceMetricsList;
public UimaASProcessStatusImpl(ProcessTrace p) {
this(p, null, null);
@@ -164,6 +167,14 @@ public class UimaASProcessStatusImpl imp
return parentCasId;
}
+ public void setPerformanceMetrics(List<AnalysisEnginePerformanceMetrics> pm)
{
+ performanceMetricsList = pm;;
+ }
+
+ public List<AnalysisEnginePerformanceMetrics> getPerformanceMetricsList() {
+ return performanceMetricsList;
+ }
+
/**
* Show class variable names and their current values. Uses reflection to
obtain a list of
* variables from the class.
Modified:
uima/uima-as/trunk/uimaj-as-core/src/main/java/org/apache/uima/aae/client/UimaAsBaseCallbackListener.java
URL:
http://svn.apache.org/viewvc/uima/uima-as/trunk/uimaj-as-core/src/main/java/org/apache/uima/aae/client/UimaAsBaseCallbackListener.java?rev=1242881&r1=1242880&r2=1242881&view=diff
==============================================================================
---
uima/uima-as/trunk/uimaj-as-core/src/main/java/org/apache/uima/aae/client/UimaAsBaseCallbackListener.java
(original)
+++
uima/uima-as/trunk/uimaj-as-core/src/main/java/org/apache/uima/aae/client/UimaAsBaseCallbackListener.java
Fri Feb 10 18:47:47 2012
@@ -18,9 +18,6 @@
*/
package org.apache.uima.aae.client;
-import java.util.List;
-
-import org.apache.uima.aae.monitor.statistics.AnalysisEnginePerformanceMetrics;
import org.apache.uima.cas.CAS;
import org.apache.uima.collection.EntityProcessStatus;
@@ -77,24 +74,6 @@ public abstract class UimaAsBaseCallback
}
/**
- * Called when the processing of each entity has completed.
- *
- * @param aCas
- * the CAS containing the processed entity and the analysis results
- * @param aStatus
- * the status of the processing. This object contains a record of
any Exception that
- * occurred, as well as timing information.
- * @param componentMetricsList
- * List containing CAS per component performance breakdown as
reported by UIMA
- * aggregate. Useful for identifying how much time each component
took to analyze
- * the CAS.
- */
- public void entityProcessComplete(CAS aCas, EntityProcessStatus aStatus,
List<AnalysisEnginePerformanceMetrics> componentMetricsList) {
- // If not overridden call the older version as it may have deen.
- entityProcessComplete(aCas, aStatus);
- }
-
- /**
* The callback used to inform the application that the CPC request has
completed. On success
* aStatus will be null; on failure use the EntityProcessStatus class to get
the details.
*
Modified:
uima/uima-as/trunk/uimaj-as-core/src/main/java/org/apache/uima/aae/monitor/statistics/AnalysisEnginePerformanceMetrics.java
URL:
http://svn.apache.org/viewvc/uima/uima-as/trunk/uimaj-as-core/src/main/java/org/apache/uima/aae/monitor/statistics/AnalysisEnginePerformanceMetrics.java?rev=1242881&r1=1242880&r2=1242881&view=diff
==============================================================================
---
uima/uima-as/trunk/uimaj-as-core/src/main/java/org/apache/uima/aae/monitor/statistics/AnalysisEnginePerformanceMetrics.java
(original)
+++
uima/uima-as/trunk/uimaj-as-core/src/main/java/org/apache/uima/aae/monitor/statistics/AnalysisEnginePerformanceMetrics.java
Fri Feb 10 18:47:47 2012
@@ -21,16 +21,22 @@ package org.apache.uima.aae.monitor.stat
import java.io.Serializable;
+/**
+ * Contains information about the processing of a CAS in a component of an
Analysis Engine
+ *
+ */
public class AnalysisEnginePerformanceMetrics implements Serializable {
- /**
- *
- */
+
private static final long serialVersionUID = 2355340461481671501L;
private String name;
private String uniqueName;
private long analysisTime;
private long numProcessed;
+ /**
+ * Creates a performance metrics instance
+ *
+ */
public AnalysisEnginePerformanceMetrics(String name, String uniqueName, long
analysisTime, long numProcessed ) {
this.name = name;
this.uniqueName = uniqueName;
@@ -38,18 +44,38 @@ public class AnalysisEnginePerformanceMe
this.numProcessed = numProcessed;
}
+ /**
+ * Gets the local name of the component as specified in the aggregate
+ *
+ * @return the name
+ */
public String getName() {
return name;
}
+ /**
+ * Gets the unique name of the component reflecting its location in the
aggregate hierarchy
+ *
+ * @return the unique name
+ */
public String getUniqueName() {
return uniqueName;
}
+ /**
+ * Gets the elapsed time the CAS spent analyzing this component
+ *
+ * @return time in milliseconds
+ */
public long getAnalysisTime() {
return analysisTime;
}
+ /**
+ * Gets the total number of CASes processed by this component so far
+ *
+ * @return number processed
+ */
public long getNumProcessed() {
return numProcessed;
}
Modified:
uima/uima-as/trunk/uimaj-as-jms/src/main/java/org/apache/uima/adapter/jms/client/BaseUIMAAsynchronousEngineCommon_impl.java
URL:
http://svn.apache.org/viewvc/uima/uima-as/trunk/uimaj-as-jms/src/main/java/org/apache/uima/adapter/jms/client/BaseUIMAAsynchronousEngineCommon_impl.java?rev=1242881&r1=1242880&r2=1242881&view=diff
==============================================================================
---
uima/uima-as/trunk/uimaj-as-jms/src/main/java/org/apache/uima/adapter/jms/client/BaseUIMAAsynchronousEngineCommon_impl.java
(original)
+++
uima/uima-as/trunk/uimaj-as-jms/src/main/java/org/apache/uima/adapter/jms/client/BaseUIMAAsynchronousEngineCommon_impl.java
Fri Feb 10 18:47:47 2012
@@ -1096,10 +1096,10 @@ public abstract class BaseUIMAAsynchrono
@SuppressWarnings("unchecked")
protected void notifyListeners(CAS aCAS, EntityProcessStatus aStatus, int
aCommand, String serializedComponentStats) {
if ( aCommand == AsynchAEMessage.Process) {
+
((UimaASProcessStatusImpl)aStatus).setPerformanceMetrics(deserializePerformanceMetrics(serializedComponentStats));
for (int i = 0; listeners != null && i < listeners.size(); i++) {
UimaAsBaseCallbackListener statCL = (UimaAsBaseCallbackListener)
listeners.get(i);
- statCL.entityProcessComplete(aCAS, aStatus,
-
deserializePerformanceMetrics(serializedComponentStats));
+ statCL.entityProcessComplete(aCAS, aStatus);
}
}
}
