Develop a Java Command

This chapter describes how to develop a Java command for PAK.

1. Introduction

This chapter gives an overview of the development of commands in the PAK framework.

2. Glossary

In the following a short glossary is given to clarify the terms used in this chapter.

Term	Description
Adapter	An adapter is a special kind of service that takes care of communication with external applications.
Command	A concrete implementation of a task. Commands are elements that are later displayed in the Construction Kit as part of the Palette in the editor.
Interpreter	An interpreter is a Java class used by PAK to make a command implementation executable.
Node	A node is the parent-category for all elements that can occur in a workflow, e.g. a task is a specialization of a node.
Service	Services are classes that are instantiated and configured by the end application and whose instances can be used in the commands to perform specific actions.
Task	A task is a command that has already been placed in a workflow. This means that there can be several tasks with the same command id, which can be distinguished by a different mapping in BPMN.

Term

Description

Adapter

An adapter is a special kind of service that takes care of communication with external applications.

Command

A concrete implementation of a task.
Commands are elements that are later displayed in the Construction Kit as part of the Palette in the editor.

Interpreter

An interpreter is a Java class used by PAK to make a command implementation executable.

Node

A node is the parent-category for all elements that can occur in a workflow, e.g. a task is a specialization of a node.

Service

Services are classes that are instantiated and configured by the end application and whose instances can be used in the commands to perform specific actions.

Task

A task is a command that has already been placed in a workflow.
This means that there can be several tasks with the same command id, which can be distinguished by a different mapping in BPMN.

3. Command Meta Information

The command meta information is stored as JSON file.
It contains all the information relevant for the command so that the engine knows how to execute it.
Usually, a command developer does not need to interact with it because it is automatically generated by the provided tools.

Nevertheless, a developer should be aware of the existence of those files in order to be able to find the cause of errors (e.g. missing datastore keys, wrong data flow analysis, commands not displayed, …).
Check Command Meta Doc for more details!

4. Java Command

This section describes how to write a command for PAK in Java.

4.1. Requirements

The Java Language Command Interpreter (JLCINT) is provided for command development using Java.

Several dependencies and tasks are required, which will be described in the following.
Additionally, an example implementation of a build.gradle for Gradle and a pom.xml for Apache Maven are given.

4.1.1. Dependencies

The required dependencies are described below.

`jlcint-commandapi`	Lightweight dependency that contains only annotations to define the program flow (including mappings) of a command. Does not create dependencies to PAK APIs or similar. Thus, commands remain independent of the PAK engine in the first step.
`jlcint-processor`	Annotation processor that automatically generates the command meta information JSON files from the command API annotations during build. Needs the build information (version, group and name) from the java compiler via -A flags.
`jlcint-testutils`	Test utilities that do not create a dependency on PAK and can be used to perform module tests on individual commands.

jlcint-commandapi

Lightweight dependency that contains only annotations to define the program flow (including mappings) of a command.
Does not create dependencies to PAK APIs or similar.
Thus, commands remain independent of the PAK engine in the first step.

jlcint-processor

Annotation processor that automatically generates the command meta information JSON files from the command API annotations during build.
Needs the build information (version, group and name) from the java compiler via -A flags.

jlcint-testutils

Test utilities that do not create a dependency on PAK and can be used to perform module tests on individual commands.

Additionally, you will need a new task (metaJar) to deploy the meta files to the Nexus repository and to define a new Javadoc custom tag, which defines the documentation for a workflow developer.

Command modules need to declare the scope of following dependencies as provided, see Classloader Delegation Concept.

provided de.asap.pak.jlcint:jlcint-commandapi

/*
The Service-api(s) of the used services. For example if you use the Jenkins Adapter you have to provide the api module of the Jenkins Adapter as "provided"
*/
provided de.asap.pak.adapter.jenkins:jenkins-adapter-api

A command could assume the dependencies in Chapter Services to be present, this might be due to changing credentials or something like that.

4.1.2. Gradle

If you want to use Gradle for your command development you can use the following build.gradle as orientation for needed dependencies.

Listing 1. build.gradle

plugins {
    // java - no more to say
    id 'java-library'
}

ext {
    pakVersion = '1.5.14'
}

version = '1.0.0-SNAPSHOT'
project.description = 'TestCommand'
project.group = 'org.example.commands'

repositories {
    maven {
        name = 'pak-explorer-maven'
        url 'https://pak.asap.de/nexus/repository/pak-explorer-maven/'
    }
    mavenCentral()
}

dependencies {
    annotationProcessor "de.asap.pak.jlcint:jlcint-processor:${pakVersion}"
    implementation "de.asap.pak.jlcint:jlcint-commandapi:${pakVersion}"
    testImplementation "de.asap.pak.jlcint:jlcint-testutils:${pakVersion}"
}

compileJava {
    //  pass required options to annotation processor#
    options.compilerArgs.add("-Aversion=$project.version")
    options.compilerArgs.add("-Agroup=$project.group")
    options.compilerArgs.add("-Aname=$project.name")
}

