In short, Elmo is for anyone planning to develop Semantic Web applications using JavaBeans and Sesame.

Elmo is Java library for Semantic Web applications. Elmo allows developers to create applications that work with RDF/OWL knowledge bases at the level of ontologies, using JavaBeans, instead of working on the level of RDF/OWL languages, using generic Resource Objects.

Elmo provides support for developing applications using the most popular Web ontologies, including FOAF, RSS 1.0 and Dublin Core. Elmo contains a static object model for these ontologies as well as some tools to work with them, for example an RDF crawler and a smusher for FOAF data. Elmo gives dynamic access to data in other ontologies and is also easily extendible with new static models.

Elmo uses the popular Sesame storage and query facility as a backend, representing a good choice for working with the lightweight ontologies that are most commonly used in web applications, both in terms of features and scalability.

The Elmo object model builds on a simple concept: each ontological class has a matching Java class in the library, using the same name. Classes from a single ontology are collected in subpackages of the org.openrdf.elmo.model package. For example, classes of the FOAF model can be found in the Java package org.openrdf.elmo.model.foaf.

Properties of an instance can be set or read by calling getter/setter methods on the Java object. Inheritance is used where there is a subclass relationship between two ontological classes. Unlike RDF(S), Java does not support multiple inheritance, so each Java class has only one superclass.

Let's start with the simplest possible example, where we create a foaf:Person object, set some of its properties and lastly write it out as RDF. This example and the others to follow can be found in the Elmo source distribution in the package org.openrdf.elmo.example.

ElmoSession session = new ElmoSession(); 
URI jackURI = session.createURI("http://www.jackandjill.example.org/#jack"); 
         
Person jack = (Person) session.getInstance(jackURI, Person.class); 
 
jack.setName(session.createLiteral("Jack"));
jack.setMbox(session.createURI("mailto:jack@jackandjill.example.org"));
jack.setMbox(session.createURI("mailto:jack@work.example.org")); 
   
RdfDocumentWriter writer = new AbbreviatedRdfXmlWriter(System.out); 
writer.setNamespace("foaf", Person.FOAF_NS); 
writer.startDocument(); 
new PersonWriter().writeRDF(writer, jack); 
writer.endDocument(); 

The output looks like this:

<?xml version="1.0" encoding="UTF-8"?> 
<rdf:RDF 
 xmlns:foaf="http://xmlns.com/foaf/0.1/" 
 xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
 xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"> 
<foaf:Person rdf:about="http://www.jackandjill.example.org/#jack"> 
 <foaf:name>Jack</foaf:name> 
 <foaf:mbox rdf:resource="mailto:jack@work.example.org"/> 
 <foaf:mbox rdf:resource="mailto:jack@jackandjill.example.org"/> 
</foaf:Person> 
</rdf:RDF>

In this example, we first create an in-memory ElmoSession by calling the default constructor. An ElmoSession provides methods to acquire Elmo objects and manages their interaction with the underlying repository. Read more about the ElmoSession.

Next, we create the URI that will identify the new Person object. ElmoSession also provides factory methods for creating Sesame BNode (blank nodes) and Literal. (In the Sesame object model, BNode and URI are subinterfaces of the more generic Resource interface and they are implemented as BNodeImpl and URIImpl. For more details, see the openrdf model documentation.) Using the factory methods of ElmoSession is the preferred way to create these objects.

Next, we create an instance of the Person class by calling another session method, getInstance. This version of the method takes the id of the resource and the Java class to be returned as identifiers. (Note: Elmo objects should not be created using their public constructors.) The Sesame Resource object that was used as identifier can be later retrieved using the getResource method.

Once we have a reference to a Person object, we can set some properties. In this case, we state the name of the Person and two of his email addresses. Setter methods either take instances of Literal or Resource as arguments or other model objects. (This latter case will be demonstrated later on.)

Lastly, we write out an RDF/XML serialization of this Person by creating an instance of RdfDocumentWriter and of PersonWriter. RdfDocumentWriter is a RIO interface and it is implemented by a number of serializers capable of producing various RDF syntaxes including RDF/XML, N3, N-Triples and Turtle. For more information, see the RIO documentation. PersonWriter is an Elmo Writer that can serialize Person objects in various ways.

