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 PostgreSQL database provides a storage for all the core resources: annotations, targets, cached representations, users and notebooks. The database consists of 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. For instance, any resource class has an attribute "external identifier" through which a client accesses an instance of the resource. Thus, each of 5 tables have a column "external id". An external identifier is an UUID string generated by the server when a resource, e.g. an annotation, added to the database. Also, it is worth to note that annotation bodies are stored in the table "annotations" in the column "body".

Further, there is a number of joint 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 (unless another annotation refers to it), and in its turn, removal of the targets trigger 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. "Spring 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 like adding, deleting an updating, are given in the corresponding DAO java interface. For instance, AnnotationDao?.java interface lists all the signatures of all necessary basic operations over the annotation table and the joint tables "annotation-targets" and "annotations-principals-permissions". By 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 an annotation table.

Due to the presence of joint tables there must be a mechanism that takes care about right sequencing of basic operations. For instance, consider the a complete procedure of deleting an annotation. An annotation (internal database) identifier occurs in three joint tables "annotations-targets", "annotations-principalss-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 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, the 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

The REST interface is implemented as a set of JAX-RS resources that make use of the DAO's mentioned above to access the data. Communication with the client will happen according to the methods and data models specified in the specification document.

Tickets

List of all open tickets for the backend component:

Ticket	Summary	Priority	Owner	Reporter
No tickets found