javadoc {
    source = sourceSets.main.allJava
    options.tags = [
            'workflowDocu:cm:Workflow Developer Documentation:'
    ]
}

task metaJar(type: Jar) {
    archiveClassifier = 'pakmeta'
    from sourceSets.main.output
    include 'meta/**'
    include 'entities/**'
    from sourceSets.main.java
    include 'icon/**'
}

4.1.3. Apache Maven

If you want to use Apache Maven for your command development you can use the following pom.xml as orientation for needed dependencies.

Listing 2. pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<groupId>org.example</groupId>
<artifactId>TestCommand</artifactId>
<version>1.0.0-SNAPSHOT</version>

<properties>
    <pakVersion>1.5.14</pakVersion>
</properties>

<repositories>
    <repository>
        <id>pak-explorer-maven</id>
        <url>https://pak.asap.de/nexus/repository/pak-explorer-maven/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>de.asap.pak.jlcint</groupId>
        <artifactId>jlcint-testutils</artifactId>
        <version>${pakVersion}</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>de.asap.pak.jlcint</groupId>
        <artifactId>jlcint-commandapi</artifactId>
        <version>${pakVersion}</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>de.asap.pak.jlcint</groupId>
        <artifactId>jlcint-processor</artifactId>
        <version>${pakVersion}</version>
    </dependency>
</dependencies>

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.0</version>
                <configuration>
                    <annotationProcessorPaths>
                        <annotationProcessorPath>
                            <groupId>de.asap.pak.jlcint</groupId>
                            <artifactId>jlcint-processor</artifactId>
                            <version>${pakVersion}</version>
                        </annotationProcessorPath>
                    </annotationProcessorPaths>
                    <compilerArgs>
                        <arg>-Aversion=${project.version}</arg>
                        <arg>-Agroup=${project.groupId}</arg>
                        <arg>-Aname=${project.artifactId}</arg>
                    </compilerArgs>
                </configuration>
            </plugin>
            <plugin>
                <artifactId>maven-jar-plugin</artifactId>
                <version>3.0.2</version>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <version>3.2.0</version>
                <configuration>
                    <source>sourceSets.main.allJava</source>
                    <tags>
                        <tag>
                            <name>workflowDocu</name>
                            <placement>a</placement>
                            <head>Workflow Developer Documentation:</head>
                        </tag>
                    </tags>
                </configuration>
            </plugin>
        </plugins>
    </pluginManagement>
</build>

</project>

4.2. Implementation

This chapter will show you how to use annotations to declare a command in Java.

4.2.1. Annotation Quick Reference

To develop a command you must use several annotations.
The available annotations are listed below.
Each list item refers to a documentation of the respective annotation.

4.2.2. Example

The following is a simple example of a command that clones a repository with git.

Listing 3. Command implementation: GitClone.java

import de.asap.pak.jlcint.commandapi.CommandGroup;
import de.asap.pak.jlcint.commandapi.JavaCommand;
import de.asap.pak.jlcint.commandapi.Persistent;
import de.asap.pak.jlcint.commandapi.Run;
import de.asap.pak.jlcint.commandapi.Service;

/**
 * Sample implementation for a simple command that uses a Git service to execute
 * a method on it. The @JavaCommand annotation is necessary for the annotation
 * processor to recognize this class as a command. If this is not set, no meta
 * file will be generated!
 *
 * @workflowDocu Clones a GIT repository to a target directory
 */
@JavaCommand
@CommandGroup("Git") // described name will be shown as group/cluster in the workflow editor
public class GitClone {
	/**
	 * Fields annotated with @Service are automatically resolved by JLCINT via
	 * injection. For tests, a mocked instance could also be handed over. It is also
	 * possible to specify a named service instance (@Named or to set this service
	 * as optional (@Service(optional = true)).
	 */
	@Service
	private IGitService gitService;

	/**
	 * @Persistent means that the value is read or saved from the data store.
	 *             Without this specification the value is a mandatory read value.
	 *             The annotation provides many options, which are described in the
	 *             JavaDoc.
	 * @workflowDocu Source repository URI to clone
	 */
	@Persistent
	private String gitUri;

	/**
	 * @workflowDocu target directory, where the repository should be cloned to
	 */
	@Persistent
	private String targetFolder;

	/**
	 * Methods that are annotated with @Run are executed when the task is called.
	 * Any number of exceptions can be thrown, these can then be handled by an
	 * exception handler during runtime (see exception handling concept).
	 */
	@Run
	public void doClone() throws IOException, GitServiceException {
		this.gitService.cloneRepository(this.gitUri, target);
	}
}

4.2.3. Don’ts

Don’t name @Run Method like getter

Make sure that the method under ‚@Run‘ is not named like a possible getter for one of the fields.
Otherwise, hard interpreter errors will occur.

Listing 4. Do not follow this

@JavaCommand
public class FetchFile {

	[...]

	@Persistent
	private String fileName;

	@Run
	public void getFileName() {
		[...]
	}
}

In the example above the getter of the field fileName would be getFileName which is also the name of the method annotated with @Run.

4.2.4. Best Practices