Note that for nicer formatting, we set the namespace abbreviation for FOAF. Namespaces and URI objects for properties can be accessed as static members of the model classes.

The objects we have created so far were in memory representations. However, it is also possible to use a persistant Sesame repository implementation as backend.(Sesame has a variety of repository implementations using databases, the file system, memory etc. ) This repository will then be used to retrieve the values of properties as well as store the values set.

The ElmoRepository class has a number of static methods to access Sesame repositories in different ways. ElmoRepository is wrapper for the SesameRepository class of the Sesame API and exposes all methods of the underlying SesameRepository. For additional information, please see the documentation for SesameRepository.

The easiest way is to access a remote repository; this can be done by providing the URL of the server and the name of the repository. The obtained ElmoRepository is then used when instantiating the ElmoSession:

//Repository-based ElmoSession 
ElmoRepository repository = ElmoRepository.getRepository(new URL("http://localhost:8080/sesame"), "test"); 
ElmoSession session = new ElmoSession(repository); 

While it's possible to instantiate model objects one-by-one using the getInstance method shown above, it is more common to retrieve a set of instances matching a query. This is done by the getInstances method, which in its most simple form requires only the query and the class to be returned:

String query = "SELECT person FROM {person} <" + Person.FOAF_NAME + "> {name} WHERE name=\"Jack\""; 
Collection persons = session.getInstances(query, Person.class); 
Iterator it = persons.iterator();

A limitation is that the query must return a single column and cannot use a '*' in the select clause. It is of course also possible execute queries directly on the ElmoRepository and instantiate resources one-by-one as iterating over the result.

The Person class (and some other classes) also have convenience methods to retrieve all Person instances in a repository or to retrieve instances matching a certain description. See the JavaDoc for more detail.

Important to note about repository based ElmoSessions is that all settter methods write directly to the repository by default. This automatic commit feature can be disabled by using the setAutoCommit method. Once autocommit is disabled, changes can be committed by calling the commit method and they can be discarded with rollback. Get methods do not return set values unless they are committed.

Note: The Elmo API requires a Sesame server installation with a version number of 1.2 or higher.

Consider also the following example using the RSS model. In this example, we create an RSS channel and put two items on it. Lastly, as before, we write out the contents of the channel as RDF.

ElmoSession session = new ElmoSession(); 
   
Resource channelURI = session.createURI("http://rss.example.org"); 
 
Channel channel = (Channel) session.getInstance(channelURI, Channel.class); 
   
channel.setTitle(session.createLiteral("Test channel")); 
channel.setLink(session.createLiteral("http://www.cs.vu.nl/")); 
channel.setDescription(session 
    .createLiteral("This is the description of this channel.")); 
   
DCResource dcChannel = (DCResource) session.getInstance(channelURI, DCResource.class); 
dcChannel.setSubject(session.createLiteral("Semantic Web")); 
   
   
Item item = (Item) session.getInstance(session 
    .createURI("http://rss.example.org#1"), Item.class); 
item.setTitle(session.createLiteral("Our latest news item")); 
item.setDescription(session 
    .createLiteral("This is the description of the latest news item")); 
channel.addItem(item); 
 
item = (Item) session.getInstance(session 
    .createURI("http://rss.example.org#2"), Item.class); 
item.setTitle(session.createLiteral("An older news item")); 
item.setDescription(session 
    .createLiteral("This is the description of the older news item")); 
channel.addItem(item); 

RdfDocumentWriter writer = new AbbreviatedRdfXmlWriter(System.out); 
writer.setNamespace("rss", Channel.RSS_NS); 
writer.setNamespace("dc", DCResource.DC_NS); 

writer.startDocument(); 
new ChannelWriter().writeRDF(writer, channel); 
writer.endDocument(); 
 

You might note that the Channel class has a convenience method for adding an item to the channel (addItem), which also takes care of creating a Seq instance (if this is the first item) and linking it to the channel. There is also a convenience method for accessing the items that have been added (getItemsAsList).

We can also see in this example how multiple typing is used Elmo. Namely, we create an instance of the Dublin Core ontology with the same URI as the channel and then set a value for the dc:subject property. We don't have to serialize this resource separately because the writeRDF method of the Channel class takes care of that. (RSS 1.0 is often used in combination with Dublin Core.)

