deliverable d.4.2 the cai documentation · all cai http rest methods available described using the...

FP7-ICT-2013-10

ICT-10-8.1 - Technologies and scientific foundations in the field of creativity

of 22

Deliverable D.4.2

The CAI Documentation

WP 4 – c-Space content server platform

T.4.1 - Content access infrastructure – CAI and spatio-temporal aggregation and alignment of

video streams

Revision: [Final]

Authors:

Angelos Anagnwstopoulos (EPSILON International)

Anestis Trypitsidis (EPSILON International)

Marc Bonazountas (EPSILON International)

Nikolaos Papadakis (EPSILON International)

Dissemination level PU (public)

Reviewer(s) Anestis Trypitsidis (EPSILON International)


Editor(s)

Angelos Anagnwstopoulos (EPSILON International)

Anestis Trypitsidis (EPSILON International)


Nikolaos Papadakis (EPSILON International)

Partner in charge(s) EPSILON

Due date 31-10 -2014

FP7-ICT-2013-10


of 22

REVISION HISTORY AND STATEMENT OF ORIGINALITY

Revision Date Author Organisation Description

v.1.0 15/10/2014 Anestis Trypitsidis EPSILON International Structure of the document

v.2.0 20/10/2014 Anestis Trypitsidis EPSILON International Content inserted

v.2.1 24/10/2014 Angelos Anagnostopoulos EPSILON International Content inserted

v.2.2 24/10/2014 Angelos Anagnostopoulos EPSILON International Content inserted

v.2.3 24/10/2014 Nikolaos Papadakis EPSILON International Content inserted

v.3.0 28/10/2014 Anestis Trypitsidis EPSILON International Initial Draft

v.4.1 30/10/2014 Angelos Anagnostopoulos EPSILON International Final review

v.4.2 30/10/2014 Nikolaos Papadakis EPSILON International Final review

v.4.3 31/10/2014 Marc Bonazountas EPSILON International Final review

v.5.0 03/11/2014 Anestis Trypitsidis EPSILON International Review and formatting

v.6.0 16/11/2014 Nikolaos Papadakis EPSILON International Add UML diagrams

v.7.0 16/11/2014 Anestis Trypitsidis EPSILON International Final review

v.8.0 12/15/2015 Bruno Simoes GRAPHITECH Review

Statement of originality:

This deliverable contains original unpublished work except where clearly indicated otherwise.

Acknowledgement of previously published material and of the work of others has been made through

appropriate citation, quotation or both.

Moreover, this deliverable reflects only the author’s views. The European Community is not liable for any

use that might be made of the information contained herein.

FP7-ICT-2013-10


of 22

Table of content

TABLE OF CONTENT ................................................................................................................................................. 3

TABLE OF FIGURES ................................................................................................................................................... 4

ACRONYMS ................................................................................................................................................................... 5

A. TECHNOLOGIES USED .............................................................................................................................................. 7

B. SOFTWARE STACK ................................................................................................................................................... 7

2. HTTP REST API ................................................................................................................................................ 10

A. THE UML DIAGRAMS ........................................................................................................................................... 14

3. FUTURE ACTIONS ........................................................................................................................................... 21

4. REFERENCES ..................................................................................................................................................... 22

FP7-ICT-2013-10


of 22

Table of figures FIGURE 1: UML MEDIA CONTROLLER – GETMETADATA ............................................................................................................................... 14 FIGURE 2: UML MEDIA CONTROLLER – GETTRACKING ................................................................................................................................. 14 FIGURE 3: UML DEVICE CONTROLLER (REGISTERS A NEW DEVICE) – NEWDEVICE ................................................................................. 15 FIGURE 4: UML SCENE CONTROLLER – GETSCENE ......................................................................................................................................... 15 FIGURE 5: UML SCENE CONTROLLER – CREATESCENE .................................................................................................................................. 15 FIGURE 6: UML UPLOAD CONTROLLER – GETUPLOAD INFO – GETFILEINFO – UPLOAD (STORES) ......................................................... 16 FIGURE 7: UML TIMESTAMP CONTROLLER – GETUTCTIME ........................................................................................................................ 17 FIGURE 8: UML USER CONTROLLER – GETUSER (ID) – NEWUSER (I.E. EMAIL) - ATTACHDEVICE – LIST - LOGIN ............................. 18 FIGURE 9: C-SPACE CLASSES................................................................................................................................................................................. 19 FIGURE 10: CAI MODEL ......................................................................................................................................................................................... 20

