This tutorial will walk you through building a simple Eclipse RCP application that runs UIMA pipelines. It was written with Eclipse Ganymede 3.4 and Apache UIMA 2.2. It is assumed that you have basic knowledge of working with UIMA and Eclipse RCP. If you dont I suggest you go through a few tutorials on these. There are a lot of good tutorials out there, I would recommend the Vogel tutorial on Eclipse RCP and the Apache UIMA documentation as good resources..
The most common errors one encounters when trying to run UIMA pipelines from within an Eclipse RCP application are ClassNotFound errors. Most of these can be fixed using buddy loading policy.
2.1 Download either the source or binary zipped package from the UIMA download site.
2.2 Unzip the downloaded file to any location. We will refer to this location as <UIMAInstallationDIr>.
3.1 In Eclipse select File>New>Project
3.2 Select Plug-in Development>Plug-in from existing JAR archives
3.3 Click Add External... to add JARs from any location on your computer.
3.4 Navigate to <UIMAInstallationDIr>\lib and select all the jars in that directory. In our case, <UIMAInstallationDIr> is C:\apache-uima.. Click Next.
3.5 On the next page fill in the plugin properties. Uncheck the "Unzip the JAR archives into the project" checkbox. Click Finish.
4.1 Create an Eclipse RCP Plugin project using the wizard. Make sure that you check "Create a Java project" checkbox.
4.2 And dont forget to select "Yes" for the question "Would you like to create a Rich Client Application"
4.3 For this tutorial we will use the Hello RCP template. It is the simplest one.
4.4 Your workspace will now contain two projects as shown below. Your view might be different depending on any existing projects that you might have. Click on the "Launch An Eclipse Application" link to run the RCP application.
4.5 Currently we havent added anything to the default application so the window should look like this:
Since we will be using UIMA classes in our RCP application we first need to add our uimalibs plugin that contains the UIMA jars as a dependency.
5.1 In the Dependencies tab for the RCP applications manifest, Click Add to add a Dependency.
5.2 Select the 'uimalibs' plugin from the list.
The most common errors encountered in using UIMA from an Eclipse application are the ClassNotFound errors. This happens because of the way Eclipse loads classes, it has separate class loaders for each plugin. A good overview of Eclipse class loading can be found here or in the Resources list at the bottom of this page. The errors occur because when Eclipse requires to load any UIMA classes it delegates this job to the uimalibs plugin classloader. And the uimaplugins classloader can only see the classes in its own classpath or in the class path of its dependencies. We cannot add our RCP application as a dependency to the uimalibs plugin, because this will cause a cyclic dependency. Hence we use buddy policy to add our rcp application to the classpath of uimalibs in effect allowing its classloader to "see" the RCP applications classes.
6.1 Set buddy policy on the UIMA libraries plugin by adding the line 'Eclipse-BuddyPolicy: registered' to the end of the MANIFEST.MF file.
6.2 Register the RCP application as buddy to uimalibs by adding 'Eclipse-RegisterBuddy: uimalibs' line to it's MANIFEST.MF.
That's it with the setup. Now we are ready to finally write some code.
The easiest way to run an analysis engine within Eclipse is to first install it from a PEAR package. For the tutorial we will use the Whitespace Annotator that is included in the UIMA Annotator Addons package available at the UIMA download page. For instructions on installing a pear package see here.
8.1 When you install a UIMA AE using the PEAR installer, the AE descriptor is the <aename>pear.xml found in the installed directory root. Given the java.io.File reference to this descriptor we can create an Analysis Engine like this:
protected boolean setupAE(File aeFile) {
try {
ResourceManager rsrcMgr = null;
// Destroy old AE.
if (ae != null) {
destroyAe();
}
// get Resource Specifier from XML file
XMLInputSource in = new XMLInputSource(aeFile);
ResourceSpecifier specifier = UIMAFramework.getXMLParser()
.parseResourceSpecifier(in);
// create Analysis Engine here
if (rsrcMgr == null) {
ae = UIMAFramework.produceAnalysisEngine(specifier);
} else {
ae = UIMAFramework.produceAnalysisEngine(specifier,
rsrcMgr, null);
}
} catch (Exception e) {
e.printStackTrace();
return false;
}
return true;
}
8.2. We initialize a CAS object for the AE to process like this:
private CAS cas = null;
protected boolean setupCAS(AnalysisEngine analysisEngine) {
try {
this.cas = analysisEngine.newCAS();
} catch (ResourceInitializationException e) {
e.printStackTrace();
return false;
}
initCas();
return true;
}
private final void initCas() {
this.cas.setDocumentLanguage(this.language);
this.cas.setDocumentText("Some dummy text");
}
Finally running an AE is accomplished like this:
protected void internalRunAE(boolean doCasReset) {
try {
if (doCasReset) {
// Change to Initial view
this.cas = this.cas.getView(CAS.NAME_DEFAULT_SOFA);
this.cas.reset();
initCas();
}
ProcessTrace lastRunProcessTrace = this.ae.process(this.cas);
} catch (Exception e) {
e.printStackTrace();
} catch (Error e) {
StringBuffer buf = new StringBuffer();
buf.append("A severe error has occured:\n");
e.printStackTrace();
throw e;
}
}
The above code can be found in the AnalysisEngineLoader.java and AnalysisEngineProcessor.java files found in the tutorial source package.
The above example is not very practical as it does not allow the user to input the text to be processed. A more practical approach is to use a Collection Processing Manager(CPM). The CPM lets us specify a CollectionReader and a CAS Consumer in addition to the Analysis Engine.
The tutorial source code can be downloaded here. It contains the RCP plugin project created in the tutorial. It adds a wizard that prompts for the Analysis Engine descriptor file and then executes it on text that is hard coded. The project depends on the 'uimalibs' plugin project that is created in the first part of the tutorial. This is is not included in the zip file and you will have to create it to run the tutorial code.