SimpleServer/src/docbook/simpleServerUserGuide.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 imgroot "images/simpleServerUserGuide/" >
]>
<!--
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.
-->
<book lang="en">

	<title>
		UIMA Simple Server User Guide
	</title>

	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
		href="../../target/docbook-shared/common_book_info.xml" />

<chapter id="sandbox.simpleServer">
  <title>Introduction</title>
  
  <para>The UIMA Simple Server makes results of UIMA processing available in a simple, XML-based
  format.  The intended use of the the Simple Server is to provide UIMA analysis as a REST service.
  The Simple Server is implemented as a Java Servlet, and can be deployed into any Servlet container
  (such as Apache Tomcat or Jetty).</para>
  
  <para>You can
  make your UIMA analysis available as follows:
  </para>
  
  <itemizedlist>
  <listitem>
  <para>Package you analysis as a UIMA PEAR file.</para>
  </listitem>
  <listitem>
  <para>Create a mapping file that tells the server what analysis results to show in which format.</para>
  </listitem>
  <listitem>
  <para>Create a WAR file for deployment into the servle container with appropriate WEB.xml.</para>
  </listitem>
  <listitem>
  <para>Deploy the WAR file into the server.</para>
  </listitem>
  </itemizedlist>
  
  <para>In the following, we will explain how to perform each of these steps.  </para>
  
  <section>
  <title>Quick start for the impatient</title>
  <para>If you're familiar with UIMA and servlets, you can start right here and get your first
  simple service running in a few minutes.  If not, not to worry.  We'll go over this in much more
  detail later on.  To follow the quick start guide, you will need to have:</para>

  <itemizedlist>
  <listitem>
  <para>Tomcat or some other servlet container installed.  Installing Tomcat is a breeze, see 
  <ulink url="http://tomcat.apache.org/"></ulink>.  For the purposes of this documentation, we have
  used Apache Tomcat 6.0.20, but other versions should work just as well if they're not too old.</para>
  </listitem>
  <listitem>
  <para>The latest Apache UIMA release, plus the Apache UIMA sandbox add-ons.  See
  <ulink url="http://uima.apache.org/downloads.cgi">the Apache UIMA download site</ulink>.
   </para>
  </listitem>
  <listitem>
  <para>Doing all this from Eclipse is convenient, but not required.  If you work with Eclipse, it is
  useful to use the Web Tools Platform.  Alternatively, just install the J2EE development
  version of Eclipse.  The screenshots for this documentation were done with the J2EE development
  version of Eclipse 3.5.0 (Galileo).</para>
  </listitem>
  </itemizedlist>
  
  <section>
  <title>Build a sample WAR file</title>

  <para>
  	Create a Web ARchive project in your favorite development
  	environment. We'll show you how to do this in Eclipse, but if you
  	don't use Eclipse, you'll figure out how to do this without.
  </para>

  <para>
  	Create a new "dynamic web project" called "simple-server-test" (or
  	whatever you like). Below is a series of screenshots that show how
  	to create such a project.
  </para>

  <screenshot>
    <mediaobject>
        <imageobject>
            <imagedata scale="100" format="JPG"
                fileref="&imgroot;new-web-project1.jpg" />
        </imageobject>
        <textobject>
            <phrase>New project dialog: select "dynamic web project"</phrase>
        </textobject>
    </mediaobject>
  </screenshot>
  
  <para>
  Below is the next step in the dialog, where you can set the project name and the intended
  runtime.  If you haven't done so yet, point Eclipse to your Tomcat installation.
  </para>

  <screenshot>
    <mediaobject>
        <imageobject>
            <imagedata scale="100" format="JPG"
                fileref="&imgroot;new-web-project2.jpg" />
        </imageobject>
        <textobject>
            <phrase>New project dialog: note server runtime</phrase>
        </textobject>
    </mediaobject>
  </screenshot>

  <para>
  	Hit finish next, accepting default settings for the rest of the project setup.
  </para>


  <para>
  We'll now describe what jar files you need to package in your WAR file for the application
  to run.  Note that these are jars that you will need for each and every UIMA service you
  deploy.  So if you deploy several different services into the same servlet container, you can
  also copy those jars to the shared lib directory of your servlet container: you then don't
  have to deploy them with each UIMA service.  However, for the purposes of this example, we
  <emphasis>will</emphasis> deploy the common jars with the WAR file.
  </para>

