3.4 Plugins

The jazz development environment is centered around the creation of custom RTC plugins. However, this section is not a detailed introduction to writing plugins, and instead focuses on how to use jazz development environment in support of writing plugins. Examples of such plugins are the RTC Git Connector, or the Work Item Bulk Mover Service.

For getting started with creating custom RTC plugins, I suggest Ralph Schoons fantastic blog on all topics concerning jazz extensions. Especially the RTC workshop is very important in getting started with extension development.

Quick Introduction

For users of the previous version of jazz-debug-environment, there is a migration guide in the wiki. If you are familiar with jazz plugin development, you will already have plugin projects on your computer. Jazz development environment can automatically detect and configure plugins, given their location.

For example, if you have a local version of the RTC Git Connector, say in a folder called D:\workspaces\jazz\rtc-git-connector, all you have to do is edit the jde/user/workspaces/workspaces_template.cfg file, and add a line pointing to that location. An appropriately edited file could look like this:

# Example: a workspace on drive D could look like this:
D:\workspaces\jazz\rtc-git-connector

where D:\workspaces\jazz\rtc-git-connector is the root folder of the git connector plugin. The root folder of a project is where the main pom.xml or the main package.json are located. Running gradlew info would now show said plugin in the available plugins section:

Available plugins:
        UiEntry {
                directory = D:\workspaces\jazz\rtc-git-connector
                ini line = reference\:file\:D\:/workspaces/jazz/rtc-git-connector@start
        }

That's it, no more configuration is necessary.

Alternatively, you can also put the directory path in a separate file inside the workspaces folder. This can be useful if you have many plugins and want to group them together instead of having one large file. All .cfg files in the workspaces folder are included in the search path for plugins. For example, you could create a file containing all rtc-git-connector related plugins:

jde/user
├── linux_terminal_emulator.cfg
├── run_time_parameters.cfg
└── workspaces
    ├── git-connector.cfg
    └── workspaces_template.cfg

With the following content:

/home/sbi/workspaces/jazz/rtc-git-connector
/home/sbi/workspaces/jazz/rtc-git-connector-service

Detailed Example

This example covers how to use our open source tools to quickly create a new plugin and set up the development environment to use it.

Outline

1. Use the maven plugin archetype to create a new service plugin.
2. Edit the plugin to print a custom message
3. Build the plugin
4. Add the plugin to the jazz development environment
5. Run the environment to verify that our plugin works.

1. Create new plugin

We use the maven plugin archetype to create a new plugin. Detailed instructions on how to do this are included in the README of the archetype. If this is the first time you are creating a plugin, please follow those instructions closely, as they cover a lot of setting up not included in this tutorial.

We create a service called EnvironmentDemonstrationService:

./setup.sh --group org.jazzcommunity.environmentdemo --serviceName EnvironmentDemonstrationService

and move it to its own folder:

mv target/org.jazzcommunity.environmentdemo.parent ~/workspaces/jazz

That means, we now have a service plugin in the following location:

/home/sbi/workspaces/jazz/org.jazzcommunity.environmentdemo.parent

2. Change output

Using any text editor or development environment, we edit the /home/sbi/workspaces/jazz/org.jazzcommunity.environmentdemo.parent/plugin/src/main/java/org/jazzcommunity/environmentdemo/service/HelloWorldService.java file, replacing the writer.write line with:

writer.write("Welcome to the jazz development environment");

3. Build using maven

We use maven on the command line to build the example. In the /home/sbi/workspaces/jazz/org.jazzcommunity.environmentdemo.parent folder, we run

mvn clean install

4. Edit workspaces location

Using any available text editor, we edit the jde/user/workspaces/workspaces_template.cfg file to include the new plugin location.

# Example: a workspace on drive D could look like this:
# D:\workspaces\rtc-git-connector
/home/sbi/workspaces/jazz/org.jazzcommunity.environmentdemo.parent

We can verify this plugin configuration using the info task

./gradlew info

The output should contain a service entry for our newly created demonstration service:

Available plugins:
        ServiceEntry {
                directory = /home/sbi/workspaces/jazz/org.jazzcommunity.environmentdemo.parent
                ini line = reference\:file\:/home/sbi/workspaces/jazz/org.jazzcommunity.environmentdemo.parent/plugin@start
                properties line = org.jazzcommunity.environmentdemo=target/classes,target/dependencies
        }

5. Run environment

We now want to test if our new service plugin works as we anticipate. First, we run the environment:

./gradlew run

After the service has started, we log in and navigate to https://localhost:7443/jazz/service/ (make sure that you are not viewing a cached version of this website, such as by refreshing using Ctrl + Shift + F5 in Firefox). We can now search for an entry with our service, such as by searching for environmentdemo. Our new plugin should pop up in the list of registered services:

Clicking on the link should tell us that there is no method for GET """:

The requested service "" doesn't exist for method "GET".

If we now navigate to the service we previously edited https://localhost:7443/jazz/service/org.jazzcommunity.environmentdemo.IEnvironmentDemonstrationService/helloWorld, we should see the message that we changed:

Welcome to the jazz development environment

That's it, you now know how to create plugins and include existing plugins in the jazz development environment run time.