Persistence API services

The Persistence API is a Java client library, which provides the generic RDF persistence framework. It allows serialization and de-serialization of the Java objects into RDF repositories (based on RQL and RUL languages) and will provide Criteria API, which allows creation and execution of RQL queries dynamically in the program code. Main functionalities of the Persistence API include:

  • serialization of the Java objects to the RDF repository
    • generates RUL statements to create or update RDF representation of the specified Java Data Access Objects (DAO)
    • assigns URI for newly created DAO
  • de-serialization of the RDF statements into Java objects
    • generated RQL statements to obtain RDF representation of the specified DAO
  • serialization/de-serialization of RDF model
    • Persistence API provides a RDF object model (as Java classes) for those who need specific functionality
    • RDF Model is resource oriented and independent on used RDF storage
  • criteria API - object oriented API for the RDF queries
    • based on query, results can be returned in RDF model or as DAO classes


  • Concatenation of RQL and RUL statements in order to minimize number of queries sent to KMS-RE
  • Utilizing lazy collections, in order to fetch data from RDFSuite only when it is really needed
  • Connection pool, in order to minimize delay when establishing connection to KMS-RE
  • Cache (On RDF Model level or on DAO Level)


The architecture of the framework is depicted on the following figure. Persistence API users can use modules shaded in gray. The rest of modules are internal and are not normally accessed by users (tools developers).

Architecture of the Persistence API

Data Access Objects (DAO)

Classes of the managed instances are implemented by the tool developer, which specifies mappings to the RDF model via Java annotations inserted in the source code.

Entity Manager

  • Creates instances of the de-serialized java objects and populates their properties from the RDF object model and
  • Updates RDF object model with values from the serialized Java objects. Entity Manager uses reflexion API and annotations of classes and properties specified by tool developer to map properties to RDF model.

Main purpose of Entity Manager is to separate business logic from RDF. By simple annotations, user can connect his Bean class with RDFSuite, without knowing RQL/RUL. Entity Manager Provides RDF persistent framework for the Java objects defined for the various artefacts and used to implement application logic of the KP-Lab tools. Following methods are provided:

Method Description
URI persist(Object entity) Serialize Java DAO into RDF repository. This will update existing or create new
RDF resource with properties specified in Java object.
<T> T find(Class<T> type, URI uri) Deserialize Java object of the specified type from the RDF statements
stored in the RDF repository.
void remove (URI uri)Removes resource from RDF repository, based on given uri of the resource.
<T> List<T> executeCriteria(Criteria cri. teria, Class<T> type)Execute criteria query and translate RDF resources of the result graph to the Java objects of the specified type.


To develop a tool, which will manage knowledge artefact with the specified RDF Scheme, it is assumed that the tool developer will follow the following steps.

  • He/she creates Java classes that correspond to the RDF types specified in the RDF Scheme (e.g. System model), developer can also implement various different Java classes (views) for one RDF type.
  • In the source code of implemented Java classes, developer must use Java annotations provided by the persistence framework to specify mappings of the Java classes and properties to the RDF model (see J2SE 5.0 specification for the description of the Java annotation facilities).
Note that user works only with his DAO classes and calls EntityManager methods. User does not need to know RQL/RUL and in fact he/she does not need to be very familiar even with RDF language.

RUL/RQL Generator

Entity Manager uses RUL/RQL generator to generate statements for fetching or updating RDF data stored in the RDF repository.

RDF Object Model

RDF object model is used to manage in-memory representation of RDF statements loaded from the repository.

RDF Parser

RDF Parser creates instances of the RDF object model for the received RDF triples encoded in XML (or other RDF serialization format).

Criteria API

Criteria API will specify atomic and complex criteria objects, which can be used by tool developer to construct queries to RDF repository.

Criteria Engine

Criteria Engine will interpret criteria queries and generate corresponding RQL statements. It will use Entity Manager to deserialize resources in the result RDF graph to the Java instances.


Persistence API provides following Java annotations for users to create DAO:

Annotation Parameters Note
RDFResource Namespace typeName Class annotation.Required annotation.
URId N/A Field or Method Annotation. This is required annotation, each DAO must have exactly one
Property Name targetEntity Field or Method AnnotationtargetEntity must be specified for Collections.
This is
required annotation, each DAO must have at least one
InverseProperty Name targetEntity Field or Method Annotation.targetEntity must be specified for Collections


DAO used with Entity Manager are independent, they can be freely serialized like any other Java Beans. However there are several requirements that are placed on these DAO:

  • Every element must have URI annotation and every element must have at least one property annotation
  • hashCode() and equals() methods must be based on URI field of the DAO
  • Must manage business integrity itself
    • By custom factory class
    • By ensuring integrity of same properties in DAO (e.g. property subTasks Vs inverse property parentTask in Task class)

Lazy collections

Persistence API specifies and utilizes Lazy collections in order to greatly improve performance when deserializing from RDF repository. Main idea behind lazy collections is that DAO are fetched from RDFSuite only when they are really needed.

This feature of Persistence API is very similar to one in Hibernate. Lazy collections are transparent to users and they don’t need to change they code in any way in order to utilize this feature. Users need to be aware of this feature though, and they need to keep Entity Manager collection open in order to be able to use lazy fetching (if connection was closed, exception would be thrown). Currently, following collections have support for lazy initialization:

  • List<T>
  • Set<T>
Note that collections are lazy initialized only in case that class T is of DAO type. If T is URI, String, basic type or any registered literal type, collections are not lazy.

Custom literals

Persistence API tries to follow Java RDF (JRDF) specification. Currently, all Java's Primitive Data Types plus Date/xsd:dateTime are supported. If user wants to have support for additional typed, he can do so by registering (even in runtime) a new datatype in LiteralFactory class

RDF Object Model

RDF Model used in Persistence API is slightly extended JRDF Model. We have extended it to support datatypes and resource view. It is aimed to be resource-centric and independent on underlying RDF storage. Following figure shows UML class diagram of RDF Object model used in Persistence API to parse result from RDF suite:

UML Class Diagram of RDF Object model used in Persistence API

Most of the time, user does not need to access this model, because he/she is working with DAO objects only. However, there may be situations when it is better for the user to get result not in the form of a DAO class, but in the form of an object of some RDF Java object model. Persistence API will provide “parametric query” methods which parse well defined subset of RQL into RDF Model. This way, user does not need to parse difficult results from KMS Request Engine him/herself. Persistence API can also provide specific methods that will generate complex queries and return result in form of a RDF Model. Functionality of these methods is very specific and thus done upon users’ needs. Results from Criteria API can also be returned in form of a RDF Model, if needed.


All information about the releases available for this API can be found at:

Development Development APIs


  Page Info My Prefs Log in
This page (revision-7) last changed on 18:24 25-Mar-2017 by Ionescu Mirela.

Referenced by

JSPWiki v2.4.102