tags/uima-as-2.9.0/uima-as-docbooks/src/docbook/async.tools.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >
  %uimaents;
  ]>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
-->
<chapter id="ugr.async.tools">
  <title>Asynchronous Scaleout Tools</title>
  <section id="ugr.async.tools.overview">
    <title>Overview</title>
    <para>
    Several tools are available to use with UIMA-AS, including tools to start a JMS Broker,
    deploy a UIMA-AS service, start up a trivial client that reads documents from a directory 
    and sends them to a remote service, and query a named service for its meta data.
    </para>
    <para>Additionally, there is an extension to the Component Descriptor Editor that
    gives a form-based editor capability to edit deployment descriptors, along with wizards to 
    enable creating these kinds of descriptors.</para>
  </section> 
  <section id="ugr.async.tools.startBroker">
    <title>Starting a broker</title>
    <para>
    The <code>startBroker</code> script starts an ActiveMQ broker that can then be used to connect UIMA-AS
    clients to UIMA-AS Services.
    </para>
    <para>All arguments are optional; if none are given, the broker is started on the same
    machine using defaults.  See the script for details on how this can be configured.</para>
  </section>
  <section id="ugr.async.tools.deploying">
    <title>Deploying a UIMA-AS Service</title>
    <para>
    The <code>deployAsyncService</code> script deploys one or more UIMA-AS services.  
    Its arguments are one or more paths to deployment descriptors.
    </para>
    <para>
    The Java source code that does the deploying is in the class 
    <code>org.apache.uima.adapter.jms.service.UIMA_Service</code>, in the 
    uimaj-as-activemq project. 
    </para>
  </section>
  <section id="ugr.async.tools.client">
    <title>Running a UIMA-AS Client</title>
    <para>The runRemoteAsyncAE script is a sample application  
    that calls a Remote Asynchronous Analysis Engine on a collection of artifacts, represented by
    files in a directory.
    </para>
    <para>
      The command takes several arguments:
      <itemizedlist>
        <listitem>
          <para>brokerUrl - the url of the broker to use to connect to the service</para>
        </listitem>
        <listitem><para>service name - this is the endpoint name of the service, 
        and must match what is in the service's deployment descriptor. </para>
        </listitem>
      </itemizedlist>
      <para>The rest of the arguments are optional:</para>
      <itemizedlist>
        <listitem><para>-d Specifies a deployment descriptor. 
        The specified service will be deployed before processing begin, 
        and the service will be undeployed after processing completes. 
        Multiple -d entries can be given.</para>
        </listitem>
        <listitem><para>-c Specifies a CollectionReader descriptor. 
        The client will read CASes from the CollectionReader and 
        send them to the service for processing. If this option is omitted, 
        one empty CAS will be sent to the service 
        (useful for services containing a CAS Multiplier acting as a collection reader).</para></listitem>
        <listitem><para>-p Specifies CAS pool size, which determines the maximum number 
        of requests that can be outstanding.</para></listitem>
        <listitem><para>-f Specifies the initial FS heap size in bytes of each CAS in the pool.</para></listitem>
        <listitem><para>-o Specifies an Output Directory. 
        All CASes received by the client's CallbackListener will be serialized to XMI 
        in the specified OutputDir. If omitted, no XMI files will be output.</para></listitem>
        <listitem><para>-t Specifies a timeout period in seconds. 
        If a CAS does not return within this time period it is considered an error. 
        By default there is no timeout, so the client will wait forever.</para></listitem>
        <listitem><para>-i Causes the client to ignore errors returned from the service. 
        If not specified, the client terminates on the first error.</para></listitem>
        <listitem><para>-log Output details on each process request.</para></listitem>
        <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>
      </itemizedlist>
    </para>
    <para>The source code for this is in the class 
    <code>org.apache.uima.examples.as.RunRemoteAsyncAE.java</code>
    in the project <code>uimaj-as-activemq</code>.</para>
  </section>
    <section id="ugr.async.tools.getMeta">
    <title>Querying for a service's metadata</title>
    <para>
    The <code>getMetaRequest</code> script connects to an Active MQ broker and attempts to 
    query a particular named service's metadata.  This can be useful to confirm that 
    a service actually exists and is started, on a particular broker.
    </para>
    <para>This takes several arguments:
      <itemizedlist>
        <listitem><para>broker Uri - the Uri of the JMS broker used by the UIMA-AS Service</para></listitem>
        <listitem><para>service name - the name of the UIMA-AS service, same as the "endpoint" name.</para></listitem>
        <listitem><para>[optional] -verbose  - to output more information</para></listitem>
      </itemizedlist>
      There are other arguments which are normally not given; if needed, they are specified as
      Java -D (defined properties) arguments:
      <itemizedlist>
        <listitem><para>-Dactivemq.broker.jmx.port=xxx - override the port
        being used for JMX (defaults to 1099)</para></listitem>
        <listitem><para>-Dactivemq.broker.jmx.domain=xxx - use <code>xxx</code>
        as the JMX domain.  This normally never needs to be done unless multiple brokers are run on the same node 
        as is sometimes done for unit tests.</para></listitem>
      </itemizedlist>
    </para>
    <para>This command will connect to the specified broker at its JMX port and query
    to verify that this broker has the named service registered.  It then will 
    send a <code>getMeta</code> request to the named service and retrieve its metadata.</para>
    <para>The source code for this is in the class
    <code>org.apache.uima.examples.as.GetMetaRequest</code> in the project
    <code>uimaj-as-activemq</code>.</para>
  </section>
  
  
</chapter>