Set up a Plugin Development Environment

Contents


Introduction

This tutorial explains how to setup your environment in order to create a new plugin for PickCells and provides explanations about the diverse components of a plugin project.

Before you start, please note that there exists a number of projects which are maintained independently because of the third-party libraries they depend on. Here is a non-exhaustive list of library specific projects for PickCells:

If you are planning on using one of the above libraries, you should access the corresponding repository as these projects already contain utility classes and a dependency management system which you will find useful. If unsure of what to do then please ask on the PickCells Colony forum.

If your were planning on using one of the above libraries, you should fork, develop and contribute the corresponding repository as these projects already contain utility classes and a dependency management system which you will find useful.

If you would like to contribute to the PickCells framework itself, please see Develop PickCells core.

If you wish to create a feature which uses the PickCells API but none of the libraries mentioned above or if you just want to experiment, then you are in the right place!


Set up your environment

This tutorial assumes you have already downloaded, installed and run PickCells, as described in our documentation on how to Get Started.

Install Java 8 as described in our documentation on how to Install PickCells.

Install the Eclipse integrated development environment. We recommend installing the latest version of the Eclipse IDE for Java Developers, as this includes a Maven integration package, m2e.

Maven is used as PickCells' build and dependency management tool. Maven supports archetypes, which are template Maven projects.

We will now use Eclipse to create a Maven project which will contain the desired directory structure for a PickCells plugin and some template code. This should only take a few minutes to accomplish thanks to a Maven archetype designed specifically for this purpose.


Import the archetype catalog

An archetype catalog is a small XML file which will tell Maven which archetypes are available. To import the PickCells archetype catalog, in Eclipse go to Window > preferences.

In the left panel of the dialog navigate to Maven > archetype and click to ‘Add remote catalog’.

In the ‘Catalog file’ text box, enter the following URL:

https://archiva.pickcellslab.org/repository/pickcells-releases/archetype-catalog.xml

Enter a custom description in the box underneath.

catalog


Create a project using the archetype

Now we can create a new Maven project using the newly available archetype. To do so, go to File > New… and select Maven Project:

new maven

You will then be asked where the new project should be created. You are free to choose a different location than the default one (which should be a new folder of your current workspace location).

After this, the next dialog will ask you to choose an archetype. You should be able to choose the pickcells-archetype catalog that we imported previously. When you select the pickcells-archetype catalog, the pickcells-archetype should appear underneath as shown in the screenshot below. Select it and then click ‘Next’.

pickcells archetype

The final dialog allows you to define the ‘Maven coordinates’ for your project. In brief, once built, your project will produce a binary file (most likely a Java jar file) which, in Maven terms, is called an artifact. In order to identify this artifact, Maven uses a coordinate system which consists of a ‘groupId’, an ‘artifactId’ and a ‘version’. This allows Maven to manage versions and dependencies when building any project. For more information on this, see Maven Coordinates. The documentation also includes best naming practices for your coordinates.

