Very fast (and small) guide to using CODA

CODA is based on UIMA (actually can be considered both an extension of UIMA and a specialization of its capabilities). At the bottom of this page, we thus provide a short introduction on how to call an UIMA Analysis Engine

CODA Deployments

CODA can be deployed and used acording to three different modalities:

as a standalone application
as a UIMA Analysis Engine (UIMA AE)
as a bundle in an OSGi environment

Running CODA in a standalone application

In this deployment scenario, CODA is used more or less as an ordinary Java library, which needs to be added to the application classpath. The required JARs alongside the metadata indicating their dependencies on external projects have been published on Maven Central. Provided that the build system of the application supports the resolution of dependencies from Maven Central, the preferred way to setup CODA is adding a dependency on the following artifact:

			 
<dependency>
    <groupId>it.uniroma2.art.coda</groupId>
    <artifactId>coda</artifactId>
    <version>1.0</version>
</dependency>

It is also available for manual download an archive containing the stuff that needs to be added to the classpath. This approach should be used as last resource, since the lack of explicit information about dependencies makes harder to detect possible conflicts at build-time.

Assuming that CODA is properly setup, it is time to see how the main application may interact with CODA. The very first step is to create an instance of the framework core class by means of the appropriate factory:

			 
CODACore codaCore = CODAStandaloneFactory.getInstance(targetBundlesFolder, targetFelixCache);

where:

targetBundlesFolder is the directory containing the converters (as java libraries)
targetFelixCache is the directory in which felix will store the cache for its bundles

The framework assumes that in the folder denoted by targetBundlesFolder there is at least the bundle providing the standard converter library. This bundle is available on Maven Central at the following coordinates:

			 
<dependency>
    <groupId>it.uniroma2.art.coda</groupId>
    <artifactId>coda-converters</artifactId>
    <version>1.0</version>
</dependency>

It is sufficient to download the bundle coda-converters and place it in the appropriate folder.

The newly created object needs to be initialized:

			
PreviousDecisions prevDecision = new PreviousDecisions();
File tempDir = new File(tempDirString);
codaCore.initialize(owlModel, prevDecision, tempDir);
codaCore.setProjectionRulesModel(new File(prFilePath));

where:

tempDirString is a directory in which CODA stores some temporary files
owlModel is the ontology model created with a particular repository manager
tempDir is another directory used by CODA to store some files
prFilePath is the path of the Projection Rule file

Then set the jcas by doing:

			
codaCore.setJCas(jcas)

Now it is time to process the UIMA annotations contained in the JCas which was set in CODA. CODA processes one annotation at a time. The code to process every single annotation contained into the JCas should be something similar to:

			
SuggOntologyCoda suggOntCoda;
while (codaCore.isAnotherAnnotationPresent()) {			
	suggOntCoda = codaCore.processNextAnnotation();
	List<ARTTriple> addedTripleList = new ArrayList<ARTTriple>();			
	for (ARTTriple artTriple : suggOntCoda.getARTTripleList()) {
		ARTResource subject = artTriple.getSubject();
		ARTURIResource predicate = artTriple.getPredicate();
		ARTNode object = artTriple.getObject();
		owlModel.addTriple(subject, predicate, object);
		addedTripleList.add(artTriple);
	}
	PreviousDecisionSingleElement prevDecSingleElem = new PreviousDecisionSingleElement(
		addedTripleList, suggOntCoda);
	prevDec.addPrevDecSingleElem(prevDecSingleElem);
}

For more documentation about the API on how to use CODA, please have a look at the javadoc

Running CODA as a UIMA AE

documentation coming...

Using a CODA as an OSGi service

CODA can be used as an OSGi bundle inside an OSGi container. Third party applications can thus exploit it to build more complex services based on CODA. An example is the Sheet2RDF extension for Semantic Turkey, where a datasheet-->RDF transformation system based on CODA is embedded inside the Knowledge Management and Acquisition platform Semantic Turkey.

The CODA bundle can be manually deployed inside any OSGi container, but we also deployed on Maven a Karaf feature for autmatically downloading it at run time from Maven Central. Here follow instructions for karaf 2.3.x, for which the feature has been developed.

Open Karaf in interactive mode (using the karaf batch/bash script) and then:

install the CODA feature file

features:addurl mvn:it.uniroma2.art.coda/coda-karaf/1.0/xml/features
check that the coda feature is available

features:list | grep coda
install the coda feature

features:install coda
check that the feature is correctly installed

features:list | grep coda
usually, if you came up to this step with no issue, CODA should be already upand running. However, you maight want to shutdown and restart Karaf to be 100% there is nothing appended after the downloads. For a clean exit, you may use the stop script, or run the following from the console:

shutdown now

The usage of CODA in this deployment scenario differs from the standalone mode mainly in the instantiation of the core framework class.

In the OSGi deployment, the proper factory is registered in the OSGi Service Registry under the key it.uniroma2.art.coda.osgi.bundle.CODAOSGiFactory. The obtained service should be then casted to the homonym interface, which is provided by the following artifact on Maven Central:

			 
<dependency>
    <groupId>it.uniroma2.art.coda</groupId>
    <artifactId>coda-osgi-bundle</artifactId>
    <version>1.0</version>
</dependency>

Assuming that the variable codaOSGiFactory holds a reference to the factory, the following code will instantiate CODA:

			 
codaOSGiFactory.getInstance(bundleContext)

where:

bundleContext is the BundleContext associated with the current bundle

Defining a contract and implementing converters

This is a somewhat advanced topic which is covered in a dedicated guide.

Calling a UIMA AE

This is a very small resume of how to install and use a UIMA pear (annotator). For the complete guide please refer to the official UIMA documentation site

Installation of a UIMA PEAR can be performed through the following code:

			 
File pearFile = new File(pearPathString);
File installDir = new File(installedPearString);
PackageBrowser instPear = PackageInstaller.installPackage(installDir, pearFile, true);
String descrPathString = instPear.getComponentPearDescPath();

The Analysis Engine and the relative JCas can be created by:

			 
ResourceSpecifier specifier = UIMAFramework.getXMLParser().parseResourceSpecifier(new XMLInputSource(descrPathString));
AnalysisEngine ae = UIMAFramework.produceAnalysisEngine(specifier);
JCas jcas = ae.newJCas();

Once the Analysis Engine is ready it can be invoked to analyze/annotate a text:

			
jcas.reset();
jcas.setDocumentText(textToBeAnnotatate);
ae.process(jcas);

It is possible to create and exectute an annotator using UIMAFIT:

			 
AnalysisEngine ae = AnalysisEngineFactory.createEngine(ANNOTATOR_TO_CREATE.class);
JCas jcas = JCasFactory.createJCas();
jcas.setDocumentText(textToBeAnnotatate);
SimplePipeline.runPipeline(jcas, ae);