On a minor note: we also have to use the AbbreviatedRdfXmlWriter to serialize RSS channels, because the RSS 1.0 specification requires this format. In particular, RSS 1.0 documents should also validate against the DTD of XML-based versions of RSS, because many existing tools processs RSS 1.0 using XML parsers. There are other, soft rules of RSS validation (such as the recommended number of items per channel or the allowed length of descriptions) and for this reason we recommend checking the validity of the produced RDF with one (or preferable more) of the many RSS validators available on the Web.

Elmo provides JavaBeans to access popular ontologies and is easily expanded to support more, see Extending the object model for more information. Elmo also provides a dynamic interface to access resources, using Apache's beanutils' DynaBean interface.

DynaResource has a one getter and one setter method, #get(String) and #set(String,Object) respectively. The property name (String) is the local name of the property. If there are multiple properties with the same local name the behaviour is not guaranteed and DynaResource should not be used to access that property. The return Object of the getter and the Object of the setter are based on the ontology of the class types of the resource. A Resource wrapped by a DynaResource will return/expect one of three values: Set, List, or DynaResource as described in the following table.

If the property is a Literal, a DynaResource is still returned. Its value can be accessed by using the #as(Class) method. Otherwise the DynaResource is read-only and provides five properties: label, language, datatype, type, and locale; they return String, String, model.URI, Collection of rdfs.Class and Locale, respectively.

The expected property type can be retrieved at runtime with the method:

DynaResource#getDynaClass().getDynaProperty(String).getType()

See the DynaResourceTest class for more examples.

The primary function of the ElmoSession is to provide performance improvements by (a memory-sensitive) caching and by expanding queries. The limits of query expansion are application dependent: while executing a more general query than necessary often improves performance by speeding up future access, it can also slow down the application temporarily or result in overly large result sets that break memory limits. For this reason query expansion can be regulated.

The getInstances method mentioned above can also take a third boolean parameter that specifies whether all properties of all instances should be preloaded. Another form of query expansion occurs when a property is read on an instance that was the result of a query. In that case, that property is read for all instances that were also the result of that query. This kind of query expansion can be enabled or disabled by calling the setExpandQuery method of the ElmoSession.

ElmoSession also implements the String BeanFactory. Providing #getBean(String,Class) as an alternative to #getInstance(URI,Class). Also included is the class ElmoSessionFactory, which implements String's FactoryBean. This class provides abstract ElmoSession creation. It can be used as follows:

ElmoSessionFactory factory = new ElmoSessionFactory();
factory.setConfigFile("config.xml");
factory.setRepositoryId("main");
factory.init();
ElmoSession session = factory.getSession();
      

Note: All ElmoSessions created with the same factory will share the same schema cache, which reduces multiple session overhead.

The object model of Elmo is easily extensible with additional classes to support your own ontologies.

Again, the best way to understand how things work is to consider an example. Below is the full source of the foaf:Group class:

package org.openrdf.elmo.model.foaf; 
 
public class Group extends FOAFResource { 
 
    final static URI FOAF_GROUP = new URIImpl(FOAF_NS + "Group"); 
 
    public static final URI ABOUT = FOAF_GROUP; 
     
    /* 
     * Properties with a domain of foaf:Group 
     */ 
 
    final static URI FOAF_MEMBER = new URIImpl(FOAF_NS + "member"); 
 
    public Group() { 
        super(); 
    } 
 
    public Group(String uri) { 
        super(uri); 
    } 
 
 
    //MEMBER 
    public Set getMember() throws QueryEvaluationException { 
        return _session.getInstances(_id, FOAF_MEMBER, Agent.class); 
    } 
 
    public void setMember(Agent value) { 
        _session.addStatement(_id, FOAF_MEMBER, value.getResource()); 
    } 
    
}

Model classes are all subclasses of Elmo's Resource class from the rdfs subpackage (not to be confused with Sesame Resource interface). This class represents the RDF(S) notion of a Resource with all the properties defined in RDF(S) such as label, comment and seeAlso.

