powered by ASAP

Java Command

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


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.


The required dependencies are described below.


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.


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.


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.


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/'

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#

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/**'

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"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">





                            <head>Workflow Developer Documentation:</head>



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

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.


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
@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)).
	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
	private String gitUri;

	 * @workflowDocu target directory, where the repository should be cloned to
	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).
	public void doClone() throws IOException, GitServiceException {
		this.gitService.cloneRepository(this.gitUri, target);


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
public class FetchFile {


	private String fileName;

	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.

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!
@Deprecated(since = "adapter version 1.1.0")
public class CreateNewTestRun {


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

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

Impossible Conversions

Not convertible are

  • numbers that exceed the limit for another type of number

  • objects not extending/implementing the same super class.


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


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 */
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
	private String gitUri;

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

	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;

	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

	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.

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