FP7-ICT-2013-10


of 22

Acronyms

3GP Third Generation Partnership

4D 4-Dimensional

API Application Programming Interface

App Application

CAI Content Access Infrastructure

Exif Exchangeable image file

GMT Greenwich Mean Time

GPX GPS Exchange Format

HTTP Hypertext Transfer Protocol

IEC International Electro technical Commission

ISO International Organization for Standardization

jpeg Joint Photographic Experts Group

MP4 MPEG Layer-4 Audio

NTP Network Time Protocol

OEM Original equipment manufacturer

ppm parts per million

UTC Universal Coordinated Time

WP Work Package

FP7-ICT-2013-10


of 22

1. Introduction

This document details the software and the hardware architecture of the CAI system. The design pursues a

modular methodology based on a distributed environment paradigm at a Linux container level, following

the n-tier architecture. Following the n-tier Architectural Style has many benefits. The main properties of a

system designed this way include:

Ease of deployment,

Flexible to future changes,

Extensible and scalable,

Not context specific,

Reusable,

Secure and many others.

In the following paragraphs a detailed description of the architecture will be given.

FP7-ICT-2013-10


of 22

1. Software Components

On top of the infrastructure described above lies the CAI application layer. It is responsible for handling all

CAI business logic. Among its functions are:

Provide endpoints for uploading/downloading media content to/from the CAI storage

Store uploaded/reconstructed media content (coming from the mobile client, the reconstruction

pipeline, etc.)

Extract and/or enrich meta-data embedded into the media content

Index the data and provide a search API

Handle user/role management

Notify other modules about events (e.g. 4d reconstruction material ready etc.)

a. Technologies used

The entire implementation is based on J2EE technologies. The main reasons for choosing the Java platform

are:

Cross-platform support

High scalability

Wide adoption

Maturity

Huge library code-base available

Open source license

Ease of installation on infrastructure

Common code-base with Android

b. Software Stack

The CAI software stack is arranged as depicted in the following diagram:

FP7-ICT-2013-10


of 22

The JVM layer

OpenJDK 1.7 was chosen, instead of the Oracle one, since it is fully open-source and compatible with the

latter. It fully implements the Java Platform, SE 7 specification. In the CAI server's case, it is also part of the

official Ubuntu repositories and, therefore, easily installed and maintained (i.e. updates are part of the OS

update work-flow).

Apache Tomcat 7

Apache tomcat is the most widely used, open-source, servlet container and web server. Version 7

implements and supports the Servlet 3.0 API and JSP 2.2 specifications. It also supports various features

such as clustering and high availability.

Java Persistence API (JPA)

Responsible for the management of relational data (i.e. SQL databases), this API supports mapping

database tables to Java entities/objects (POJOs – Plain Old Java Objects), as well as handling all database

transactions, acting directly on those objects (instead of the database tables). This technique is called

Object Relational Mapping (ORM), and adds a level of abstraction for the application developer. The most

widely used API (defined in JSR-317) implementation is Hibernate, also used in the c-Space context.

Spring Core

The Spring Core framework forms the basis for J2EE (Enterprise) applications. It acts as the “glue” between

the various components of an application, supporting Dependency Injection, Inversion of Control,

declarative (via annotations) component definition etc. A large number of sub-projects build upon the

Core framework and can be used as modules on any application, on a per-case basis.

http://openjdk.java.net/

https://jcp.org/en/jsr/detail?id=336


http://hibernate.org/

FP7-ICT-2013-10


of 22

Spring Data

A Spring sub-project, wraps around the JPA API, and enables easy data access to the developer, as well as

simplified transaction handling.

Spring Security

A Spring sub-project, it enables handling of users, user roles, as well as user privileges, via declarative rules

