Documentation

1. Plug-in creation

2. Topcased Bus Structure

3. Presentation of the extension points

4. Implementing IService interface

Introduction

This documentation presents all information you have to know to write your own contribution to the Topcased Bus. This tutorial will introduce the different existing extensions points involved in Topcased.

1. Plug-in creation

The first step consists in creating a new plug-in for receiving your future service. Use Eclipse wizard to create a new plug-in project :
File > New > Project > Plug-in project
Give any name you want to the project. On the second page, you can specify that the plug-in does not contribute to the UI. The first screen should look like this :

pluginWizardCreation

Click on the Finish button to create the plug-in project. You may also click on the Next button and specify the Topcased plug-in template to have a service and more sample code in the created plug-in. This point will be explain in detail in the last chapter of this documentation.

2. Topcased Bus Structure

The Topcased bus is based on the Eclipse mechanisms. It reuses extension points definition to define its own structure. We can say that Topcased Bus is another extension point of the Eclipse framework.

The structure of the Topcased bus is divided into three distinct parts :

3. Presentation of the extension points

To work around the Topcased bus, four extension points have been defined. The schemes of this extension point can be found into :

In order to use these specific Topcased extension points, it is mandatory to edit a dependency in the section 'Dependencies' of your plugin.xml file. So, you need to add the dependency to the plug-in containing the declaration of these extension points which is 'org.topcased.bus.core' (Cf. Illustration 2). dependecySection.png

dependecySection

3.1. org.topcased.bus.core.Services

This extension point enables to declare a Topcased Service. This service will be registered to the ServiceManager (which is part of the Topcased Bus).

A Service is defined by the following properties :

A parameter has an identifier, a name, a description and a kind. For the last one, you have to choose between different types : OCLExpression, IPath, EObject, String and Void. Actually, each of the parameter names must match the name of an inParam or an outParam. The additional parameter name must be 'Path' and its type must be 'IPath'. The parameters matching inParams will get a String representing the system path of a file. For the parameters corresponding to outParams, it will be a simple String. Finally, the "Path" parameter will get a IPath that corresponds to the location where the import was triggered. For any other parameter you are free to set it as you want. Remember to set the class of the service to a valid IService class.

3.2. org.topcased.bus.core.Transformation

This extension point allows ATL transformations to collect information about a Topcased transformation.

Add a transformation item and give it a name and an unique identifier. This name corresponds to the label that will be displayed into the import or export wizard. Specify one ruleFile attribute and at least one inParam item. More than one inParam can be set and you can also add several outParam items, which should be the case for most transformations.

3.3. org.topcased.bus.core.Metamodels

This extension must be only used during a transformation process when a metamodel is not generated (i.e not available within the EMF registry). You can define one or more 'metamodel' items without limitation. Typically, this extension point is often used with the Transformation extension point in order to perform a model transformation.

For each item you have to specify :

All those information can be automatically retrieved by the transformation process if needed.

4. Implementing IService interface

Now, you have to write the class specified in Service extension point. This class must implement the IService interface with its serviceRun(Map) method.

As we can see, the service parameters are stored inside a Map where :

Note : It is the responsibility of this class implementation to test the validity of all received parameters.

The result of the service will be returned as Object to allow all objects types to be returned. It is the responsibility of the service to offer to other services a result as described in the Services extension point.

There are several ways to implement this method. You advise to take a look to the existing Topcased services or use the service generator presented in the next chapter.

The service generator allows to create a set of classes representing a contribution to the Topcased Bus. For experimented users and developers, fill free to delete all contained code and customize it according to your needs.


By Sebastien GABEL, Communication & System

Created August, 2 2007