DASISH annotator backend implementation

Introduction

This page describes the implementation of the backend for the DASISH annotation framework. It will serve a range of clients and offers a generic access to a storage facility for annotations and snapshots the annotated context. (To be extended)

People

• Peter Withers?: development
• Olha Shkaravska?: development
• Twan Goosen?: architecture

Design

Architecture overview

Database and Database Access Objects

A relational PostgreSQL database provides a storage for all the core resources: annotations, targets, cached representations, users and notebooks. The database contains 5 main tables; each of them stores a corresponding type of resource. A column in a table represents an attribute in the corresponding resource class, see the model schema. For instance, any resource class has an attribute URI through which a client accesses an instance of the resource. URI has the form <base service URI>/<resources>/<external id>, e.g. "https:/dasish.mpi.nl/api/annotations/e3c834f0-34c4-11e3-aa6e-0800200c9a66". Each of 5 tables has its column "external identifier". An external identifier is a UUID string generated by the server when a resource, e.g. an annotation, is added to the database. Also, it is worth to note that annotation bodies are stored in the table "annotation" in the column "body".

Further, there is a number of join tables representing the relations between the resources, which are described as relations between the classes in the model schema. These relations induce a hierarchy between the resources. Indeed, any of the relations can be abstracted to "refers" so that we have that a "user" refers to an "annotation" or a "notebook", an "annotation" refers to a "target" and a "target" refers to a "cached representation". As one can see, cached representations have the lowest position in this hierarchy. This hierarchy induces a "cascading" mechanism of adding and deleting resources in the database. For instance, removal of an annotation from the database triggers the removal of its targets, except the ones to which other annotations refer to. In its turn, removal of the targets triggers removal of all the corresponding cached representations unless some other targets refer to a cached representation under consideration.

"Spring Database Access Objects" (DAO's) are used to programmatically access the data in the database. The DAO mechanism allows to form and call SQL database commands like SELECT, or UPDATE, or INSERT, or DELETE from "java" methods. Signatures for basic manipulations over resources (retrieving, updating, adding and deleting) are given in the corresponding DAO java interface. For instance, AnnotationDao.java interface lists the signatures of all necessary basic operations over the table "annotation" and the joint tables "annotation-targets" and "annotations-principals-permissions". By a basic operation we mean an operation which demands a single SQL command SELECT, or UPDATE, or INSERT, or DELETE. The interfaces themselves do not perform any actual work, they just list necessary java methods together with their input and output types. Any interface must be implemented by a corresponding java class. For instance, "add annotation" is implemented in JdbcAnnotationDao.java class as a single java method. As one expects, this method forms and calls an INSERT command for the table "annotation".

Due to the presence of join tables there must be a mechanism that takes care about right sequencing of basic operations. For instance, consider a complete procedure of deleting an annotation. The annotation's internal database identifier occurs in three joint tables "annotations-targets", "annotations-principals-permissions", "notebooks-annotations". If the annotation record is deleted from the table "annotation" before the corresponding rows in the joint tables are removed, then the joint tables have references to the non-existing annotation (via its internal identifier). The database signalises an integrity error. To prevent such errors we have introduced a special java class "DBIntegrityServiceImpl.java" which calls the methods from the DAO implementations in the correct order. Moreover it triggers cascading of the operations when necessary. For instance, complete deleting of an annotation amount to purging the joint tables first, then deleting the corresponding record in the "annotation" table, and then triggering removal of the annotation's non-used targets.

The complete list of the DAO java classes and their methods together with short comments can be found in the java-doc files. (reference ???)

REST interface

A client makes use of DAO classes by means of REST interface methods. For instance, let the client send an URI request "GET https:/dasish.mpi.nl/api/annotations/e3c834f0-34c4-11e3-aa6e-0800200c9a66", that is the client wants to retrieve an annotation with the external identifier "e3c834f0-34c4-11e3-aa6e-0800200c9a66". The request URI triggers a call of the corresponding GET interface method on the server side. This interface method retrieves the user's credentials and calls the corresponding DAO method.

REST requests completely define communications between the server and a client on a high level. All the requests are listed in the specification document.

From the programmer's point of view, the REST interface is implemented as a set of JAX-RS resources that make use of the DAO classes to access the data.

Tickets

List of all open tickets for the backend component:

Ticket	Summary	Priority	Owner	Reporter
No tickets found