In the case of Group, there is another class between Resource and Group in the inheritance hierarchy: FOAFResource. This class doesn't have an ontological equivalent but it is a placeholder for all the properties that the FOAF ontology defines for all resources (these are name, homepage and depiction at the time of writing).

Subclasses of Resource should implement two public constructors, one default, and one with a single String parameter, that call the constructor of the superclass. These constructors are used to instantiate blank nodes.

Next, a get and a set methods are defined for the only property of foaf:Group, which is foaf:member. The getter method should call the getInstances method of ElmoSession that takes the id of the resource, the property (a URI) and the class of values to be returned. In this case, the range of the property is another model class, foaf:Agent. The setter method calls the addStatement method of ElmoSession with the id, the property (the same URI) and the Sesame Value to be set. In the case of an Elmo resource (as here) the Sesame Resource to be added can be retrieved by calling getResource.

The Elmo scutter is a generic RDF crawler that follows rdfs:seeAlso links in RDF documents, which typically point to other relevant RDF sources on the web. The Elmo scutter is based on original code by Matt Biddulph for Jena.

RDF(S) seeAlso is also the mechanism used to connect FOAF profiles and thus (given a starting location) the scutter allows to collect FOAF profiles from the Web. Several advanced features are provided to support this scenario:

The data collected by the scutter is stored in a Sesame repository (see configuration below). We recommend using a Native RDF repository for scuttering, because it provides the best performance for uploads.

The Scutter is available as a Java class as well as a Java servlet. The servlet provides access to all of the above features, except for filtering (which requires programming) and it can be deployed by placing the Elmo.war file in the web application directory of a Servlet/JSP container.

The servlet initialization parameters to be specified in the web.xml descriptor file are listed below. An example web.xml file is provided in the war file.

The request parameters to the server are listed in the table below. For convenience, there is an html file provided in the distribution for calling various operations on the servlet.

A custom filtering of statements can be implemented by setting an instance of the StatementFilter interface using the setStatementFilter method of the Scutter class. See the JavaDoc for more details.

The task of the Elmo smusher is to find equivalent instances in large sets of data. This is a very common problem when processing collections of FOAF profiles as several sources on the Web may describe a the same individual using different identifiers or blank nodes (which are always assumed to be different). While the servlet provided is specific to smushing foaf:Person instances, the underlying mechanism is generic

The smusher uses instances of ResourceComparator for comparing instances. Implementations of ResourceComparator are given for foaf:Person and swrc:Publication.

The smusher reports the results (matching instances) by calling methods on registered listeners. Listeners implement the SmusherListener interface. Two implementations of SmusherListener are provided: one writes out results in text, while the other represents matches using the owl:sameAs relationship and uploads such statements to a Sesame repository. While Sesame does not directly support OWL semantics, the semantics of this relationship (the equivalence of property values) can be easily axiomatized using Sesame's custom rule language.

The servlet can be deployed by placing the elmo.war file in the web application directory of a Servlet/JSP container.

The servlet initialization parameters to be specified in the web.xml descriptor file are listed below. An example web.xml file is provided in the war file.

The smusher servlet has no request parameter. As the service is invoked it starts smushing on the repository defined in the web application descriptor (web.xml).

Note that the smusher is currently not iterative, i.e. smushing is performed only once. You may want to repeat smushing in case new matches can be found on the basis of what has been inferred in a previous round.

The task of the Elmo validator is to validate instances using Java. Programmatic validation is often necessary, since not every requirement in ontologies can be represented in RDF or OWL. For example, validation can be used to check common mistakes in FOAF profiles such as providing a Literal as the value of the mbox property.

Again, the validation mechanism is more general and available from Java by calling the validate method on classes that support validation, such as the Person class in the foaf subpackage. Validation is implemented using a listener pattern: various levels of validation errors are reported by calling methods on the listener passed in to the validate method. Listeners implement the AdminListener interface of Sesame. Standard implementations of this interface are provided with Sesame, e.g. for writing out errors as plain text, HTML or XML.

There is also servlet interface to validation (ValidatorServlet) which validates all foaf:Person instances found in a repository. This is particulary useful when checking the results of scuttering.

The ValidatorServlet takes the same initialization parameters (specified in the web.xml file) as the Smusher. There are no request parameters to specify.