RDFBean interfaces and dynamic proxying

Along with traditional JavaBean-like persisting technique using RDFBean classes, the version 2.0 introduces new approach to object-RDF mapping: RDFBean interfaces.

It works simply: you define an interface of your domain model object and annotate it just like an RDFBean class:

@RDFNamespaces("foaf = http://xmlns.com/foaf/0.1/")
@RDFBean("foaf:Person")
public interface IPerson {
 
    @RDFSubject
    String getId();
 
    @RDF("foaf:name")
    String getName();
 
    void setName(String name);
 
    @RDF("foaf:mbox")
    String getEmail();
 
    void setEmail(String email);
}

Then you instantiate the RDFBeanManager (was RDFBinding in RDFBeans 1.x) upon an RDF2Go Model and create a dynamic proxy object with your interface:

ModelFactory modelFactory = RDF2Go.getModelFactory();
Model model = modelFactory.createModel();
model.open();        
RDFBeanManager manager = new RDFBeanManager(model);
IPerson person = manager.create("http://example.com/persons/jdoe", IPerson.class)

The methods of this proxy object are directed immediately to the underlying RDF triples, so that

person.setName("John Doe");
person.setEmail("john@example.com");

will cause adding the statements to the model:

<http://example.com/persons/jdoe> a <http://xmlns.com/foaf/0.1/Person> ;
	<http://xmlns.com/foaf/0.1/name> "John Doe" ;
	<http://xmlns.com/foaf/0.1/mbox> "john@example.com" ;

Similarly, the getter methods will return values retrieved directly from these statements.

RDFBean annotations

The annotations scheme has changed, so the old classes will be incompatible with RDFBeans 2.0. As you can see in the example above, @RDF annotation is now applied to the getter methods but not to the field declaration like in the previous versions.

You also can notice new annotation, @RDFNamespaces, which defines a list of URI prefixes to be used in other RDFBean annotations declared in a given class or interface. This includes class and property URIs, as well as RDFBean identifiers:

@RDFNamespaces({ 
	"foaf = http://xmlns.com/foaf/0.1/",
	"persons = http://example.com/persons/" 
})
@RDFBean("foaf:Person")
public interface IPerson {
 
	@RDFSubject(prefix = "persons:")
	String getId();
...

Annotations are now inherited from superclasses and interfaces that makes the RDFBeans markup compatible with complex domain-specific object models. See how the Thing, Agent and Person classes of the FOAF example are organized to mimic the owl:Thing → foaf:Agent → foaf:Person subclassing in RDF-Schema.

http://rdfbeans.sourceforge.net

Working on my current project, I had to deal with a rich object model which is persisted into a RDF triple-store, so quickly I stuck in writing the object-triples translation code. I thought it would be a good idea to automate this by providing a simple data binding framework for transparent mapping of the Java objects to RDF (like Hibernate and other tools does so for SQL or XML) with the following requirements in mind:

• It should be easy to make existing classes compatible with the framework with minimum modifications. This should not affect the business object model (no special interfaces and superclasses) and should not interfere with common JavaBeans-oriented frameworks (like Spring, etc.). Any JavaBean-like POJO class can be RDF-serializable just with few Java annotations added.
• No predefined ontologies and RDF-schemas are required.
• Class information is stored in the RDF model for transparent instantiation of the objects.
• Cascade binding for related objects should be supported.
• Basic Java Collection types should be supported.

This framework is implemented using Java annotations and Reflection APIs and works with major RDF triple-stores (via RDF2GO abstraction layer).

RDF Beans

In order to be mapped to an RDF resource, a Java class must obey certain conventions:

• The class must have a public default (no-argument) constructor.
• The class declaration must have a @RDFBean annotation to associate it with appropriate RDFS class:

