Very fast (and small) guide to using CODA

CODA is a development framework extending UIMA and specializing its capabilities for the acquisition of unstructured content and its projection into RDF datasets, according to desired modeling vocabularies.

In this page we provide information on how to use the facilities provided by CODA in your own applications, for the acquisition of content and for its triplification.

At the bottom of this page, we also give a short resume on how to call an UIMA Analysis Engine

CODA Deployments

CODA can be deployed and used according to three different scenarios:

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 of an host application. The required JARs alongside the metadata indicating their dependencies on external projects have been published on Maven Central. Provided that the IDE being used supports Maven, the only thing to be done is to add the following dependency to the POM of the host application:

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

In the host application, CODA can be instanciated by means of its appropriate factory:

			 
CODACore codaCore = CODAStandaloneFactory.getInstance(new File(bundlesDir), new File(felixCacheDir));

where:

bundlesDir is the directory containing the converters (as java libraries)
felixCacheDir is the directory in which felix (the OSGi framework adopted by CODA) 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.7</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, by giving references to an RDF dataset and by instructing CODA on which PEARL file to use for the triplification.

			
OWLArtModelFactory<Sesame2ModelConfiguration> fact = OWLArtModelFactory.createModelFactory(new ARTModelFactorySesame2Impl());
codaCore.initialize(owlModel, fact);
codaCore.setProjectionRulesModelAndParseIt(new File(prFilePath));

where:

owlModel is the ontology model created with a particular repository manager
prFilePath is the path of the PEARL 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 followig code snippet processes every single annotation contained into the JCas:

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

For more documentation about the API of 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. From version 0.11, Semantic Turkey actually features CODA by default and uses it for many of its Knowledge Acquisition tasks.

The CODA bundle can be manually deployed inside any OSGi container, but we also deployed on Maven a Karaf feature for automatically 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.7/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 might want to shutdown and restart Karaf to be 100% sure 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.7</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);