Java Command Development – Full Reference
This chapter describes how to develop a Java command for PAK.
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. |
|
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. |
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.
|
|
Lightweight dependency that contains only annotations to define the program flow (including mappings) of a command. |
|---|---|
|
|
Annotation processor that automatically generates the command meta information JSON files from the command API annotations during build. |
|
|
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-apiA 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.
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.
<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.
GitClone.javaimport 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.
@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.
/**
* @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.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.
GitClone.javaimport 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());
}
}