Here we have create an Example ('artifactId) project which belongs to the ‘family’ or group ‘org.pickcellslab.plugins('_groupId') and with a '_version_' of0.1`.

coordinates

Notice that an additional field is requested, ‘project_name’.

This field is specific to the pickcells-archetype. It will be used to generate template code in our new project. Here we are using the name Example again. This does not have to be the same as the artifactId. You should use a name which does not contain characters which are illegal in class definitions as this name will be used for naming template classes in the project (we describe these classes in ‘Understanding the project’s structure’ below).

When you click ‘Finish’, a new project should appear in your workspace with the following structure:

archetyped project


Enable annotation processing

Java annotations are used to enable the framework to discover the plugins at runtime and also to ensure that a few conventions are respected.

As some of the annotations are not standard java annotations, custom annotation processing must be enabled to allow eclipse to display potential warnings or errors in the editor.

To do so, right-click on the project in the project explorer panel and select Build Path -> Configure Build Path…

Then navigate to Java Compiler -> Annotation Processing and tick all boxes:

Custom Annotation Processing

Then in Factory Path, enable project specific settings and click ‘Add external jar’ to add the annotation processors which are part of the foundationj-wiring.jar artefact.

Factory Path

NB: The foundationj-wiring jar file should be located in your local maven repository

~/.m2/repository/org/pickcellslab/foundationj/foundationj-wiring/0.1.0-SNAPSHOT/foundationj-wiring-0.1.0-SNAPSHOT.jar

That’s it, you are now ready to start coding !

If you wish to get started quickly and are familiar with Maven conventions, you may skip the next section and check out the Where Next? section further below.


Understanding the project’s structure

The following sections explain the structure of the project created with the method described above. If you are familiar with Maven, you will notice that the directory structure follows the Maven standard directory layout

src/main/java

This is where your source code is located. By default, this folder already contains two template classes:

main java

Note that the names of these classes ({project_name}_Node and {project_name}_Plugin) are generated based on the value that we entered in the ‘project_name’ field when creating the project. The classes are as follows:

src/main/resources

This is the folder for your resources which need to be included at runtime:

main resources

By default, an icons/ subfolder is present and it contains a .png file. This is here to illustrate where you may store your icons so they are available at runtime. For example, our Example_Plugin class mentioned previously implements SimpleTask. One of its methods uses the default icon:

@Override
    public Icon icon() {
        // This will define which icon to display in the menu bar of pickcells for this module
        return new ImageIcon(getClass().getResource("/icons/default_icon_32.png"));
}

src/test/java

This folder is where unit tests are located. For an introduction to unit testing concepts, see unit tests in Introduction to Software Engineering on Wikibooks.

test java

In PickCells we use the JUnit 5 unit testing framework in our archetyped project for writing unit tests. The dependencies are already configured and ready to use.

A template test for the Example_Node has already been created to illustrate how testing can be performed. For instance, our Example_Node class declares the following method:

public String sayHi() {
	LoggerFactory.getLogger(getClass()).debug(typeId()+" says Hi!");
	return "Hi!";
}

and our Example_NodeTest has the following method:

	@Test
	public void testSayHi() {
		Example_Node testNode = new Example_Node();
		Assert.assertEquals("Hi!", testNode.sayHi());
	}

The @Test annotation allows JUnit to find and run the method as a JUnit test. In Eclipse, you can right-click on the method declaration to run this specific method as a test. The test should pass and the console should display the logging message.

This is a very simple method just to show that the framework for unit testing is readily available in the archetyped project.

We recommend to write rigourous and automated unit tests for your plugins. For information on writing tests with JUnit 5, see the JUnit 5 Tutorial.

target/

The target folder is where the built artifacts from your project will be located. To create the artifact issue the following Maven command (either in a terminal window or from within Eclipse):

mvn clean install

This command will update, test, build and install your project and create following layout in the target folder:

mvn install

Notice the example-0.1.jar file. This is the jar file that you can drop into the plugins folder of the PickCells installation to see the result of your code. If you do this without changing anything from the archetyped project, you will obtain something similar to this in the bottom left corner of the workbench (in PickCells-0.7.3-SNAPSHOT):

plugin presence

pom.xml

The last file is an important one. The pom.xml file is your Maven configuration file which defines your artifact coordinates, build procedure, dependencies, etc.

With the archetype, we have tried to make it easy to get setup. For example, the dependency to JUnit 5 is already defined. If you open the pom file in your editor, you will find the corresponding line.

<!-- Unit Testing -->
<dependency>
    <groupId>org.junit.platform</groupId>
    <artifactId>junit-platform-runner</artifactId>
    <version>1.1.0</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-engine</artifactId>
    <version>5.1.0</version>
    <scope>test</scope>
</dependency>

In PickCells we also use Mockito for mocking some objects in our tests, the dependencies are not included by default. However you could add this by adding the following lines in the dependencies section:

<dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-core</artifactId>
    <version>2.16.0</version>
    <scope>test</scope>
</dependency>

Note the scope tag. This enables the dependency only during the test phase and not in your final build.

More on Maven POM files can be found in Maven’s Introduction to the POM.


Where Next?

Once your environment is setup, you may start learning about the PickCells API by: