Skip to content

Plugin Development Guide

Jump to bottom Edit New page
Keaton Hanna edited this page Dec 22, 2020 · 5 revisions

Plug-in Development Guide

This guide is intended for developers creating their first plug-in for OSATE. A basic understanding of Java is required and an understanding of the Eclipse framework is helpful.

Sections 3, 4, and 5 can be done in any order, but you may find it easier to do them in the order provided.

Section 0: Before You Start

A clear separation between UI and logic makes it easier to test using JUnit. A JUnit test is required for a plug-in containing logic that will be pushed to the OSATE repository, however, it is always recommended to write a test, whether pushing to GitHub or not.

Section 1: Create a new Plug-in Project

First, decide what working set (if any) the plug-in will live in. Once you have selected where the plug-in will reside, select "File" and then "New" from the tool bar at the top. Next, select "Project..." and search for "Plug-in Project". Give the project a meaningful name by using Java's package naming conventions (i.e. [organizationsName].[descriptiveName].ui) and select "Next>". If the plug-in contains UI, make sure you enable "This plug-in will make contributions to the UI". Another useful option is to generate an Activator class. It is needed if you require work to be done upon the startup or shutdown of the plug-in.

Section 2: Pick Extension(s)

Once you have finished creating the plug-in, you will see a new file "plugin.xml". Under the extension tab, you can choose what parts of Eclipse the plug-in will add to (i.e. org.eclipse.ui.menus). Three extensions that should be added for any plug-in that contains UI are org.eclipse.ui.commands, org.eclipse.ui.handlers and org.eclipse.ui.menus. Each command has a command id and a name. The command id will be referenced by both the handlers extension and the menus extension. The name is what is shown in the menu to allow you to easily find and run the plug-in. The handler extension points to the class that controls the plug-in (this is the handler class, which is covered in the next section). It also allows you to specify when the plug-in is enabled. The menu extension allows you to specify where the button is to be placed in OSATE. Lastly, add your plug-in as a module in the "pom.xml" file of the working set's releng project (i.e. osate2-core.releng).This adds the plug-in to the maven build. You will also need to create a "pom.xml" if there is not one already. Take a look at other "pom.xml" files in the same working set as your plug-in for how to set it up.

Section 3: Create Handler Class

The handler class is called when the plug-in is to be executed. This class should extend AaxlReadOnlyHandlerAsJob, which requires two methods to be implemented, getActionName(), which returns a String, and doAaxlAction(IProgressMonitor monitor, Element root), which does not return anything. doAaxlAction is where the real action happens (hence the name) and handles anything that needs to be called for the plug-in to function. The root parameter gives you the root node from the instance model. This root node is always an instance of the SystemInstanceclass and allows you to traverse the model by casting it to SystemInstance and using the method eAllContents(). The method returns an Iterator object that contains all elements in the model besides the root itself. This can also be done inside of the logic class by passing root as a parameter (this is recommended).

Section 4: Create Separate Java Project for Logic Class(es)

Right click on the working set that you chose to store the plug-in in and create a new "Java Project". Follow the same naming convention as the plug-in project, but drop the ".ui" at the end. Now, you can create any classes that are needed to analyze the meta-model. One method should take root as a parameter, as mentioned above, so that you can walk the model.

Section 5: Create UI Class Using JFace's Dialog Class

Create a new class in the plug-in project and have it extend Dialog. Override Dialog's createDialogArea(Composite parent) method to implement your own UI. On the first line of the method, write the code Composite composite = (Composite) super.createDialogArea(parent);. The composite object is capable of containing other controls (i.e. Labels, Tables, etc.). It will be passed to each control as the first parameter. More information on creating UI is available in the Useful Resources section.

Section 6: Write a JUnit Test (optional)

After having a firm understanding on what the plug-in does, create a new "Java Project" and use the same name as the logic project but add ".tests" to the end. Next, create an AADL model(s) that can test all possible cases of the plug-in's logic. Store the models in a new folder inside of the test project that you just created. Create a new java class for executing the test and add the annotations @RunWith(XtextRunner.class) and @InjectWith(Aadl2InjectorProvider.class) before the class declaration. Inside the class, create a class field of type TestHelper<AadlPackage> and add the annotation @Inject above it. Now, you can create methods for each test model that you created. To instantiate the model for analyzing, you'll first have to get the AADL package. This done using AadlPackage pkg = testHelper.parseFile(pathToModel);, where testHelper is the class field mentioned above. Next, instantiating the model is done using two lines of code: SystemImplementation impl = (SystemImplementation) pkg.getPublicSection().getOwnedClassifiers().get(1); followed by SystemInstance si = InstantiateModel.instantiate(impl);. The si variable is the root of the instance model, just like the root parameter that the handler class takes. The logic of the plug-in can now be tested using the Assert class.

*Note that this is only one way to write a test in OSATE. It is also possible to write tests using Xtend

Section 7: Adding Help Text to OSATE (Optional)

Help Text is a good way to show users how to use your plug-in and some of its capabilities. To begin, you'll need to create a an anchor in the file aadlhelp.xml located in the org.osate.help project in Eclipse. Select what section of the Table of Contents you would like the help text to be stored in and add an anchor. Next, go to the plug-in project you created for the UI and create a table of contents for your help page. Create a new "Help Table of Contents", name it "toc_pluginName.xml", and change "Context" to your plug-in name. Now you can add any topics your help contents will go over. Then, create three folders: "html", "markdown", and "help". The "markdown" folder is only necessary if you plan to have html generated from markdown. In the "help" folder, create a new "Context Help" file and change the ID to "help_dialog". Add a description to the ID, then add a label and link it to your html file. If you decide to use markdown and generate HTML, then you'll need a "pom.xml" file. Take a look at org.osate.modelstats.ui as an example for this file, and it is also a good reference for everything mentioned in this section.

Useful Resources

Eclipse Platform Expression Framework (used in plugin.xml) https://wiki.eclipse.org/Platform_Expression_Framework

Eclipse Platform Command Framework https://wiki.eclipse.org/Platform_Command_Framework

Eclipse Command Core Expressions https://wiki.eclipse.org/Command_Core_Expressions

SWT Tutorial (UI) https://www.vogella.com/tutorials/SWT/article.html

JFace Dialogs (UI) https://www.vogella.com/tutorials/EclipseDialogs/article.html

Java Package Naming Conventions https://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html

Add a custom footer
Add a custom sidebar

Clone this wiki locally