org.aerogear.digger.client

Class DiggerClient

java.lang.Object

org.aerogear.digger.client.DiggerClient

public class DiggerClient
extends Object

Digger Java Client interact with Digger Jenkins api.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DiggerClient.DiggerClientBuilder

Field Summary

Fields

Modifier and Type	Field and Description
static long	DEFAULT_BUILD_TIMEOUT

Method Summary

Modifier and Type	Method and Description
BuildTriggerStatus	build(String jobName) Triggers a build for the given job and waits until it leaves the queue and actually starts.
BuildTriggerStatus	build(String jobName, long timeout) Triggers a build for the given job and waits until it leaves the queue and actually starts.
BuildTriggerStatus	build(String jobName, long timeout, Map<String,String> params) Triggers a build for the given job and waits until it leaves the queue and actually starts.
static DiggerClient.DiggerClientBuilder	builder()
com.offbytwo.jenkins.model.BuildWithDetails	cancelBuild(String jobName, int buildNumber) Cancel a build for a specific job
static DiggerClient	createDefaultWithAuth(String url, String user, String password) Create a client with defaults using provided url and credentials, with crumb flag turned off.
static DiggerClient	createDefaultWithAuth(String url, String user, String password, boolean crumbFlag) Create a client with defaults using provided url and credentials, and specify if crumb is enabled on the Jenkins server.
void	createJob(String name, String gitRepo, String gitBranch, BuildDiscarder buildDiscarder) Create new Digger job on Jenkins platform with build and binary cleanup
void	createJob(String name, String gitRepo, String gitBranch, BuildDiscarder buildDiscarder, com.offbytwo.jenkins.model.credentials.Credential gitRepoCredential, List<BuildParameter> buildParameters) Create new parameterized Digger job on Jenkins platform
void	deleteJob(String jobName, String credentialId) Delete the job from Jenkins server.
InputStream	fetchArtifact(String jobName, int buildNumber, String artifactName) Fetch artifacts urls for specific job and build number
com.offbytwo.jenkins.model.BuildWithDetails	getBuildDetails(String jobName, int buildNumber) Get the details about a build.
List<com.offbytwo.jenkins.model.BuildWithDetails>	getBuildHistory(String jobName) Returns the build history for a job.
String	getBuildLogs(String jobName, int buildNumber) Get build logs for specific job and build number
com.offbytwo.jenkins.JenkinsServer	getJenkinsServer() Expose the underline Jenkins Server client to allow perform other operations that may not be implemented by the jenkins digger client.
com.offbytwo.jenkins.model.JobWithDetails	getJob(String name) Get a Digger job on the Jenkins platform.
BuildTriggerStatus	pollBuild(String jobName, com.offbytwo.jenkins.model.QueueReference queueReference, long timeout, Map<String,String> params) This method takes a QueueReference and polls to check if a build goes to the next available executor or gets cancelled or gets stuck on the queue for some other reason.
void	saveArtifact(String jobName, int buildNumber, String artifactName, File outputFile) Save artifact for specified location for specific job, build number and artifact name.
void	streamLogs(String jobName, int buildNumber, LogStreamingOptions options) Streaming the build logs.
BuildTriggerStatus	triggerBuild(String jobName, Map<String,String> params) Triggers a build for the given job.
void	updateJob(String name, String gitRepo, String gitBranch, BuildDiscarder buildDiscarder) Update a Digger job on Jenkins platform
void	updateJob(String name, String gitRepo, String gitBranch, BuildDiscarder buildDiscarder, com.offbytwo.jenkins.model.credentials.Credential gitRepoCredential, List<BuildParameter> buildParameters) Update parameterized Digger job on Jenkins platform.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_BUILD_TIMEOUT

public static final long DEFAULT_BUILD_TIMEOUT

See Also:

Constant Field Values

Method Detail

createDefaultWithAuth

public static DiggerClient createDefaultWithAuth(String url,
                                                 String user,
                                                 String password)
                                          throws DiggerClientException

Create a client with defaults using provided url and credentials, with crumb flag turned off.

This client will use the defaults for the services. This is perfectly fine for majorith of the cases.

Parameters:

url - Jenkins url

user - Jenkins user

password - Jenkins password

Returns:

client instance

Throws:

DiggerClientException - if something goes wrong

createDefaultWithAuth

public static DiggerClient createDefaultWithAuth(String url,
                                                 String user,
                                                 String password,
                                                 boolean crumbFlag)
                                          throws DiggerClientException

Create a client with defaults using provided url and credentials, and specify if crumb is enabled on the Jenkins server.

Parameters:

url - Jenkins url

user - Jenkins user

password - Jenkins password

crumbFlag - If CSRF Protection is enabled on the Jenkins server

Returns:

client instance

Throws:

DiggerClientException - if something goes wrong

builder

