chavaillaz / jenkins-client

Asynchronous Jenkins client with Jackson supporting multiple HTTP clients.

Jenkins Client

This library allows you to interact with a Jenkins instance and choose which HTTP client to use. It is also easily extendable, allowing you to have custom clients. All requests are performed asynchronously and return a CompletableFuture. The serialization and deserialization of domain objects are performed using Jackson.

Presently, it supports the following HTTP clients:

• Java HTTP client (included since Java 11)
• Apache HTTP client 5.2
• OkHttp client 4.11
• Vert.x client 4.5

Note that this library has been tested with a Jenkins instance version 2.426.1.

Installation

The dependency is available in maven central (see badge for version):

<dependency>
    <groupId>com.chavaillaz</groupId>
    <artifactId>jenkins-client</artifactId>
</dependency>

Don't forget to also declare the HTTP client you want to use as a dependency (see below), as it is only indicated as optional in the project, to avoid gathering them all together despite the fact that only one is needed.

Java HTTP client

It does not require any dependency (already in Java).

Apache HTTP client

It requires the following dependency:

<dependency>
    <groupId>org.apache.httpcomponents.client5</groupId>
    <artifactId>httpclient5</artifactId>
    <version>5.2.x</version>
</dependency>

OkHttp client

It requires the following dependency:

<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>4.12.x</version>
</dependency>

Vert.x client

It requires the following dependency:

<dependency>
    <groupId>io.vertx</groupId>
    <artifactId>vertx-web-client</artifactId>
    <version>4.5.x</version>
</dependency>

Usage

Features

• JobApi - Everything for folders, views, jobs and their builds
  • Folders
    • getFolder(Path path)
    • getFolderConfiguration(Path path)
    • createFolder(Path path, String folderName)
    • renameFolder(Path path, String folderName, String newName)
    • deleteFolder(Path path, String folderName)
  • Views
    • getView(Path path, String viewName)
    • getViewConfiguration(Path path, String viewName)
    • createView(Path path, String viewName)
    • updateViewConfiguration(Path path, String viewName, String configXML)
    • deleteView(Path path, String viewName)
  • Jobs
    • getJob(Path path, String jobName)
    • getJobConfiguration(Path path, String jobName)
    • getJobDescription(Path path, String jobName)
    • createJob(Path path, String jobName, String configXML)
    • updateJobConfiguration(Path path, String jobName, String configXML)
    • renameJob(Path path, String jobName, String newName)
    • enableJob(Path path, String jobName)
    • disableJob(Path path, String jobName)
    • deleteJob(Path path, String jobName)
  • Builds
    • getLastBuildNumber(Path path, String jobName)
    • getBuild(Path path, String jobName, int buildNumber)
    • getArtifact(Path path, String jobName, int buildNumber, String artifactPath)
    • getTestReport(Path path, String jobName, int buildNumber)
    • getTestCoverageReport(Path path, String jobName, int buildNumber)
    • getConsoleOutput(Path path, String jobName, int bufferOffset)
    • getConsoleOutput(Path path, String jobName, int buildNumber, int bufferOffset)
    • buildJob(Path path, String jobName)
    • buildJob(Path path, String jobName, Map<Object, Object> properties)
    • stopBuild(Path path, String jobName, int buildNumber)
• PipelineApi - Everything for pipelines
  • getRunHistory(Path path, String pipelineName, String branchName)
  • getRun(Path path, String pipelineName, String branchName, long buildNumber)
  • getRunPendingActions(Path path, String pipelineName, String branchName, long buildNumber)
  • getRunArtifacts(Path path, String pipelineName, String branchName, long buildNumber)
  • getRunNode(Path path, String pipelineName, String branchName, long buildNumber, String nodeId)
  • getRunNodeLog(Path path, String pipelineName, String branchName, long buildNumber, String nodeId)
• PluginApi - Everything for plugins
  • getPlugins()
  • getPlugins(Integer depth)
  • installPlugin(String pluginId)
• QueueApi - Everything for queues
  • getQueueItems()
  • getQueueItem(long queueId)
  • getQueueItemOptional(long queueId)
  • cancelQueueItem(long id)
• SystemApi - Everything for system management
  • getSystemInfo()
  • getOverallLoad()
  • quietDown()
  • cancelQuietDown()
  • restart()
  • safeRestart()
  • exit()
  • safeExit()
  • reload()
• UserApi - Everything for users
  • getUser()
  • generateToken(String tokenName)
  • revokeToken(String tokenUuid)

Client instantiation

Instantiate the Jenkins client of your choice by giving your Jenkins instance URL. Depending on your needs, you may also want to add authentication with an access token using withTokenAuthentication or with username and password using withUserAuthentication. If you need to connect via a proxy, you can specify it using withProxy. Below an example for each HTTP client:

• JavaHttpJenkinsClient

JenkinsClient client = JenkinsClient.javaClient("https://jenkins.mycompany.com")
    .withUserAuthentication("myUsername","myPassword")
    .withProxy("http://proxy.mycompany.com:1234");

• ApacheHttpJenkinsClient

JenkinsClient client = JenkinsClient.apacheClient("https://jenkins.mycompany.com")
    .withUserAuthentication("myUsername","myPassword")
    .withProxy("http://proxy.mycompany.com:1234");

• OkHttpJenkinsClient

JenkinsClient client = JenkinsClient.okHttpClient("https://jenkins.mycompany.com")
    .withUserAuthentication("myUsername","myPassword")
    .withProxy("http://proxy.mycompany.com:1234");

• VertxHttpJenkinsClient

JenkinsClient client = JenkinsClient.vertxClient("https://jenkins.mycompany.com")
    .withUserAuthentication("myUsername","myPassword")
    .withProxy("http://proxy.mycompany.com:1234");

From this JenkinsClient you will then be able to get the desired APIs described in the feature chapter.

Iterable results

When requesting a list of elements, the client returns an object encapsulating this list, sometimes with more pieces of information depending on the Jenkins endpoint called. From this object, you can iterate directly on its child elements.

Contributing

If you have a feature request or found a bug, you can:

• Write an issue
• Create a pull request

Code style

The code style is based on the default one from IntelliJ, except for the following cases:

Imports

Imports are ordered as follows:

• All static imports in a block
• Java non-static imports in a block
• All non-static imports in a block

A single blank line separates every block. Within each block the imported names appear in alphabetical sort order. Wildcard imports, static or otherwise, are not used.

Arrangements

The attributes of domain classes are ordered alphabetically.

License

This project is under Apache 2.0 License.