Deprecation over Removal

Instead of removing or renaming an old command use the @Deprecated annotation instead.
This ensures that old workflows will still work after an update of the available commands.

Listing 5. Deprecation over Removal

/**
 * @workflowDocu Creates a new test run from test cases.
 * @deprecated CreateNewTestRunFromTestCases is the follow-up version of this
 *             command.
 *             Use that instead!
 */
@JavaCommand
@Deprecated(since = "adapter version 1.1.0")
public class CreateNewTestRun {
	[...]
}

4.3. Conversion

The interpreter handles the conversion of data types between the datastore and the command.
This enables a smooth usage of the interacting commands.

4.3.1. Possible Conversions

String ⇐⇒ Number
Number ⇐⇒ Number (Integer ⇐⇒ Double)
String that represents a number ⇐⇒ Number
String ⇐⇒ Boolean
Primitive ⇐⇒ Boxed
Object implements Interface ⇒ Interface
Object extends SuperObject ⇒ SuperObject
Object ⇒ Everything that Object is castable to
Object ⇒ String (via toString())
String ⇒ File

4.3.2. Impossible Conversions

Not convertible are

numbers that exceed the limit for another type of number
objects not extending/implementing the same super class.

4.3.3. Example

For example, a command saves a time value as double and another command requests the time value from the datastore as integer.
This conversion is only possible when the object saved in the datastore is convertible to another class.

Figure 1. Conversion Examples

4.4. Testing

To test a command the jlcint-testutils package offers a JUnit 5 (Jupiter) extension which takes care of resolving datastore values and services.

A possible simple implementation of a test for the command of Listing 3 looks like this.

Listing 6. Example test class for command of GitClone.java

import de.asap.pak.jlcint.commandapi.Persistent;
import de.asap.pak.jlcint.commandapi.Service;
import de.asap.pak.jlcint.testutils.JlcintExtension;
import org.junit.Test;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.extension.ExtendWith;

import java.io.IOException;

import static org.junit.jupiter.api.AssertTrue.assertTrue;

/** The @ExtendWith is required to load the Jlcint test extensions */
@ExtendWith(JlcintExtension.class)
public class GitCloneTest {
	/**
	 * We want to set the gitUri variable directly here in the test class, the value
	 * stored here will then be injected in the command
	 */
	@Persistent
	private String gitUri;

	/** the same happens with targetFolder and the git service */
	@Persistent
	private String targetFolder;

	@Service
	private IGitService gitService;

	/**
	 * The provider class is provided by the test utils and then inserted here by
	 * the extension. This one then takes care oft the mapping and the command
	 * instantiation.
	 */
	private Provider<GitClone> command;

	@BeforeEach
	public void prepare() throws IOException {
		// Here we use a specific service instance. Equally possible would be a mock.
		this.gitService = new GitService();
		this.targetFolder = Files.createTempDirectory(this.getClass().getSimpleName()).toString();
		this.gitUri = "... some-repo-at-github ...";
	}

	// TODO: Delete the created temporary directory in @AfterEach

	@Test
	public void testRun() throws Exception {
		// The command can be executed directly and then the result can be validated.
		// Write mappings are also written back to the test class if return values are
		// to be validated.
		// Of course, the provider implementation also allows extensive access to the
		// instance, for example to execute
		// only the PostConstruct method or similar actions.
		this.command.execute();

		// we only look here that the README.MD file was created from our test repo
		assertTrue(new File(this.targetFolder + "/README.MD").exists());
	}
}

Java Command Development – Full Reference

1. Introduction

2. Glossary

3. Command Meta Information

4. Java Command

4.1. Requirements

4.1.1. Dependencies

4.1.2. Gradle

4.1.3. Apache Maven

4.2. Implementation

4.2.1. Annotation Quick Reference

4.2.2. Example

4.2.3. Don’ts

Don’t name @Run Method like getter

4.2.4. Best Practices

Deprecation over Removal

4.3. Conversion

4.3.1. Possible Conversions

4.3.2. Impossible Conversions

4.3.3. Example

4.4. Testing

We are here to help.

4.1. Requirements

4.1.1. Dependencies

4.1.2. Gradle

4.1.3. Apache Maven

4.2. Implementation

4.2.1. Annotation Quick Reference

4.2.2. Example

4.2.3. Don’ts

Don’t name @Run Method like getter

4.2.4. Best Practices

Deprecation over Removal

4.3. Conversion

4.3.1. Possible Conversions

4.3.2. Impossible Conversions

4.3.3. Example

4.4. Testing

Sonatype Nexus

Jenkins

Git Hub

Atlassian Confluence

Codebeamer

JFrog Artifactory

Amazon Web Services (AWS)

Atlassian Jira

Git

Generic Human Tasks

Generic Commands

Nexus Maven Command Pool

Artifactory Maven Command Pool

Open API Command Interpreter

Kotlin Command Interpreter

Bpmn Interpreter

Human Task Interpreter

Java Command Interpreter

Core

RocksDB Persistence

PAK online

Command Line App

Workflow Editor

Workflow Executor

Support