You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by ea...@apache.org on 2008/11/28 21:31:31 UTC
svn commit: r721555 - in /incubator/uima/site/trunk/uima-website:
docs/doc-uimacpp-huh.html docs/images/getting-started/uimacppnative.png
xdocs/doc-uimacpp-huh.xml
Author: eae
Date: Fri Nov 28 12:31:31 2008
New Revision: 721555
URL: http://svn.apache.org/viewvc?rev=721555&view=rev
Log:
UIMA-1235 Incorporate changes suggested by Tong and Burn
Added:
incubator/uima/site/trunk/uima-website/docs/images/getting-started/uimacppnative.png (with props)
Modified:
incubator/uima/site/trunk/uima-website/docs/doc-uimacpp-huh.html
incubator/uima/site/trunk/uima-website/xdocs/doc-uimacpp-huh.xml
Modified: incubator/uima/site/trunk/uima-website/docs/doc-uimacpp-huh.html
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/docs/doc-uimacpp-huh.html?rev=721555&r1=721554&r2=721555&view=diff
==============================================================================
--- incubator/uima/site/trunk/uima-website/docs/doc-uimacpp-huh.html (original)
+++ incubator/uima/site/trunk/uima-website/docs/doc-uimacpp-huh.html Fri Nov 28 12:31:31 2008
@@ -175,7 +175,7 @@
<tr><td>
<blockquote>
<p>
- The UIMA C++ framework is designed to facilitate the creation of UIMA compliant Analysis Engines (AE) from analytics written in C++, or written in languages that can utilize C++ libraries. The UIMACPP SDK directly supports C++, and indirectly supports Perl, Python and Tcl languages via SWIG (http://www.swig.org/). Existing analytics in these languages can be wrapped with a UIMACPP annotator and integrated with other UIMA compliant analytics or UIMA-based applications.
+ The UIMA C++ framework is designed to facilitate the creation of UIMA compliant Analysis Engines (AE) from analytics written in C++, or written in languages that can utilize C++ libraries. The UIMACPP SDK directly supports C++, and indirectly supports Perl, Python and Tcl languages via SWIG (http://www.swig.org/). Existing analytic programs in any of these languages can be wrapped with a UIMACPP annotator and integrated with other UIMA compliant analytics or UIMA-based applications.
</p>
<p>
<table width="100%"><tr><td align="center" valign="middle">
@@ -207,20 +207,75 @@
<tr><td bgcolor="#9289A2">
<font color="#ffffff" face="arial,helvetica,sanserif">
- <a name="UIMACPP Example - Running a C++ analytic in a JVM Process"><strong>UIMACPP Example - Running a C++ analytic in a JVM Process</strong></a>
+ <a name="UIMACPP Sample Code"><strong>UIMACPP Sample Code</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
- When a UIMA component descriptor specifies
+ The UIMACPP package includes several sample UIMA C++ annotators and a sample C++ application that instantiates and uses a C++ annotator. Please go to the <a href="http://incubator.apache.org/uima/downloads.cgi">UIMA Download Page</a> and get the "UIMACPP Framework" package for Linux or Windows as appropriate. For best interaoperability with the Java version of UIMA, unpack into the $UIMA_HOME directory. See the README file in the top level directory for instructions on testing the package, and follow the links there to the sample code in C++, Perl, Python and Tcl.
+ </p>
+ <p>
+ A UIMA C++ annotator descriptor differs from a Java descriptor in the frameworkImplementation, specifying
<pre><frameworkImplementation>org.apache.uima.cpp</frameworkImplementation></pre>
-UIMA's Java framework instantiates a proxy annotator that transparently creates the UIMACPP component through the JNI. When the process(cas) method is called on the proxy, the CAS is binary serialized through the JNI into the native environment. The UIMA C++ annotator operates on the native copy of the CAS, and then the CAS is serialized back to the Java environment. See Figure 2.
+For a C++ annotator, the annotatorImplementationName specifies the name of a dynamic link library. UIMACPP will add the OS appropriate suffix and search the active dynamic libary path: LD_LIBRARY_PATH for Linux, PATH for Windows, and DYLD_LIBRARY_PATH for MacOSX. The suffix is not automatically added when the annotatorImplementationName includes a path.
+ </p>
+ <p>
+ An annotator library is derived from the UIMACPP class "Annotator" and must implement basic annotator methods. Annotators in Perl, Python and Tcl languages each use a C++ annotator to instantiate the appropriate interpreter, load the specified annotator source and call the annotator methods.
+ </p>
+ </blockquote>
+ </td></tr>
+ <tr><td><br/></td></tr>
+ </table>
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+
+
+ <tr><td bgcolor="#9289A2">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="UIMACPP Example - Running a C++ analytic in a Native Process"><strong>UIMACPP Example - Running a C++ analytic in a Native Process</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+ As in UIMA, UIMACPP includes application level methods to instantiate an Analysis Engine from a UIMA annotator descriptor, create a CAS using the AE type system, and call AE methods.
+ </p>
+ <p>
+ <b>examples/src/ExampleApplication.cpp</b> is a simple program that instantiates the specified annotator, reads a directory of txt files, and for each file sets the document text in a CAS and calls the AE process method. For annotator development, this program can be modified to create arbitrary CAS content to drive the annotator. Because the entire application is C++, standard tools such as gdb or devenv can be easily used for debugging.
+ </p>
+ <p>
+ <b>runAECpp</b> is a UIMA C++ application driver modeled closely after the Java tool <b>runAE</b>. Like ExampleApplication, this tool can read a directory of text files and exercise the given annotator. In addition, runAECpp can take input from XML format CAS files, call the annotator's process() method, and output the resultant CAS in XML format files. XML format CAS input files can be created from upstream UIMA components, or created manually with the content needed to develop and unit test an annotator.
+ </p>
+ <p>
+ <table width="100%"><tr><td align="center" valign="middle">
+ <img src="./images/getting-started/uimacppnative.png" alt="runAECpp - Native C++ Test Driver" border="0" />
+ <br>Figure 2 - runAECpp - Native C++ Test Driver.</br></td>
+ </tr></table>
+ </p>
+ </blockquote>
+ </td></tr>
+ <tr><td><br/></td></tr>
+ </table>
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+
+
+ <tr><td bgcolor="#9289A2">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="UIMACPP Example - Running a C++ analytic in a JVM Process"><strong>UIMACPP Example - Running a C++ analytic in a JVM Process</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+ Using the UIMA or UIMA AS packages, a UIMA C++ Analysis Engine can be used anywhere a UIMA Java AE can be used, for example, as a delegate in an aggregate AE, or as a UIMA service (using JMS, Vinci or SOAP protocols). When used in the Java framework, by default a C++ AE is instantiated and called via the JNI, running as part of the JVM process.
+ </p>
+ <p>
+ When a UIMA component descriptor specifies the frameworkImplementation as <b>org.apache.uima.cpp</b>, UIMA's Java framework instantiates a proxy annotator that transparently creates the UIMACPP component through the JNI. When the process(cas) method is called on the proxy, the CAS is binary serialized through the JNI into the native environment. The UIMA C++ annotator operates on the native copy of the CAS, and then the CAS is serialized back to the Java environment.
</p>
<p>
<table width="100%"><tr><td align="center" valign="middle">
<img src="./images/getting-started/uimacppthrujni.png" alt="Colocated UIMA C++ Component" border="0" />
- <br>Figure 2 - UIMA C++ Component Colocated with Java Framework.</br></td>
+ <br>Figure 3 - UIMA C++ Component Colocated with Java Framework.</br></td>
</tr></table>
</p>
<p>
@@ -255,49 +310,41 @@
<tr><td>
<blockquote>
<p>
- A UIMA C++ component can be run as a UIMA AS service using the UIMA C++ application <b>deployCppService</b>. This application instantiates the C++ component and then connects to the specified input queue managed by an ActiveMQ broker. In order to take advantage of multi-core hardware, deployCppService supports instantiating multiple copies of the C++ analytic, each in a different thread; this option requires the analytic to be designed for multithreaded operation.
+ With the UIMA AS package, a UIMA C++ component can be run as a UIMA AS service using the UIMA C++ application <b>deployCppService</b>. This application instantiates a UIMA C++ AE from the specified annotator descriptor, and then connects to the specified ActiveMQ broker and input queue. In order to take advantage of multi-core hardware, deployCppService supports instantiating multiple copies of the C++ analytic, each in a different thread; this option requires the analytic to be designed for multithreaded operation.
</p>
<p>
- Once deployed, the service can be utilized from UIMA applications and aggregate analysis engines in exactly the same way as other UIMA AS services. <!-- need link to online documenation --> See Figure 3.
+ Once deployed, the service can be utilized from UIMA applications and aggregate analysis engines in exactly the same way as other UIMA AS services written in Java. <!-- need link to online documenation -->
</p>
<p>
<table width="100%"><tr><td align="center" valign="middle">
<img src="./images/getting-started/deploycppservice.png" alt="Native UIMA AS Service" border="0" />
- <br>Figure 3 - UIMA C++ Component Running as Native UIMA AS Service.</br></td>
+ <br>Figure 4 - UIMA C++ Component Running as Native UIMA AS Service.</br></td>
</tr></table>
</p>
+ <br />
+ <p>
+ <b>Using Java to provide lifecycle management and monitoring</b>
+ </p>
<p>
- Java can provide lifecycle management, JMX monitoring and integrated logging of C++ native services when the UIMA AS Deployment Descriptor specifies
+ UIMA AS services written in Java are deployed using UIMA Deployment Descriptors. These descriptors, which specify the UIMA component descriptor to instantiate and the connectivity and error handling options, are used by the UIMA utility <b>deployAsyncService</b> to launch a Java service. Deployment Descriptors have special support for UIMA C++ services, with the ability to provide lifecycle management, JMX monitoring and integrated logging of C++ native services. This support is enabled when the UIMA AS Deployment Descriptor specifies
<pre><custom name="run_top_level_CPP_service_as_separate_process"/></pre>
-Note that in this case the Deployment Descriptor can also specify the environment for the native process, enabling multiple UIMA C++ components with different levels of UIMACPP to be managed by the same JVM. See Figure 4.
+in which case Java will launch deployCppService as a separate process on the same machine and establish socket connections for logging and monitoring.
+ </p>
+ <p>
+Note that in this case the Deployment Descriptor can also specify the environment for the native process using entries such as
+<pre><environmentVariable name="LD_LIBRARY_PATH">/home/user/apache-uima-as/uimacpp/lib</environmentVariable></pre>
+This feature enables multiple UIMA C++ components with different levels of UIMACPP to be managed by the same JVM.
</p>
<p>
<table width="100%"><tr><td align="center" valign="middle">
<img src="./images/getting-started/managedcppservice.png" alt="Managed Native Service" border="0" />
- <br>Figure 4 - Java Managed UIMA C++ Service.</br></td>
+ <br>Figure 5 - Java Managed UIMA C++ Service.</br></td>
</tr></table>
</p>
</blockquote>
</td></tr>
<tr><td><br/></td></tr>
</table>
- <table border="0" cellspacing="0" cellpadding="2" width="100%">
-
-
- <tr><td bgcolor="#9289A2">
- <font color="#ffffff" face="arial,helvetica,sanserif">
- <a name="Other UIMACPP Examples"><strong>Other UIMACPP Examples</strong></a>
- </font>
- </td></tr>
- <tr><td>
- <blockquote>
- <p>
- The UIMACPP package includes several sample UIMA C++ annotators and a sample C++ application that instantiates and uses a C++ annotator. Please go to the <a href="http://incubator.apache.org/uima/downloads.cgi">UIMA Download Page</a> and get the "UIMACPP Framework" package in zip or tar format. See the README file in the top level directory for instructions on installing the package, and follow the links there to the UIMA C++, Perl, Python and Tcl example annotators.
- </p>
- </blockquote>
- </td></tr>
- <tr><td><br/></td></tr>
- </table>
</blockquote>
</p>
</td></tr>
Added: incubator/uima/site/trunk/uima-website/docs/images/getting-started/uimacppnative.png
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/docs/images/getting-started/uimacppnative.png?rev=721555&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/uima/site/trunk/uima-website/docs/images/getting-started/uimacppnative.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: incubator/uima/site/trunk/uima-website/xdocs/doc-uimacpp-huh.xml
URL: http://svn.apache.org/viewvc/incubator/uima/site/trunk/uima-website/xdocs/doc-uimacpp-huh.xml?rev=721555&r1=721554&r2=721555&view=diff
==============================================================================
--- incubator/uima/site/trunk/uima-website/xdocs/doc-uimacpp-huh.xml (original)
+++ incubator/uima/site/trunk/uima-website/xdocs/doc-uimacpp-huh.xml Fri Nov 28 12:31:31 2008
@@ -37,7 +37,7 @@
<subsection name="UIMA C++ Overview">
<p>
- The UIMA C++ framework is designed to facilitate the creation of UIMA compliant Analysis Engines (AE) from analytics written in C++, or written in languages that can utilize C++ libraries. The UIMACPP SDK directly supports C++, and indirectly supports Perl, Python and Tcl languages via SWIG (http://www.swig.org/). Existing analytics in these languages can be wrapped with a UIMACPP annotator and integrated with other UIMA compliant analytics or UIMA-based applications.
+ The UIMA C++ framework is designed to facilitate the creation of UIMA compliant Analysis Engines (AE) from analytics written in C++, or written in languages that can utilize C++ libraries. The UIMACPP SDK directly supports C++, and indirectly supports Perl, Python and Tcl languages via SWIG (http://www.swig.org/). Existing analytic programs in any of these languages can be wrapped with a UIMACPP annotator and integrated with other UIMA compliant analytics or UIMA-based applications.
</p>
<p>
<table width="100%"><tr><td align="center" valign="middle">
@@ -62,16 +62,49 @@
</p>
</subsection>
- <subsection name="UIMACPP Example - Running a C++ analytic in a JVM Process">
+ <subsection name="UIMACPP Sample Code">
+ <p>
+ The UIMACPP package includes several sample UIMA C++ annotators and a sample C++ application that instantiates and uses a C++ annotator. Please go to the <a href="http://incubator.apache.org/uima/downloads.cgi">UIMA Download Page</a> and get the "UIMACPP Framework" package for Linux or Windows as appropriate. For best interaoperability with the Java version of UIMA, unpack into the $UIMA_HOME directory. See the README file in the top level directory for instructions on testing the package, and follow the links there to the sample code in C++, Perl, Python and Tcl.
+ </p>
<p>
- When a UIMA component descriptor specifies
+ A UIMA C++ annotator descriptor differs from a Java descriptor in the frameworkImplementation, specifying
<pre><frameworkImplementation>org.apache.uima.cpp</frameworkImplementation></pre>
-UIMA's Java framework instantiates a proxy annotator that transparently creates the UIMACPP component through the JNI. When the process(cas) method is called on the proxy, the CAS is binary serialized through the JNI into the native environment. The UIMA C++ annotator operates on the native copy of the CAS, and then the CAS is serialized back to the Java environment. See Figure 2.
+For a C++ annotator, the annotatorImplementationName specifies the name of a dynamic link library. UIMACPP will add the OS appropriate suffix and search the active dynamic libary path: LD_LIBRARY_PATH for Linux, PATH for Windows, and DYLD_LIBRARY_PATH for MacOSX. The suffix is not automatically added when the annotatorImplementationName includes a path.
+ </p>
+ <p>
+ An annotator library is derived from the UIMACPP class "Annotator" and must implement basic annotator methods. Annotators in Perl, Python and Tcl languages each use a C++ annotator to instantiate the appropriate interpreter, load the specified annotator source and call the annotator methods.
+ </p>
+ </subsection>
+
+ <subsection name="UIMACPP Example - Running a C++ analytic in a Native Process">
+ <p>
+ As in UIMA, UIMACPP includes application level methods to instantiate an Analysis Engine from a UIMA annotator descriptor, create a CAS using the AE type system, and call AE methods.
+ </p>
+ <p>
+ <b>examples/src/ExampleApplication.cpp</b> is a simple program that instantiates the specified annotator, reads a directory of txt files, and for each file sets the document text in a CAS and calls the AE process method. For annotator development, this program can be modified to create arbitrary CAS content to drive the annotator. Because the entire application is C++, standard tools such as gdb or devenv can be easily used for debugging.
+ </p>
+ <p>
+ <b>runAECpp</b> is a UIMA C++ application driver modeled closely after the Java tool <b>runAE</b>. Like ExampleApplication, this tool can read a directory of text files and exercise the given annotator. In addition, runAECpp can take input from XML format CAS files, call the annotator's process() method, and output the resultant CAS in XML format files. XML format CAS input files can be created from upstream UIMA components, or created manually with the content needed to develop and unit test an annotator.
+ </p>
+ <p>
+ <table width="100%"><tr><td align="center" valign="middle">
+ <img src="./images/getting-started/uimacppnative.png" alt="runAECpp - Native C++ Test Driver" border="0"/>
+ <br>Figure 2 - runAECpp - Native C++ Test Driver.</br></td>
+ </tr></table>
+ </p>
+ </subsection>
+
+ <subsection name="UIMACPP Example - Running a C++ analytic in a JVM Process">
+ <p>
+ Using the UIMA or UIMA AS packages, a UIMA C++ Analysis Engine can be used anywhere a UIMA Java AE can be used, for example, as a delegate in an aggregate AE, or as a UIMA service (using JMS, Vinci or SOAP protocols). When used in the Java framework, by default a C++ AE is instantiated and called via the JNI, running as part of the JVM process.
+ </p>
+ <p>
+ When a UIMA component descriptor specifies the frameworkImplementation as <b>org.apache.uima.cpp</b>, UIMA's Java framework instantiates a proxy annotator that transparently creates the UIMACPP component through the JNI. When the process(cas) method is called on the proxy, the CAS is binary serialized through the JNI into the native environment. The UIMA C++ annotator operates on the native copy of the CAS, and then the CAS is serialized back to the Java environment.
</p>
<p>
<table width="100%"><tr><td align="center" valign="middle">
<img src="./images/getting-started/uimacppthrujni.png" alt="Colocated UIMA C++ Component" border="0"/>
- <br>Figure 2 - UIMA C++ Component Colocated with Java Framework.</br></td>
+ <br>Figure 3 - UIMA C++ Component Colocated with Java Framework.</br></td>
</tr></table>
</p>
<p>
@@ -95,35 +128,38 @@
<subsection name="UIMACPP Example - Running a C++ analytic as a Native UIMA AS Service">
<p>
- A UIMA C++ component can be run as a UIMA AS service using the UIMA C++ application <b>deployCppService</b>. This application instantiates the C++ component and then connects to the specified input queue managed by an ActiveMQ broker. In order to take advantage of multi-core hardware, deployCppService supports instantiating multiple copies of the C++ analytic, each in a different thread; this option requires the analytic to be designed for multithreaded operation.
+ With the UIMA AS package, a UIMA C++ component can be run as a UIMA AS service using the UIMA C++ application <b>deployCppService</b>. This application instantiates a UIMA C++ AE from the specified annotator descriptor, and then connects to the specified ActiveMQ broker and input queue. In order to take advantage of multi-core hardware, deployCppService supports instantiating multiple copies of the C++ analytic, each in a different thread; this option requires the analytic to be designed for multithreaded operation.
</p>
<p>
- Once deployed, the service can be utilized from UIMA applications and aggregate analysis engines in exactly the same way as other UIMA AS services. <!-- need link to online documenation --> See Figure 3.
+ Once deployed, the service can be utilized from UIMA applications and aggregate analysis engines in exactly the same way as other UIMA AS services written in Java. <!-- need link to online documenation -->
</p>
<p>
<table width="100%"><tr><td align="center" valign="middle">
<img src="./images/getting-started/deploycppservice.png" alt="Native UIMA AS Service" border="0"/>
- <br>Figure 3 - UIMA C++ Component Running as Native UIMA AS Service.</br></td>
+ <br>Figure 4 - UIMA C++ Component Running as Native UIMA AS Service.</br></td>
</tr></table>
</p>
+ <br></br>
<p>
- Java can provide lifecycle management, JMX monitoring and integrated logging of C++ native services when the UIMA AS Deployment Descriptor specifies
+ <b>Using Java to provide lifecycle management and monitoring</b>
+ </p>
+ <p>
+ UIMA AS services written in Java are deployed using UIMA Deployment Descriptors. These descriptors, which specify the UIMA component descriptor to instantiate and the connectivity and error handling options, are used by the UIMA utility <b>deployAsyncService</b> to launch a Java service. Deployment Descriptors have special support for UIMA C++ services, with the ability to provide lifecycle management, JMX monitoring and integrated logging of C++ native services. This support is enabled when the UIMA AS Deployment Descriptor specifies
<pre><custom name="run_top_level_CPP_service_as_separate_process"/></pre>
-Note that in this case the Deployment Descriptor can also specify the environment for the native process, enabling multiple UIMA C++ components with different levels of UIMACPP to be managed by the same JVM. See Figure 4.
+in which case Java will launch deployCppService as a separate process on the same machine and establish socket connections for logging and monitoring.
+ </p>
+ <p>
+Note that in this case the Deployment Descriptor can also specify the environment for the native process using entries such as
+<pre><environmentVariable name="LD_LIBRARY_PATH">/home/user/apache-uima-as/uimacpp/lib</environmentVariable></pre>
+This feature enables multiple UIMA C++ components with different levels of UIMACPP to be managed by the same JVM.
</p>
<p>
<table width="100%"><tr><td align="center" valign="middle">
<img src="./images/getting-started/managedcppservice.png" alt="Managed Native Service" border="0"/>
- <br>Figure 4 - Java Managed UIMA C++ Service.</br></td>
+ <br>Figure 5 - Java Managed UIMA C++ Service.</br></td>
</tr></table>
</p>
</subsection>
-
- <subsection name="Other UIMACPP Examples">
- <p>
- The UIMACPP package includes several sample UIMA C++ annotators and a sample C++ application that instantiates and uses a C++ annotator. Please go to the <a href="http://incubator.apache.org/uima/downloads.cgi">UIMA Download Page</a> and get the "UIMACPP Framework" package in zip or tar format. See the README file in the top level directory for instructions on installing the package, and follow the links there to the UIMA C++, Perl, Python and Tcl example annotators.
- </p>
- </subsection>
</section>