<para>
Below is list of the required files from the SimpleServer project.
</para>

  <itemizedlist>
  <listitem>
  <para><code>SimpleServer/lib/uima-simple-server.jar</code>
  </para>
  </listitem>
  <listitem>
  <para><code>SimpleServer/lib/xmlbeans-2.4.0.jar</code>
  </para>
  </listitem>
  <listitem>
  <para><code>SimpleServer/lib/geronimo-stax-api_1.0_spec-1.0.1.jar</code>
  </para>
  </listitem>
  <listitem>
  <para><code>SimpleServer/lib/uimaj-core-2.3.1.jar</code>
  </para>
  </listitem>
  </itemizedlist>
    
  <para>
  Copy all those jar files into the <code>WebContent/WEB-INF/lib</code> directory
  of your sample project.  Note how Eclipse automatically adds the jars to the Java build path under
  "Web App Libraries".
  </para>

  <para>
  We now need to add some actual analysis to run in our services.  For simplicity, we'll use
  the simple tokenizer that comes with the sandbox distribution.  In your sample project, create
  a new directory <code>WebContent/WEB-INF/resources</code>, and copy 
  <code>WhitespaceTokenizer/WhitespaceTokenizer.pear</code> there.  Your project layout should now
  look like this:
  </para>


  <screenshot>
    <mediaobject>
        <imageobject>
            <imagedata scale="100" format="JPG"
                fileref="&imgroot;sample-project-layout.jpg" />
        </imageobject>
        <textobject>
            <phrase>Sample web project layout</phrase>
        </textobject>
    </mediaobject>
  </screenshot>

  <para>
  Finally, you need to update your <code>web.xml</code> descriptor.
  Edit the <code>WebContent/WEB-INF/web.xml</code> file in your sample
  project.  Minimally, it should look like this:
  </para>
  
  <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
      http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
    id="WebApp_ID" version="2.5">
    <display-name>simple-server-test</display-name>
    <!-- Declare simple server test servlet -->
    <servlet>
        <servlet-name>simple-server-test</servlet-name>
        <servlet-class>
            org.apache.uima.simpleserver.servlet.SimpleServerServlet
        </servlet-class>
        <!-- Define the path to the tokenizer pear file -->
        <init-param>
            <param-name>PearPath</param-name>
            <param-value>
                WEB-INF/resources/WhitespaceTokenizer.pear
            </param-value>
        </init-param>
    </servlet>
    <!-- Declare the URL of the servlet -->
    <servlet-mapping>
        <servlet-name>simple-server-test</servlet-name>
        <url-pattern>/</url-pattern>
    </servlet-mapping>
</web-app>]]>
  </programlisting>
  
  <para>
  If you're doing all of this in Eclipse, and you have Tomcat configured as a server, you
  can now right-click your project and select "Run on server...".  This will start Tomcat
  and deploy web app.
  </para>
  
  <para>
  Alternatively, you can build a WAR file out of your project.  In Eclipse, right-click
  your project, and select "Export/Web/WAR file".  Save the WAR file to some location
  and deploy it in Tomcat (for example, using the admin web app that comes with Tomcat).
  </para>

  </section>
  
  
  <section>
  <title>Trying it out</title>
  
  <para>This is it, your first simple service should be ready to run.  Make sure
  Tomcat is running and direct your browser to the following URL: 
  <ulink url="http://localhost:8080/simple-server-test"></ulink>.
  You should see something like this:
  </para>
  
  <screenshot>
    <mediaobject>
        <imageobject>
            <imagedata scale="100" format="JPG"
                fileref="&imgroot;sample-app-info-page.jpg" />
        </imageobject>
        <textobject>
            <phrase>Info page of sample project</phrase>
        </textobject>
    </mediaobject>
  </screenshot>
  
  <para>
  This page basically explains what kind of requests this service can handle.
  To actually try some analysis, the service provides a simple html form
  you can use to test the service: 
  <ulink url="http://localhost:8080/simple-server-test?mode=form"></ulink>.
  </para>

  <screenshot>
    <mediaobject>
        <imageobject>
            <imagedata scale="100" format="JPG"
                fileref="&imgroot;sample-app-form-top.jpg" />
        </imageobject>
        <textobject>
            <phrase>Sample app html form</phrase>
        </textobject>
    </mediaobject>
  </screenshot>
  
  Now enter some text like "This is some sample text.", and at the bottom of the form,
  check the "XML document" button.  Hit the "Submit Query" button.
  
  <screenshot>
    <mediaobject>
        <imageobject>
            <imagedata scale="100" format="JPG"
                fileref="&imgroot;sample-app-form-bottom.jpg" />
        </imageobject>
        <textobject>
            <phrase>Sample app html form</phrase>
        </textobject>
    </mediaobject>
  </screenshot>
  
  You should see output like this:
  
  <screenshot>
    <mediaobject>
        <imageobject>
            <imagedata scale="100" format="JPG"
                fileref="&imgroot;sample-app-form-result.jpg" />
        </imageobject>
        <textobject>
            <phrase>Sample app html form result</phrase>
        </textobject>
    </mediaobject>
  </screenshot>
  
  <para>
  Use your browser's back button to go back to the form and experiment some more.
  Programmatic access to the service is described on the info page.  You can also
  look at the unit tests in the source code for how to use Apache's HttpClient
  to call UIMA simple services.  
  </para>
  
  </section>

  </section>
  
  
  
</chapter>

</book>