Version 2.3
Copyright © 2007 The Apache Software Foundation
Incubation Notice and Disclaimer. Apache UIMA is an effort undergoing incubation at the Apache Software Foundation (ASF). Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.
License and Disclaimer. The ASF licenses this documentation to you under the Apache License, Version 2.0 (the "License"); you may not use this documentation except in compliance with the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, this documentation and its contents are distributed under the License 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.
Trademarks. All terms mentioned in the text that are known to be trademarks or service marks have been appropriately capitalized. Use of such terms in this book should not be regarded as affecting the validity of the the trademark or service mark.
December, 2007
Table of Contents
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).
Once you have installed the Simple Server into a Servlet container of your choice, you can make your UIMA analysis available as follows:
Package you analysis as a UIMA PEAR file
Create a mapping file that tells the server what analysis results to show in which format
Deploy the PEAR file and the mapping file into the server.
In the following, we will explain how to perform each of these steps. We will also show you how to accomplish all of this in a concrete Servlet container, namely Apache Tomcat. Finally, we will describe how to use another Servlet container, Jetty, to test your application without deployment.
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:
Tomcat or some other servlet container installed. Installing Tomcat is a breeze, see http://tomcat.apache.org/.
The UIMA development environment set up (with Maven and all the other good stuff). For information on how to do that, see http://incubator.apache.org/uima/svn.html.
Doing all this from Eclipse is convenient, but not required. If you work with Eclipse, the Sysdeo Tomcat plugin is useful: http://www.eclipsetotale.com/tomcatPlugin.html. It lets you start and stop Tomcat from Eclipse, and allows you to debug your web apps in the Eclipse debugger.
If you haven't done so already, start by extracting the SimpleServer sandbox project from
Subversion, and build it with "mvn install". Copy the following files to the shared/lib
directory of your servlet container (i.e., Tomcat most likely; if the directory doesn't exist,
you can create it):
SimpleServer/lib/config-xml.jar
SimpleServer/lib/jsr173_1.0_api.jar
SimpleServer/lib/xbean.jar
SimpleServer/target/uimaj-simple-server.jar
One more file you need to copy there is uima-core.jar. You can either build it from
source, or grab it from the lib directory of an Apache UIMA distribution. Note: the
SimpleServer requires at least version 2.2.1 of UIMA.
Extract the WhitespaceTokenizer sandbox project from Subversion and build it with "mvn install". Note that the WhitespaceTokenizer depends on the PearPackagingMavenPlugin sandbox project, so you will need to extract and build that one as well.
When you have successfully built the WhitespaceTokenizer, you'll end up with a pear file in
WhitespaceTokenizer/target/WhitespaceTokenizer.pear. You'll need this file in the
next step.
Create a subdirectory webapps/uima in your Tomcat directory. This is where all
your simple services will live. Now create further subdirectories webapps/uima/resources
and webapps/uima/WEB-INF (webapp metadata) and webapps/uima/resources
(UIMA analysis).
Copy the whitespace tokenizer pear file from your workspace
(WhitespaceTokenizer/target/WhitespaceTokenizer.pear) to webapps/uima/resources
in your Tomcat directory. Copy a corresponding SimpleServer output mapping file
SimpleServer/src/main/resources/samples/WhitespaceTokenizer.xml also to
webapps/uima/resources.
Finally, copy SimpleServer/src/main/resources/samples/web.xml to
webapps/uima/WEB-INF.
This is it, your first simple service should be ready to run. Start (or restart) Tomcat and direct your browser to the following URL: http://127.0.0.1:8080/uima/ws-tokenizer?mode=form. Type in some text, check the "inline XML" radio button, and hit "Submit Query". You should see your text split up into sentences and tokens.