{"id":2247,"date":"2012-08-24T02:45:11","date_gmt":"2012-08-24T02:45:11","guid":{"rendered":"http:\/\/dalelane.co.uk\/blog\/?p=2247"},"modified":"2012-08-24T14:41:05","modified_gmt":"2012-08-24T14:41:05","slug":"using-uima-as-to-run-uima-annotators-in-parallel","status":"publish","type":"post","link":"https:\/\/dalelane.co.uk\/blog\/?p=2247","title":{"rendered":"Using UIMA-AS to run UIMA annotators in parallel"},"content":{"rendered":"

Overview<\/strong><\/p>\n

UIMA<\/a> stands for Unstructured Information Management Architecture. It’s an Apache technology that provides a framework and standard for building text analytics applications<\/a>. I’ve mentioned it before<\/a>.<\/p>\n

In this post, I want to talk about an area of UIMA which isn’t covered well in the documentation. <\/p>\n

I couldn’t find practical getting-started instructions for running UIMA-AS annotators in parallel. In this post I want to discuss why you might want to do it, and share some simple sample code to show how. <\/p>\n

Background – the UIMA pipeline<\/strong><\/p>\n

UIMA provides a framework for managing a text analytics application. You break up the analytics functionality into discrete pieces called annotators. UIMA takes care of moving a text document through an analytics engine: a pipeline containing a series of annotators.<\/p>\n

A document goes in one end of the pipeline, passes through a number of annotators, each of which adds some metadata to the document. What comes out the other side of the pipeline is an annotated copy of the document. <\/p>\n

<\/p>\n

By default, you get UIMA to run these annotators one at a time – one after another. <\/p>\n

Background – annotators in parallel<\/strong><\/p>\n

What if your annotators are quite slow – perhaps they take several seconds to run? <\/p>\n

If there is no dependency between any or all of your annotators, then maybe running them one at a time isn’t the most efficient approach. <\/p>\n

<\/p>\n

You can run all of them at the same time, in parallel. UIMA will merge the output from all of the annotators into a single annotated document. <\/p>\n

My sample code<\/strong><\/p>\n

I’ve written two sample UIMA apps<\/a>. Each demonstrates one of these approaches, to compare and contrast. <\/p>\n

They are divided into three eclipse projects. You can import them into an eclipse IDE<\/a>. <\/p>\n

The UIMA eclipse plugins are very helpful if you want to make changes to the XML configuration files, but they’re not essential. If you want them, there are instructions on how to install them at uima.apache.org<\/a>. <\/p>\n

I’ve added comments to the sample code<\/a> to explain how the apps work, but I’ll give an overview here. <\/p>\n

For these samples, I have five simple annotators. They sleep for six seconds, then add an empty annotation to the document CAS. <\/p>\n

public void process(JCas jCas) throws AnalysisEngineProcessException {\r\n\r\n  \/\/ sleep for six seconds...\r\n  try {\r\n    Thread.sleep(6000);\r\n  }\r\n  catch (InterruptedException e) {\r\n    e.printStackTrace();\r\n  }\r\n\r\n  \/\/ add an empty annotation to the CAS\r\n  jCas.addFsToIndexes(new AnnotationB(jCas));\r\n}<\/pre>\n
They do enough to prove that all five of them are being run, and that they all really contribute to the final annotated document. They take long enough to demonstrate the differences between these two approaches to running the pipeline. <\/p>\n
Sample code : running one annotator at a time<\/strong><\/p>\n
This can be done using UIMA. The first app uima-project<\/code> demonstrates this. <\/p>\n
An XML descriptor file (uima-project\/conf\/analysisEngine.xml<\/code>) specifies which annotators should be included in the pipeline, and which order they should be run in. <\/p>\n
<analysisEngineMetaData>\r\n\t<name>UIMA demonstration<\/name>\r\n\t<version>1.0<\/version>\r\n\t<flowConstraints>\r\n\t  <fixedFlow>\r\n\t    <node>annotatorA<\/node>\r\n\t    <node>annotatorB<\/node>\r\n\t    <node>annotatorC<\/node>\r\n\t    <node>annotatorD<\/node>\r\n\t    <node>annotatorE<\/node>\r\n\t  <\/fixedFlow>\r\n\t<\/flowConstraints><\/pre>\n
The descriptor file (uima-project\/conf\/analysisEngine.xml<\/code>) imports a descriptor for each individual annotator. <\/p>\n
<delegateAnalysisEngineSpecifiers>\r\n    <delegateAnalysisEngine key=\"annotatorA\">\r\n      <import location=\"annotatorA\/analysisEngine.xml\"\/>\r\n    <\/delegateAnalysisEngine>\r\n    <delegateAnalysisEngine key=\"annotatorB\">\r\n      <import location=\"annotatorB\/analysisEngine.xml\"\/>\r\n    <\/delegateAnalysisEngine>\r\n    <delegateAnalysisEngine key=\"annotatorC\">\r\n      <import location=\"annotatorC\/analysisEngine.xml\"\/>\r\n    <\/delegateAnalysisEngine>\r\n    <delegateAnalysisEngine key=\"annotatorD\">\r\n      <import location=\"annotatorD\/analysisEngine.xml\"\/>\r\n    <\/delegateAnalysisEngine>\r\n    <delegateAnalysisEngine key=\"annotatorE\">\r\n      <import location=\"annotatorE\/analysisEngine.xml\"\/>\r\n    <\/delegateAnalysisEngine>\r\n<\/delegateAnalysisEngineSpecifiers><\/pre>\n
Each of those imported descriptors identifies the Java class that implements the annotator, and specifies the metadata annotations that it can add to the output document. <\/p>\n
For example,
\nuima-project\/conf\/annotatorC\/analysisEngine.xml<\/code>:<\/p>\n
<annotatorImplementationName>com.dalelane.uima.annotators.DemoC<\/annotatorImplementationName>\r\n<analysisEngineMetaData>\r\n    <name>annotatorC<\/name>\r\n    <typeSystemDescription>\r\n      <types>\r\n        <typeDescription>\r\n          <name>com.dalelane.uima.annotators.gen.AnnotationC<\/name>\r\n          <description\/>\r\n          <supertypeName>uima.tcas.Annotation<\/supertypeName>\r\n        <\/typeDescription>\r\n      <\/types>\r\n    <\/typeSystemDescription><\/pre>\n
The overall pipeline is started from
\nuima-project\/src\/com\/dalelane\/uima\/serial\/Pipeline.java<\/code>. This reads in the descriptor file for the pipeline, and uses it to create an instance of a UIMA analysis engine. <\/p>\n
File descriptorFile = new File(\".\/conf\/analysisEngine.xml\");\r\nXMLInputSource descriptorSource = new XMLInputSource(descriptorFile);\r\n\r\nResourceSpecifier specifier = UIMAFramework.getXMLParser().parseResourceSpecifier(descriptorSource);\r\nanalysisEngine = UIMAFramework.produceAnalysisEngine(specifier);<\/pre>\n
To summarise:<\/p>\n
    \n
  1. The provided eclipse launch config starts a Java application 
    uima-project\/src\/com\/dalelane\/uima\/serial\/Application.java<\/code><\/li>\n
  2. The Java application creates 
    uima-project\/src\/com\/dalelane\/uima\/serial\/Pipeline.java<\/code> which creates a UIMA AnalysisEngine<\/code> <\/li>\n
  3. The analysis engine reads in the XML descriptor file uima-project\/conf\/analysisEngine.xml<\/code> <\/li>\n
  4. The analysis engine descriptor identifies the descriptors for each annotator 
    (e.g. uima-project\/conf\/annotatorC\/analysisEngine.xml<\/code>) <\/li>\n
  5. The descriptor for the annotator identifies the Java class which implements it 
    (e.g. uima-project\/src\/com\/dalelane\/uima\/annotators\/DemoC.java<\/code> )<\/li>\n<\/ol>\n
    The output from running the launch config shows that it takes about 30 seconds (5 annotators, each of which takes about 6 seconds) to process the document text. <\/p>\n
    Sample UIMA application - serial\r\n==================================\r\nAccessing analysis engine descriptor file\r\nCreating analysis engine\r\nProcessing document...\r\nTime spent in pipeline: 30121\r\nConfirming what was added...\r\n  Found: org.apache.uima.jcas.tcas.Annotation\r\n  Found: com.dalelane.uima.annotators.gen.AnnotationD\r\n  Found: com.dalelane.uima.annotators.gen.AnnotationC\r\n  Found: com.dalelane.uima.annotators.gen.AnnotationB\r\n  Found: com.dalelane.uima.annotators.gen.AnnotationA<\/pre>\n
      <\/p>\n
    Sample code : running all annotators at once<\/strong><\/p>\n
    This can be done using UIMA-AS<\/a> – a variant of UIMA that provides support for asynchronous scale out. The second app uima-as-project<\/code> demonstrates this. <\/p>\n
    To describe the approach at a high level, the idea is that you want to create five separate copies of the document to be analysed. Each of these copies can be run through a separate annotator at the same time. Once they’ve all finished, the output from all of the annotators can be collected together and merged to form the single output document.  <\/p>\n
     <\/p>\n
    Each of the annotators are run as a separate service. A by-product of this is that each can be run on a remote machine, and UIMA-AS manages moving the documents to\/from the remote services using JMS messaging<\/a>. <\/p>\n
    In my sample, I’m running them all on the same server, and using “localhost” to define the interactions. A JMS broker is still required for this. Instructions for starting the message broker is contained in uima-as-project\/README<\/code><\/p>\n
    Because the annotators are run as “remote” services, this introduces an extra step – the services need to be deployed before the pipeline can be started. <\/p>\n
    uima-as-project\/src\/com\/dalelane\/uima\/parallel\/Pipeline.java<\/code> deploys each of the services by specifying the deployment descriptors. <\/p>\n
    \/\/ creating UIMA analysis engine\r\nUimaAsynchronousEngine uimaAsEngine = new BaseUIMAAsynchronousEngine_impl();\r\n\r\n\/\/ preparing map for use in deploying services\r\nMap<String,Object> deployCtx = new HashMap<String,Object>();\r\ndeployCtx.put(UimaAsynchronousEngine.DD2SpringXsltFilePath, System.getenv(\"UIMA_HOME\") + \"\/bin\/dd2spring.xsl\");\r\ndeployCtx.put(UimaAsynchronousEngine.SaxonClasspath, \"file:\" + System.getenv(\"UIMA_HOME\") + \"\/saxon\/saxon8.jar\");\r\n\r\n\/\/ preparing map for use in deploying services\r\nuimaAsEngine.deploy(\".\/conf\/annotatorA\/deploy.xml\", deployCtx);\r\nuimaAsEngine.deploy(\".\/conf\/annotatorB\/deploy.xml\", deployCtx);\r\nuimaAsEngine.deploy(\".\/conf\/annotatorC\/deploy.xml\", deployCtx);\r\nuimaAsEngine.deploy(\".\/conf\/annotatorD\/deploy.xml\", deployCtx);\r\nuimaAsEngine.deploy(\".\/conf\/annotatorE\/deploy.xml\", deployCtx);<\/pre>\n
    The deployment descriptors for each annotator specify the name of the JMS endpoint that UIMA can use to send documents to the annotator for analysis, and the location of the analysis engine descriptor file that defines the annotator. <\/p>\n
    For example uima-as-project\/conf\/annotatorB\/deploy.xml<\/code><\/p>\n
    <analysisEngineDeploymentDescription>\r\n  <deployment protocol=\"jms\" provider=\"activemq\">\r\n    <service>\r\n      <inputQueue endpoint=\"AnnotatorBRemoteQ\" brokerURL=\"tcp:\/\/localhost:61616\"\/>\r\n      <topDescriptor>\r\n        <import location=\"analysisEngine.xml\"\/>\r\n      <\/topDescriptor>\r\n    <\/service>\r\n  <\/deployment>\r\n<\/analysisEngineDeploymentDescription><\/pre>\n
    The individual annotator descriptors are the same as in the first project uima-project<\/code>. <\/p>\n
    For example,
    \nuima-as-project\/conf\/annotatorB\/analysisEngine.xml<\/code><\/p>\n
    As before, it identifies the Java class which implements the annotator, and the types of annotations that it can create. <\/p>\n
    Once the UIMA services are deployed, the analysis engine descriptor for the overall pipeline can be deployed.<\/p>\n
    This is also done in
    \nuima-as-project\/src\/com\/dalelane\/uima\/parallel\/Pipeline.java<\/code><\/p>\n
    uimaAsEngine.deploy(\".\/conf\/deploy.xml\", deployCtx);<\/pre>\n
    The deployment descriptor for the overall pipeline (uima-as-project\/conf\/deploy.xml<\/code>), identifies how the pipeline can communicate with each of the “remote” services that make up it’s annotators. <\/p>\n
    <delegates>\r\n  <remoteAnalysisEngine key=\"annotatorA\">\r\n    <inputQueue brokerURL=\"tcp:\/\/localhost:61616\" endpoint=\"AnnotatorARemoteQ\"\/>\r\n    <serializer method=\"xmi\"\/>\r\n  <\/remoteAnalysisEngine>\r\n  <remoteAnalysisEngine key=\"annotatorB\">\r\n    <inputQueue brokerURL=\"tcp:\/\/localhost:61616\" endpoint=\"AnnotatorBRemoteQ\"\/>\r\n    <serializermethod=\"xmi\"\/>\r\n  <\/remoteAnalysisEngine>\r\n  <remoteAnalysisEnginekey=\"annotatorC\">\r\n    <inputQueue brokerURL=\"tcp:\/\/localhost:61616\" endpoint=\"AnnotatorCRemoteQ\"\/>\r\n    <serializer method=\"xmi\"\/>\r\n  <\/remoteAnalysisEngine>\r\n  <remoteAnalysisEnginekey=\"annotatorD\">\r\n    <inputQueue brokerURL=\"tcp:\/\/localhost:61616\" endpoint=\"AnnotatorDRemoteQ\"\/>\r\n    <serializer method=\"xmi\"\/>\r\n  <\/remoteAnalysisEngine>\r\n  <remoteAnalysisEngine key=\"annotatorE\">\r\n    <inputQueue brokerURL=\"tcp:\/\/localhost:61616\" endpoint=\"AnnotatorERemoteQ\"\/>\r\n    <serializer method=\"xmi\"\/>\r\n  <\/remoteAnalysisEngine>\r\n<\/delegates><\/pre>\n
    UIMA-AS provides a sample (AdvancedFixedFlowController<\/code>) that takes care of making the copies (a CAS Multiplier) of the document being analysed, and defines the sequence for the annotators to be run in parallel. <\/p>\n
    The deployment descriptor for my pipeline uses this sample.<\/p>\n
    <flowController key=\"AdvancedFixedFlowController\">\r\n    <import location=\"UIMA_HOME\/examples\/descriptors\/flow_controller\/AdvancedFixedFlowController.xml\"\/>\r\n<\/flowController>\r\n<analysisEngineMetaData>\r\n\t<configurationParameterSettings>\r\n\t  <nameValuePair>\r\n\t    <name>Flow<\/name>\r\n\t    <value>\r\n\t      <array>\r\n\t        <string>annotatorA,annotatorB,annotatorC,annotatorD,annotatorE<\/string>\r\n\t      <\/array>\r\n\t    <\/value>\r\n\t  <\/nameValuePair>\r\n\t<\/configurationParameterSettings><\/pre>\n
    It also identifies the descriptor file for running the analysis engine<\/p>\n
    <topDescriptor>\r\n    <import location=\"analysisEngine.xml\"\/>\r\n<\/topDescriptor><\/pre>\n
    The analysis engine descriptor file (uima-as-project\/conf\/analysisEngine.xml<\/code>), similar to before, identifies the annotators that make up the aggregate pipeline. <\/p>\n
    <delegateAnalysisEngineSpecifiers>\r\n  <delegateAnalysisEngine key=\"annotatorA\">\r\n    <import location=\"annotatorA\/remote.xml\"\/>\r\n  <\/delegateAnalysisEngine>\r\n  <delegateAnalysisEngine key=\"annotatorB\">\r\n    <import location=\"annotatorB\/remote.xml\"\/>\r\n  <\/delegateAnalysisEngine>\r\n  <delegateAnalysisEngine key=\"annotatorC\">\r\n    <import location=\"annotatorC\/remote.xml\"\/>\r\n  <\/delegateAnalysisEngine>\r\n  <delegateAnalysisEngine key=\"annotatorD\">\r\n    <import location=\"annotatorD\/remote.xml\"\/>\r\n  <\/delegateAnalysisEngine>\r\n  <delegateAnalysisEngine key=\"annotatorE\">\r\n    <import location=\"annotatorE\/remote.xml\"\/>\r\n  <\/delegateAnalysisEngine>\r\n<\/delegateAnalysisEngineSpecifiers><\/pre>\n
    These describe the way that the analysis engine can send documents to the remote services for analysis, using JMS. For example, uima-as-project\/conf\/annotatorB\/remote.xml<\/code> contains:<\/p>\n
    <customResourceSpecifierxmlns=\"http:\/\/uima.apache.org\/resourceSpecifier\">\r\n   <resourceClassName>org.apache.uima.aae.jms_adapter.JmsAnalysisEngineServiceAdapter<\/resourceClassName>\r\n   <parameters>\r\n     <parameter name=\"brokerURL\" value=\"tcp:\/\/localhost:61616\"\/>\r\n     <parameter name=\"endpoint\" value=\"AnnotatorBRemoteQ\"\/>\r\n     <parameter name=\"timeout\" value=\"5000\"\/>\r\n     <parameter name=\"getmetatimeout\" value=\"5000\"\/>\r\n     <parameter name=\"cpctimeout\" value=\"5000\"\/>\r\n   <\/parameters>\r\n<\/customResourceSpecifier><\/pre>\n
    To summarise:<\/p>\n
      \n
    1. The provided eclipse launch config starts a Java application uima-as-project\/src\/com\/dalelane\/uima\/parallel\/Application.java<\/code><\/li>\n
    2. The Java application creates an instance of uima-as-project\/src\/com\/dalelane\/uima\/parallel\/Pipeline.java<\/code><\/li>\n
    3. Pipeline.java<\/code> creates an UimaAsynchronousEngine<\/code> which deploys each of the annotator services, such as uima-as-project\/conf\/annotatorD\/deploy.xml<\/code><\/li>\n
    4. Each annotator’s deployment descriptor identifies the actual implementation of the annotator, giving the analysis engine XML uima-as-project\/conf\/annotatorD\/analysisEngine.xml<\/code> which in turn specifies the Java implementation class<\/li>\n
    5. Pipeline.java<\/code> then deploys the overall analysis engine pipeline as specified in the deployment descriptor uima-as-project\/conf\/deploy.xml<\/code> <\/li>\n
    6. This deployment descriptor identifies the way that the analysis engine should communicate with the remote services (by importing JMS specs such as uima-as-project\/conf\/annotatorC\/remote.xml<\/code>) and the order that they should be invoked in (using AdvancedFixedFlowController<\/code>)<\/li>\n<\/ol>\n
      The output from running the launch config shows that it takes about 6 seconds (5 annotators run in parallel, each of which takes about 6 seconds) to process the document text. <\/p>\n
      Full sample output is at
      \nuima-as-project\/example-output\/console.log<\/code><\/p>\n
      A summary is:<\/p>\n
      Sample UIMA application - parallel\r\n==================================\r\nDeploying UIMA services\r\nService:annotatorA Initialized. Ready To Process Messages From Queue:AnnotatorARemoteQ\r\nService:annotatorB Initialized. Ready To Process Messages From Queue:AnnotatorBRemoteQ\r\nService:annotatorC Initialized. Ready To Process Messages From Queue:AnnotatorCRemoteQ\r\nService:annotatorD Initialized. Ready To Process Messages From Queue:AnnotatorDRemoteQ\r\nService:annotatorE Initialized. Ready To Process Messages From Queue:AnnotatorERemoteQ\r\nDeploying analysis engine\r\nService:UIMA demonstration Initialized. Ready To Process Messages From Queue:DemoAnnotatorQueue\r\nInitialising UIMA client\r\nProcessing document...\r\nTime spent in pipeline: 6117\r\nConfirming what was added...\r\n  Found: org.apache.uima.cas.impl.AnnotationImpl\r\n  Found: org.apache.uima.cas.impl.AnnotationImpl\r\n  Found: org.apache.uima.cas.impl.AnnotationImpl\r\n  Found: org.apache.uima.cas.impl.AnnotationImpl\r\n  Found: org.apache.uima.cas.impl.AnnotationImpl\r\n  Found: org.apache.uima.cas.impl.AnnotationImpl<\/pre>\n
      Summary<\/strong><\/p>\n
      This isn’t definitive model code for using UIMA-AS. It’s intended more as a helpful first step into getting started with UIMA-AS – which there seems to be a shortage of documentation for. But there is a *lot* more to UIMA-AS, with a lot of settings and features to tweak. <\/p>\n
      Even with this simple example, you can see that output which takes 30 seconds to get using UIMA can be completed in 6 seconds if run in parallel, and how this can be done with UIMA-AS and a few extra config files. <\/p>\n","protected":false},"excerpt":{"rendered":"
      Overview UIMA stands for Unstructured Information Management Architecture. It’s an Apache technology that provides a framework and standard for building text analytics applications. I’ve mentioned it before. In this post, I want to talk about an area of UIMA which isn’t covered well in the documentation. I couldn’t find practical getting-started instructions for running UIMA-AS […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[7],"tags":[219,544,533,543],"class_list":["post-2247","post","type-post","status-publish","format-standard","hentry","category-code","tag-java","tag-jms","tag-uima","tag-uima-as"],"_links":{"self":[{"href":"https:\/\/dalelane.co.uk\/blog\/index.php?rest_route=\/wp\/v2\/posts\/2247","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/dalelane.co.uk\/blog\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/dalelane.co.uk\/blog\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/dalelane.co.uk\/blog\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/dalelane.co.uk\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=2247"}],"version-history":[{"count":0,"href":"https:\/\/dalelane.co.uk\/blog\/index.php?rest_route=\/wp\/v2\/posts\/2247\/revisions"}],"wp:attachment":[{"href":"https:\/\/dalelane.co.uk\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=2247"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dalelane.co.uk\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=2247"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dalelane.co.uk\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=2247"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}