Framesoc query API

Summary

This page describes how to use the Framesoc query API. The tutorial has been developed using Eclipse Luna and Framesoc v1.0.6. The corresponding source code is available in the fr.inria.soctrace.framesoc.tutorials.query plugin of this repository.

Requirements

• Configure a working Framesoc development environment, as described here.
• Learn to create a Framesoc tool, as described here. Only the creation of the plugin is necessary for this tutorial.

Introduction

TODO: provide a summary of the principles of the query objects and the different types of conditions

TODO: introduce the search interface

More details about the query API and the high level search interface are available in the Technical Report RT-427 (subsections 4.1.3 and 4.1.4). Note that the package names used in this report may not be up to date with the current ones, but the concepts are unchanged.

Tutorial

Create a Framesoc tool plugin

We will create here an empty Framesoc tool plugin. We will use its launch() method to execute some code using the query API.

• Create a Framesoc tool plugin (read this for more details), using the following names for the extension points details:

  • id: fr.inria.soctrace.framesoc.tutorials.query
  • class: fr.inria.soctrace.framesoc.tutorials.Query.QueryTool
  • type: ANALYSIS
  • name: Framesoc Query Tool
  • doc: Launch the tool and enjoy.

• You should be able to launch the tool from the Framesoc menu, but nothing should happen then, as the launch() method of the QueryTool is still empty.

• In the rest of the tutorial we will make the assumption that all the presented code is executed directly in the launch() method or in another method called by the launch() method.

Query API basics

To illustrate the basic usage of the query API we will use the EVENT entity of the data model. As described in the Technical Report RT-427 , this entity is physically stored using 4 database tables (cfr. Self Defining Pattern). All these details are hidden by the query API. TODO

Using the Framesoc query API requires the following steps:

• Open a connection to the database. For example:

traceDB = TraceDBObject.openNewIstance(trace.getDbName());

• Create the query object corresponding to the required entity. For example:

EventQuery etq = new EventQuery(traceDB);

• Get the result of the query, as a list of object of the required entity. For example:

List<Event> epl = epq.getList();

• Close the connection to the database. A good practice is to do this in the finally block of a try/catch. For example:

finally {
DBObject.finalClose(traceDB);
}

Using simple conditions

TODO

Using composite conditions

TODO

Some examples

TODO

Event queries

TODO

Trace queries

TODO

Analysis result queries

TODO

Using the high level search interface

TODO