Create a new Framesoc tool

Summary

This page describes how to create a new Framesoc tool. Within this tutorial we also provide some usage example of the Framesoc Bus and the 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.tool plugin of this repository.

Requirements

• Configure a working Framesoc development environment, as described here.

Introduction

A Framesoc tool is an Eclipse plugin extending the fr.inria.soctrace.framesoc.core.tool extension point defined in the fr.inria.soctrace.framesoc.core plugin. A Framesoc tool can be launched by Framesoc, perform an analysis and produce analysis results. These results can be stored in the Framesoc database. More details about tool and analysis result representation in the Framesoc datamodel are available in the Technical Report RT-427 .

Tutorial

Create the Framesoc tool plugin

• Create a new plugin: File -> New -> Plug-in Project.

  • Specify as project name fr.inria.soctrace.framesoc.tutorials.tool and press Next.
  • Do not change anything and press Next again.
  • Uncheck the Create a plug-in using one of the templates option, then press Finish.

• Open the file META-INF/MANIFEST.MF, if not already opened automatically, to add the required dependencies.

  • This file is normally opened using the Plug-in Manifest Editor.

  • In this editor, select the Dependencies tab and press Add.

  • A dialog is shown: in the text field write fr.inria.soctrace.lib and add all the plugins of the Framesoc library.

  • Press Add again, and this time write fr.inria.soctrace.framesoc in order to add the plugins fr.inria.soctrace.framesoc.core and fr.inria.soctrace.framesoc.ui.

  • At this point your list of required plugins should contain:

    org.eclipse.ui
    org.eclipse.core.runtime
    fr.inria.soctrace.lib.model
    fr.inria.soctrace.lib.query
    fr.inria.soctrace.lib.search
    fr.inria.soctrace.lib.slf4j
    fr.inria.soctrace.lib.storage
    fr.inria.soctrace.lib.utils
    fr.inria.soctrace.framesoc.core
    fr.inria.soctrace.framesoc.ui
    

• Create the tool extension.

  • Open the Extensions tab and press Add.
  • Write fr.inria.soctrace.framesoc.core.tool in the filter, and select the corresponding extension point.
  • Press Finish
  • Right-click on the extension you just created, then New -> tool.

• The documentation of the extension point fields can be accessed selecting the fr.inria.soctrace.framesoc.core.tool line and clicking on Show extension point description on the right.

  id - The ID of the tool. This is NOT the database ID. It is an identificator having the same format of java     
  packages (i.e., x.y.z.k). Note that each tool must have a globally unique id in the system.
  class - The main class of the tool, extending the FramesocTool abstract class. See its documentation for more details.
  type - The type of the tool.
  name - The name of the tool. Note that each tool must have a globally unique name in the system.
  doc - Launching documentation. Optional.
  

• Fill the the extension element details as follow:

  • id: fr.inria.soctrace.framesoc.tutorials.tool.example
  • class: fr.inria.soctrace.framesoc.tutorials.tool.ExampleTool
  • type: ANALYSIS
  • name: Framesoc Tutorial Tool
  • doc: Launch the tool and enjoy.

• Create the class needed by the extension.

  • Click on the class link.

  • Do not change anything and press Finish

  • The following class should be automatically created:

    package fr.inria.soctrace.framesoc.tutorials.tool;
    
    import fr.inria.soctrace.framesoc.core.tools.model.FramesocTool;
    import fr.inria.soctrace.framesoc.core.tools.model.IFramesocToolInput;
    
    public class ExampleTool extends FramesocTool {
    
        public ExampleTool() {
    	    // TODO Auto-generated constructor stub
        }
    
        @Override
        public void launch(IFramesocToolInput input) {
    	    // TODO Auto-generated method stub
        }
    }
    

  • Add the following line to the launch() method body:

    System.out.println("Hello World!");
    

  • Try to launch the Eclipse Application and test the tool.

    • Right-click on the tool plugin, Run as -> Eclipse Application.
    • Framesoc -> Trace Analysis -> Launch Analysis Tool.
    • Select the Framesoc Tutorial Tool and press OK.
    • In the console of the development Eclipse, you should see Hello World!.

Get the input

Up to this point, our tool is simply launched by Framesoc with no input. A plugin tool can specify the form of is input by extending the extension point fr.inria.soctrace.framesoc.ui.input.toolInput. This extension point enables to specify a factory class that will be used to create a graphical composite that extends a given base class. This composite will contain the graphical elements that the user will use to specify the input.

• Create an extension to the fr.inria.soctrace.framesoc.ui.input.toolInput extension point, following the same procedure as before for the tool extension point.

• Fill the extension element details as follow:

  • toolId: fr.inria.soctrace.framesoc.tutorials.tool.example
  • compositeFactory: fr.inria.soctrace.framesoc.tutorials.tool.ExampleToolInputCompositeFactory

• As done before, click on the link corresponding to the class (compositeFactory this time) and press Finish. The factory class is automatically created and has the following form:

  package fr.inria.soctrace.framesoc.tutorials.tool;
  
  import org.eclipse.swt.widgets.Composite;
  
  import fr.inria.soctrace.framesoc.ui.input.AbstractToolInputComposite;
  import fr.inria.soctrace.framesoc.ui.input.AbstractToolInputCompositeFactory;
  
  public class ExampleToolInputCompositeFactory extends
        AbstractToolInputCompositeFactory {
  
    public ExampleToolInputCompositeFactory() {
        // TODO Auto-generated constructor stub
    }
  
    @Override
    public AbstractToolInputComposite getComposite(Composite parent, int style) {
        // TODO Auto-generated method stub
        return null;
    }
  }
  

  The API of this factory requires to provide a graphical composite for the input. This composite extends the AbstractToolInputComposite base class.

• Create the composite class fr.inria.soctrace.framesoc.tutorials.tool.ExampleToolInputComposite, using the following code:

  TODO
  

• Modify the factory getComposite() method as follows:

    @Override
    public AbstractToolInputComposite getComposite(Composite parent, int style) {
         return new ExampleToolInputComposite(parent, style);    
    }
  

Create a view

• extension point

Using the Framesoc Bus

TODO

• pub sub to display selected trace in text box
  • create layout
  • create textbox
  • handle event and modify text

Using the Framesoc query API

TODO

• perform query on event type or producers and display them in list
  • explain query objects (write another tutorial)