and/or programmatic configuration.

Spring MVC

This framework, yet another Spring sub-project, enables easy creation of fully-featured Web based

applications, supporting the Model View Controller paradigm. Compared to the traditional 'Servlet' based

web application, it offers a huge amount of ready-to-use features to the developer, such as declarative

controllers, custom return types, automatic HTTP form field mapping to Java objects etc.

HTTP REST

Not a component by itself, but rather a feature of Spring MVC, chosen to be depicted here because of its

importance in the c-Space project, since it is the universal endpoint for all communication between all of

c-Space modules and the CAI.

FP7-ICT-2013-10


of 22

2. HTTP REST API

As mentioned in the previous section, all CAI communication with the other c-Space modules takes place

over HTTP, using a REST API created specifically for that purpose.

All methods provided by the API are either HTTP GET methods, when querying for data, or POST ones,

when putting data on the server. Method parameters are appended to the request URL, in the case of a

GET request, or embedded into the request body, in the case of a POST request.

Any time textual data is expected back from the server, as part of the response, it is encoded in JSON

format, a widely used Internet media type when implementing REST APIs.

As far as security goes, REST best practice indicates that user credentials are included along with every

request (in c-Space's case, using the HTTP basic access authentication method), instead of maintaining a

session token. This makes client-side code (the Android end-user application, for example) easier to

maintain.

All CAI HTTP REST methods available described using the Web Application Description Language,

developed by Sun Microsystems and forming the REST equivalent of SOAP's WSDL. It is, essentially, a

dynamically produced XML document, containing the method signatures, along with textual comments for

each method.

It can be found at the CAI context URL: http://<CAI Hostname or IP>/cai/v2/application.wadl

At the time of writing, the WADL descriptor is as follows:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <application xmlns="http://wadl.dev.java.net/2009/02"> <doc title="Spring REST Service WADL" /> <resources base="http://<CAI Hostname or IP>/cai/v2/application.wadl"> <resource path="/v2/application.wadl"> <method id="generateWadl" name="GET"> <doc title="WADLControllerV2.generateWadl" /> <response status="200"> <representation mediaType="application/xml" /> </response> </method> </resource> <resource path="/scene/new"> <method id="createScene" name="POST"> <doc title="SceneController.createScene" xml:lang="en">Creates a new media scene, for later media attachment to it</doc> <request> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="title" style="query" type="xs:string" required="true" /> </request> <response status="200"> <representation mediaType="application/json" /> </response> </method> </resource> <resource path="/scene/status"> <method id="getSceneStatus" name="GET"> <doc title="SceneController.getSceneStatus" xml:lang="en">Returns the current media status per scene, i.e. if any new content has been added since the last check</doc>

https://wadl.java.net/

FP7-ICT-2013-10


of 22

<response status="200"> <representation mediaType="application/json" /> </response> </method> </resource> <resource path="/media/{mediaId}/download"> <method id="download" name="GET"> <doc title="MediaController.download" /> <request> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="mediaId" style="template" type="xs:int" required="true" /> </request> <response status="200"> <representation mediaType="application/json" /> </response> </method> </resource> <resource path="/media/{mediaId}/metadata"> <method id="getMetadata" name="GET"> <doc title="MediaController.getMetadata" xml:lang="en">Returns a list of, non-location related, stored metadata, for the requested media</doc> <request> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="mediaId" style="template" type="xs:int" required="true" /> </request> <response status="200"> <representation mediaType="application/json" /> </response> </method> </resource> <resource path="/media/{mediaId}/metadata/tracking"> <method id="getTracking" name="GET"> <doc title="MetadataController.getTracking" xml:lang="en">Returns a list of, location related, stored metadata, for the requested media</doc> <request> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="mediaId" style="template" type="xs:int" required="true" /> </request> <response status="200"> <representation mediaType="application/json" /> </response> </method> <method id="setTracking" name="POST"> <doc title="MetadataController.setTracking" xml:lang="en">Attaches a GPX XML file to an (existing) video on the CAI. The client must send a HTTP multipart request.</doc> <request> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="filename" style="query" type="xs:string" required="true" /> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="mediaId" style="template" type="xs:int" required="true" /> </request> <response status="200"> <representation mediaType="application/json" /> </response> </method> </resource> <resource path="/upload/info"> <method id="getUploadInfo" name="GET"> <doc title="UploadController.getUploadInfo" xml:lang="en">Returns data related to a file upload (partial or not)</doc> <request> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="filename" style="query" type="xs:string" required="true" /> </request>

FP7-ICT-2013-10


of 22

<response status="200"> <representation mediaType="application/json" /> </response> </method> </resource> <resource path="/file/info"> <method id="getFileInfo" name="GET"> <doc title="UploadController.getFileInfo" xml:lang="en">Used for internal testing purposes, ignore</doc> <request> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="filename" style="query" type="xs:string" required="true" /> </request> </method> </resource> <resource path="/upload"> <method id="upload" name="POST"> <doc title="UploadController.upload" xml:lang="en">Uploads and stores a media file to the CAI. Supports chunked upload. The client must send a HTTP multipart request. Once the file is uploaded, it is automatically categorized as raw/reconstruction. If a 'sceneId' parameter is included in the request, the file is attached to that scene (if it exists on the CAI)</doc> <request> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="sceneId" style="query" type="xs:int" required="false" /> </request> <response status="200"> <representation mediaType="application/json" /> </response> </method> </resource> <resource path="/time"> <method id="getUTCTime" name="GET"> <doc title="TimestampController.getUTCTime" xml:lang="en">Returns timestamp from europe.pool.ntp.org</doc> <response status="200"> <representation mediaType="application/json" /> </response> </method> </resource> <resource path="/device/new"> <method id="newDevice" name="POST"> <doc title="DeviceController.newDevice" xml:lang="en">Registers a new device (i.e. mobile phone)</doc> <request> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="brand" style="query" type="xs:string" required="true"> <doc xml:lang="en">The device brand, e.g. 'Google'</doc> </param> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="model" style="query" type="xs:string" required="true"> <doc xml:lang="en">The device model, e.g. 'Nexus'</doc> </param> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="serial" style="query" type="xs:string" required="true"> <doc xml:lang="en">A unique device identifier, should be what Android's 'TelephonyManager.getDeviceId()' returns</doc> </param> </request> <response status="200"> <representation mediaType="application/json" /> </response> </method>

FP7-ICT-2013-10


of 22

</resource> <resource path="/user/{userId}"> <method id="getUser" name="GET"> <doc title="UserController.getUser" xml:lang="en">Gets a a c-Space user's info</doc> <request> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="userId" style="template" type="xs:int" required="true" /> </request> <response status="200"> <representation mediaType="application/json" /> </response> </method> </resource> <resource path="/user/new"> <method id="newUser" name="POST"> <doc title="UserController.newUser" xml:lang="en">Creates a new c-Space user</doc> <request> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="email" style="query" type="xs:string" required="true" /> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="firstName" style="query" type="xs:string" required="true" /> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="lastName" style="query" type="xs:string" required="true" /> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="password" style="query" type="xs:string" required="true" /> </request> <response status="200"> <representation mediaType="application/json" /> </response> </method> </resource> <resource path="/user/{userId}/device"> <method id="attachDevice" name="PUT"> <doc title="UserController.attachDevice" xml:lang="en">Attaches an existing devices to the given user</doc> <request> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="userId" style="template" type="xs:int" required="true"> <doc xml:lang="en">The target user's id</doc> </param> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="deviceId" style="query" type="xs:int" required="true"> <doc xml:lang="en">The attached device's ID</doc> </ param> </request> <response status="200"> <representation mediaType="application/json" /> </response> </method> </resource> <resource path="/user/list"> <method id="list" name="GET"> <doc title="UserController.list" xml:lang="en">Gets a a list of c-Space users</doc> <response status="200"> <representation mediaType="application/json" /> </response> </method> </resource> <resource path="/user/login"> <method id="login" name="POST"> <doc title="UserController.login" xml:lang="en">Login a c-Space user.

FP7-ICT-2013-10


of 22

*NOTE*: Login does NOT store any session information on the CAI server. User credentials must be send along with each REST request. This method is provided only as a means to validate a user account's existence.</doc> <request> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="email" style="query" type="xs:string" required="true" /> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="password" style="query" type="xs:string" required="true" /> </request> <response status="200"> <representation mediaType="application/json" /> </ response> </method> </resource> </resources> </application>

a. The UML diagrams

Figure 1: UML Media Controller – getMetadata

Figure 2: UML Media Controller –

getTracking

The service depicted in Figure 1 shows how a user gets metadata of a given Media object stored in the

database. This service requires also the media Id that is passed through the URL of the request, while

Figure 2 presents the operation of getting and setting the tracking data from/to a media object. Tracking

information includes the longitude, latitude, speed, bearing, etc that can be passed and stored to a

specific media file.

FP7-ICT-2013-10


of 22

Figure 3: UML Device Controller (Registers a new device) – newDevice

The operation of registering a new device is presented in Figure 3. User devices need to be registered so

they can get push notifications and eventually get data in the best for their capabilities formats

(depending e.g. of their screen capabilities, CPU, etc).

Figure 4: UML Scene Controller – getScene

Figure 5: UML Scene Controller –

createScene

Figure 4 and Figure 5 respectively show the methods to be called for getting the current status of a

specific scene object (row in the db) and the action to create a new scene object. As depicted in the

database schema every scene may have multiple media files associated with it featuring the various

FP7-ICT-2013-10


of 22

different “captures -videos” in time and space of the same scene.

Figure 6: UML Upload Controller – getupload info – getFileInfo – upload (stores)

The upload functionality is presented in the Figure 6, It shows all the various commands accepted by the

UploadController when uploading a media file and when getting information (status) for a specific file or

upload.

FP7-ICT-2013-10


of 22

Figure 7: UML Timestamp Controller – getUTCTime

Through the TimestampController applications and users involved in c-Space may request the “official” c-

Space time used to calculate various time offsets and synchronize their local clocks with the official time.

FP7-ICT-2013-10


of 22

Figure 8: UML User Controller – getUser (id) – newUser (i.e. email) - attachDevice – list - login

The userController shown in Figure 8 is responsible for the authentication (login) of the cSpace users as

well as the creation of new users and the relation of users to specific registered devices.

FP7-ICT-2013-10


of 22

The respective Classes and their attributes are depicted in the next Figure:

Figure 9: c-Space classes

FP7-ICT-2013-10


of 22

Below the figure illustrates the whole c-Space CAI model at the time of writing this deliverable.

Figure 10: CAI model

FP7-ICT-2013-10


of 22

3. Future Actions

As the project evolves, so will the CAI. In respect to the application itself, new methods will be added,

existing ones will be modified and implemented (in the case of methods forming part of later

deliverables). SSL security will be enabled, if project needs dictate so. Finally, other c-Space modules may

be deployed on the CAI infrastructure, such as the Recommendation System.

As described in Deliverable D.1.5, System Architecture, the CAI will also integrate with the rest of the

Services defined within the c-Space platform.

The integration will be based on the Rest API previously defined and will integrate with the rest of the

Module in loosely coupled manner (units of functionality that are self-contained). The services provided by

c-Space include the:

Recommender Service

3D Reconstruction Service

4D Content Streaming Service

GeoVideo Service

Location Service

Multimedia Content Service and the

Crowdsourcing/Gamification Service.

FP7-ICT-2013-10


of 22

4. References

1 OpenJDK as the JVM layer of c-Space. Available online from: http://openjdk.java.net/

2 Java Platform, SE 7 specification. Available online from: https://jcp.org/en/jsr/detail?id=336

3 The Java Persistence API is the Java API for the management of persistence and

object/relational mapping for Java EE and Java SE environments. Available online from:


4 Hibernate APIs. Available online from: http://hibernate.org/

5 Web Application Description Language. Available online from: https://wadl.java.net/

http://openjdk.java.net/



http://hibernate.org/

https://wadl.java.net/

deliverable d.4.2 the cai documentation · all cai http rest methods available described using the...

Documents