  @RDFBean("http://xmlns.com/foaf/0.1/Person")
  public class Person { ...

See also: A RDFBean class example.

Properties

The class properties must be accessible using standard getter and setter methods. The properties are mapped to their RDF counterparts with @RDF annotations:

@RDF("http://xmlns.com/foaf/0.1/name")
String name;
 
@RDF("http://xmlns.com/foaf/0.1/mbox")
String email;
 
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public String getEmail() { return email; }
public void setEmail(String email) { this.email = email; }

The argument of @RDF is a valid URI of a RDF property (predicate) in a domain of the specified RDFS class. The following types of properties are permitted:

• A Literal (String, Boolean, Date, Integer, Float, Double, Long, Short, Byte, java.net.URI)
• Another RDFBean class
• A Java Collection (List or Set) of Literals or RDFBeans

Literal values are represented in RDF with corresponding XML-Schema datatypes and Collections with RDF Containers (rdf:Bag or rdf:Seq depending on a Collection type). References to other RDFBean objects will be kept as RDF object properties and the values will be represented as separate RDF resources.

RDF subject

There must be a special String property to hold an unique URI value to identify the RDF resource (the subject URI). It must be accessible with getter and setter methods and be marked with @RDFSubject annotation:

@RDFSubject
String id;

The property value must be a valid absolute URI, otherwise you can use the prefix argument for a common prefix to construct URIs from arbitrary String identifiers:

@RDFSubject(prefix="http://example.com/persons#")
String id;

Data Binding

RDFBeans data binding framework is based on RDF2Go API which creates an abstraction layer above physical RDF storages. It makes an RDF model independent from specific RDF frameworks (such as Sesame and Jena), thus it can work with any, if a RDF2Go adapter is implemented. The data binding is performed using single RDFBinding class, which is initialized with existing RDF2Go model:

import org.cyberborean.rdfbeans.RDFBinding;
import org.ontoware.rdf2go.RDF2Go;
import org.ontoware.rdf2go.model.Model;
...
Model model = RDF2Go.getModelFactory().createModel();
model.open();
RDFBinding binding = new RDFBinding(model);

The marshal method converts a Java object into a RDF resource in the model:

Person person = new Person();
person.setId("http://example.com/staff#johndoe");
person.setName("John Doe");
person.setEmail("johndoe@example.com");
...
binding.marshal(person);

This code will create a set of RDF statements representing the properties of the given object in the model:

<http://example.com/staff#johndoe> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person> .
<http://example.com/staff#johndoe> <http://xmlns.com/foaf/0.1/name> "John Doe"^^<http://www.w3.org/2001/XMLSchema#string> .
<http://example.com/staff#johndoe> <http://xmlns.com/foaf/0.1/mbox> "johndoe@example.com"^^<http://www.w3.org/2001/XMLSchema#string> .

Additionally, it adds a special statement to associate the RDFS class with Java:

<http://xmlns.com/foaf/0.1/Person> <http://cyberborean.org/rdfbeans/1.0/bindingClass> "com.example.Person" .

The marshal method inspects the properties which link the object with other RDFBeans and initiates their cascade binding to the RDF model, thus simplifying the development and ensuring referential integrity of the RDFBeans.

To reconstruct a Java object from RDF model, there is unmarshal method:

import org.ontoware.rdf2go.model.node.URI;
...
URI subject = model.createURI("http://example.com/staff#johndoe");
Person person = (Person) binding.unmarshal(subject);

The method creates new instance of the Java class (defined by http://cyberborean.org/rdfbeans/1.0/bindingClass property) and fill the properties with data from the RDF model. If a property holds a reference to another RDFBean, it results into cascade unmarshalling of related objects, thus restoring the original object model.

Code

• RDFBeans JAR and source code
• Javadocs

[Update: 2009-08-04]

RDFBeans framework is released on SourceForge: http://rdfbeans.sourceforge.net. The API has been changed, please check the documentation and Javadocs for details.

“How does SCAN help me?”, “Why should I use it?”, “Who are the users?”, “Why it is smart?”, “Can it replace a …?”, “What is autotagging?”, technical tips-n-tricks, development questions and a lot of other things you would want to know about Smart Content Aggregation & Navigation technology.

Read SCAN FAQ »

(Read more on SCAN website)

I’m not thinking about it as of my personal stuff and welcome everyone to suggest new antipatterns and their solutions. if you want to post to that blog yourself, please contact me (you have to be a registered WordPress user).

The plugin purpose is to crawl the specified local email folders and aggregate the email messages as the documents in SCAN repository. It also introduces new document type “message/rfc822” for emails and uses the email message headers for setting document metadata. Attached files are extracted from messages and processed as the separate documents with appropriate parsers depending on its content type.

As there are no common convention on how to identify a separate message for opening it with an external application, mail plugin implements its own message viewer UI to open the messages by default. The messages are identified with “mid:” URI scheme which is a standard but unfortunately, seems to not supported by known MUA’s so far. However, it is implemented in the hope of that the future MUA’s will support this standard scheme to open the specific messages with their command line (something like “thunderbird mid:message-id“).

Mail plugin uses GNU JavaMail implementation because it includes JavaMail providers for local mail stores – mboxes and maildirs. In addition, Outlook Express mail is also supported via the separate JavaMail provider made by jmbox project. Thus, the mail plugin supports a wide range of popular MUA’s, including mbox-based (Mozilla family), maildir-based, mixed mbox/maildir (KMail and Evolution) and Outlook Express.

The plugin has been tested on Linux with Mozilla Thunderbird 1.5 and KMail 1.9.6 (in maildir mode) and Windows XP with Mozilla Thunderbird 1.5 and MS Outlook Express 5.0.

Problems?

Yep, they are. The issues with mail plugin go both from GNU JavaMail limitations and from the side of the concrete MUA’s which seem to be easy with interpreting mbox/maildir principles for their convenience. For instance, Thunderbird uses the non-standard “.sbd” directories to keep the mail subfolders, which the mbox provider is unaware of. So, recursive crawling the Thunderbird mail folders does not work. The only solution for those problems is to develop the MUA-specific JavaMail providers which would know how to deal with a concrete mbox or maildir implementation with all its peculiarities.

Outlook Express provider, as an example of such MUA-specific implementation works rather good, however we noticed a bug with localized MSOE versions where the translated folder names (“Inbox”, “Sent”, “Trash” etc) with non-latin letters had not been processed.

The reports on testing the mail plugin with other MUA’s/platforms are more than welcome.

About SCAN

“… the abundance of information will be such that either you have reached such a level of maturity that you are able to be your own filter, or you will desperately need a filter… some professional filter.”
Umberto Eco: A Conversation on Information
(an interview by Patrick Coppock, February, 1995)

SCAN is aiming for a solution of major problems of content organization and findability in information overload era.

SCAN aggregates content from different sources into a single documents collection. This repository may keep records on thousands of documents independently of their original locations and formats. Every document record contains a number of metadata properties (such as title, description, author, creation date, etc) which can be either set automatically or edited manually.

Adding documents to the repository is an automated operation. A user only need to point SCAN to a location and the application will find and add every document from there. Added document locations will be monitored for changes (new, modified or deleted documents) to keep the repository up-to-date.

The documents content is indexed for search and text analysis. You can search the documents either by simple text queries, or by using special forms to make complex queries for searching on document text and properties. The queries can be saved for repeatable use.

The documents collection is structured with a system of tags, similar to the services like del.icio.us or Flickr. Tags are keywords or labels attached to the items to identify them for quick navigation and finding. All tags together form a taxonomy representing the semantics of the documents collection. The taxonomy can be viewed as a “tags cloud” for navigating through the documents repository.

SCAN text analysis mechanism simplifies the process of tagging. It analyzes a document content and suggests the most relevant words as to-be tags. It makes manual tagging as simple as selecting the tags from the proposed candidates. It also can undertake the whole manual process of tagging, either by automated assigning the tags to the documents, or by finding the documents, relevant to a specific tag. Another text analysis application is searching the documents similar to a specific one (search by pattern).

SCAN is a component-based software using a number of plugins for specific features. The basic SCAN platform can be easily extended with plugins for new document formats, document locations (RSS feeds, web-sites, e-mail, etc) and language analyzers. Whole new areas of functionality can be added with user interface extensions. An example of such extensions is the plugin to browse the repository with a calendar (grouping the documents by their creation dates).

SCAN is a Java application, so it works on any Java-enabled platform. SCAN is a free open source software, distributed under Apache License, Version 2.0

See also:

• List of current features
• Download SCAN
• How to obtain SCAN sources from SVN repository
• User’s Manual