public static DiggerClient.DiggerClientBuilder builder()

createJob

public void createJob(String name,
                      String gitRepo,
                      String gitBranch,
                      BuildDiscarder buildDiscarder)
               throws DiggerClientException

Create new Digger job on Jenkins platform with build and binary cleanup

Parameters:

name - job name that can be used later to reference job

gitRepo - git repository url (full git repository url. e.g git@github.com:wtrocki/helloworld-android-gradle.git

gitBranch - git repository branch (default branch used to checkout source code)

Throws:

DiggerClientException - if something goes wrong

createJob

public void createJob(String name,
                      String gitRepo,
                      String gitBranch,
                      BuildDiscarder buildDiscarder,
                      com.offbytwo.jenkins.model.credentials.Credential gitRepoCredential,
                      List<BuildParameter> buildParameters)
               throws DiggerClientException

Create new parameterized Digger job on Jenkins platform

Parameters:

name - job name that can be used later to reference job

gitRepo - git repository url (full git repository url. e.g git@github.com:wtrocki/helloworld-android-gradle.git

gitBranch - git repository branch (default branch used to checkout source code)

gitRepoCredential - the credential that will be used to clone the repo.

buildParameters - list of parameters for a Jenkins parameterized build.

Throws:

DiggerClientException - if something goes wrong

updateJob

public void updateJob(String name,
                      String gitRepo,
                      String gitBranch,
                      BuildDiscarder buildDiscarder)
               throws DiggerClientException

Update a Digger job on Jenkins platform

Parameters:

name - job name that can be used later to reference job

gitRepo - git repository url (full git repository url. e.g git@github.com:wtrocki/helloworld-android-gradle.git

gitBranch - git repository branch (default branch used to checkout source code)

buildDiscarder - BuildDiscarder instance. See BuildDiscarder

Throws:

DiggerClientException - if something goes wrong

updateJob

public void updateJob(String name,
                      String gitRepo,
                      String gitBranch,
                      BuildDiscarder buildDiscarder,
                      com.offbytwo.jenkins.model.credentials.Credential gitRepoCredential,
                      List<BuildParameter> buildParameters)
               throws DiggerClientException

Update parameterized Digger job on Jenkins platform.

Parameters:

name - job name that can be used later to reference job

gitRepo - git repository url (full git repository url. e.g git@github.com:wtrocki/helloworld-android-gradle.git

gitBranch - git repository branch (default branch used to checkout source code)

buildDiscarder - BuildDiscarder instance. See BuildDiscarder

gitRepoCredential - the credential that will be used to clone the repo

buildParameters - list of parameters for a Jenkins parameterized build.

Throws:

DiggerClientException - if something goes wrong

getJob

public com.offbytwo.jenkins.model.JobWithDetails getJob(String name)
                                                 throws DiggerClientException

Get a Digger job on the Jenkins platform. Null if not found.

Parameters:

name - name of the job to get

Throws:

DiggerClientException - if something goes wrong

build

public BuildTriggerStatus build(String jobName,
                                long timeout,
                                Map<String,String> params)
                         throws DiggerClientException

Triggers a build for the given job and waits until it leaves the queue and actually starts.

Jenkins puts the build requests in a queue and once there is a slave available, it starts building it and a build number is assigned to the build.

This method will block until there is a build number, or the given timeout period is passed. If the build is still in the queue after the given timeout period, a BuildStatus is returned with state BuildTriggerStatus.State#TIMED_OUT.

Please note that timeout period is never meant to be very precise. It has the resolution of BuildService.DEFAULT_POLL_PERIOD because timeout is checked before every pull.

Similarly, BuildTriggerStatus.State#CANCELLED_IN_QUEUE is returned if the build is cancelled on Jenkins side and BuildTriggerStatus.State#STUCK_IN_QUEUE is returned if the build is stuck.

Parameters:

jobName - name of the job to trigger the build

timeout - how many milliseconds should this call block before returning BuildTriggerStatus.State#TIMED_OUT. Should be larger than BuildService.DEFAULT_FIRST_CHECK_DELAY

params - build parameters to be sent to the Jenkins build

Returns:

the build status

Throws:

DiggerClientException - if connection problems occur during connecting to Jenkins

build

public BuildTriggerStatus build(String jobName,
                                long timeout)
                         throws DiggerClientException

Triggers a build for the given job and waits until it leaves the queue and actually starts.

Calls build(String, long, Map) with a default timeout of DEFAULT_BUILD_TIMEOUT and no build parameters.

Parameters:

jobName - name of the job

timeout - how many milliseconds should this call block before returning BuildTriggerStatus.State#TIMED_OUT. Should be larger than BuildService.DEFAULT_FIRST_CHECK_DELAY

Returns:

the build status

Throws:

DiggerClientException - if connection problems occur during connecting to Jenkins

See Also:

build(String, long)

triggerBuild

public BuildTriggerStatus triggerBuild(String jobName,
                                       Map<String,String> params)
                                throws DiggerClientException

Triggers a build for the given job. Unlike build(String, long, Map), this method returns immediately with the build status, which also has a queue reference in it to track the build

Parameters:

jobName - name of the job

params - build parameters to be sent to the Jenkins build

Returns:

The QueueReference

Throws:

DiggerClientException - if connection problems occur during connecting to Jenkins

pollBuild

public BuildTriggerStatus pollBuild(String jobName,
                                    com.offbytwo.jenkins.model.QueueReference queueReference,
                                    long timeout,
                                    Map<String,String> params)
                             throws DiggerClientException

This method takes a QueueReference and polls to check if a build goes to the next available executor or gets cancelled or gets stuck on the queue for some other reason.

Parameters:

queueReference - The queue reference

jobName - name of the job

timeout -

params - build parameters to be sent to the Jenkins build

Returns:

The build status

Throws:

DiggerClientException - if connection problems occur during connecting to Jenkins

build

public BuildTriggerStatus build(String jobName)
                         throws DiggerClientException

Triggers a build for the given job and waits until it leaves the queue and actually starts.

Calls build(String, long, Map) with a default timeout of DEFAULT_BUILD_TIMEOUT and no build parameters.

Parameters:

jobName - name of the job

Returns:

the build status

Throws:

DiggerClientException - if connection problems occur during connecting to Jenkins

See Also:

build(String, long)

fetchArtifact

public InputStream fetchArtifact(String jobName,
                                 int buildNumber,
                                 String artifactName)
                          throws DiggerClientException

Fetch artifacts urls for specific job and build number

Parameters:

jobName - name of the job

buildNumber - job build number

artifactName - - name of the artifact to fetch - can be regexp

Returns:

InputStream with file contents

Throws:

DiggerClientException - - when problem with fetching artifacts from jenkins

saveArtifact

public void saveArtifact(String jobName,
                         int buildNumber,
                         String artifactName,
                         File outputFile)
                  throws DiggerClientException

Save artifact for specified location for specific job, build number and artifact name. If name would be an regular expression method would return stream for the first match.

Parameters:

jobName - name of the job

buildNumber - job build number

artifactName - name of the artifact to fetch - can be regexp for example *.apk

outputFile - file (location) used to save artifact

Throws:

DiggerClientException - when problem with fetching artifacts from jenkins

getBuildLogs

public String getBuildLogs(String jobName,
                           int buildNumber)
                    throws DiggerClientException

Get build logs for specific job and build number

Parameters:

jobName - name of the job

buildNumber - job build number

Returns:

String with file contents that can be saved or piped to socket

Throws:

DiggerClientException - when problem with fetching artifacts from jenkins

getBuildHistory

public List<com.offbytwo.jenkins.model.BuildWithDetails> getBuildHistory(String jobName)
                                                                  throws DiggerClientException

Returns the build history for a job. As reported by JobWithDetails.getBuilds() it will return max 100 most-recent builds.

Please note that this approach will take some time since we first fetch the builds in 1 call, then fetch build details in 1 call per build.

Parameters:

jobName - name of the job

Returns:

the build history

Throws:

DiggerClientException - if connection problems occur

streamLogs

public void streamLogs(String jobName,
                       int buildNumber,
                       LogStreamingOptions options)
                throws DiggerClientException

Streaming the build logs.

Parameters:

jobName - the job name

buildNumber - the build number

options - See LogStreamingOptions

Throws:

DiggerClientException

deleteJob

public void deleteJob(String jobName,
                      String credentialId)
               throws DiggerClientException

Delete the job from Jenkins server.

Parameters:

jobName - the name of the job to delete.

credentialId - the id of the credential to delete. It should be the same id value if gitRepoCredential is provided in #createJob(String, String, String, Credential, List) and it has an id value. Otherwise pass null.

Throws:

DiggerClientException

getBuildDetails

public com.offbytwo.jenkins.model.BuildWithDetails getBuildDetails(String jobName,
                                                                   int buildNumber)
                                                            throws DiggerClientException

Get the details about a build.

Parameters:

jobName - the name of the job

buildNumber - the build number

Returns:

the build details

Throws:

DiggerClientException

cancelBuild

public com.offbytwo.jenkins.model.BuildWithDetails cancelBuild(String jobName,
                                                               int buildNumber)
                                                        throws DiggerClientException

Cancel a build for a specific job

Parameters:

jobName - the name of the job

buildNumber - the build number

Throws:

DiggerClientException

getJenkinsServer

public com.offbytwo.jenkins.JenkinsServer getJenkinsServer()

Expose the underline Jenkins Server client to allow perform other operations that may not be implemented by the jenkins digger client.

Returns:

the instance of the jenkins server