com.offbytwo.jenkins

Class JenkinsServer

java.lang.Object

com.offbytwo.jenkins.JenkinsServer

public class JenkinsServer
extends Object

The main starting point for interacting with a Jenkins server.

Constructor Summary

Constructors

Constructor and Description
JenkinsServer(JenkinsHttpClient client) Create a new Jenkins server directly from an HTTP client (ADVANCED)
JenkinsServer(URI serverUri) Create a new Jenkins server reference given only the server address
JenkinsServer(URI serverUri, String username, String passwordOrToken) Create a new Jenkins server reference given the address and credentials

Method Summary

Methods

Modifier and Type	Method and Description
void	addStringParam(String jobName, String name, String description, String defaultValue)
void	cancelQuietDown() Cancels the Quiet Down (Prepare for shutdown) message
void	createFolder(FolderJob folder, String jobName) Create a job on the server (in the given folder)
void	createFolder(FolderJob folder, String jobName, Boolean crumbFlag) Create a job on the server (in the given folder)
void	createFolder(String folderName) Create a folder on the server (in the root)
void	createFolder(String folderName, Boolean crumbFlag) Create a folder on the server (in the root)
void	createJob(FolderJob folder, String jobName, String jobXml) Create a job on the server using the provided xml and in the provided folder
void	createJob(FolderJob folder, String jobName, String jobXml, Boolean crumbFlag) Create a job on the server using the provided xml and in the provided folder
void	createJob(String jobName, String jobXml) Create a job on the server using the provided xml
void	createJob(String jobName, String jobXml, Boolean crumbFlag) Create a job on the server using the provided xml
void	deleteJob(FolderJob folder, String jobName) Delete a job from Jenkins within a folder.
void	deleteJob(String jobName)
void	deleteJob(String jobName, boolean crumbFlag) Delete a job from Jenkins.
void	disableJob(String jobName)
void	disableJob(String jobName, boolean crumbFlag) Disable a job from Jenkins.
void	enableJob(String jobName)
void	enableJob(String jobName, boolean crumbFlag) Enable a job from Jenkins.
Build	getBuild(QueueItem q)
Map<String,Computer>	getComputers() Get a list of all the computers on the server (at the summary level)
ComputerSet	getComputerSet() The ComputerSet class will give informations like ComputerSet.getBusyExecutors() or the ComputerSet.getTotalExecutors().
com.google.common.base.Optional<FolderJob>	getFolderJob(Job job)
JobWithDetails	getJob(FolderJob folder, String jobName) Get a single Job from the given folder.
JobWithDetails	getJob(String jobName) Get a single Job from the server.
Map<String,Job>	getJobs() Get a list of all the defined jobs on the server (at the summary level)
Map<String,Job>	getJobs(FolderJob folder) Get a list of all the defined jobs on the server (in the given folder)
Map<String,Job>	getJobs(FolderJob folder, String view) Get a list of all the defined jobs on the server (at the specified view level and in the specified folder)
Map<String,Job>	getJobs(String view) Get a list of all the defined jobs on the server (at the specified view level)
String	getJobXml(String jobName) Get the xml description of an existing job
LabelWithDetails	getLabel(String labelName) Get the description of an existing Label
MavenJobWithDetails	getMavenJob(FolderJob folder, String jobName)
MavenJobWithDetails	getMavenJob(String jobName)
PluginManager	getPluginManager() This will give you back the PluginManager.
Queue	getQueue()
QueueItem	getQueueItem(QueueReference ref)
String	getVersion()
View	getView(FolderJob folder, String name) Get a single view object from the given folder
View	getView(String name) Get a single view object from the server
Map<String,View>	getViews() Get a list of all the defined views on the server (at the summary level)
Map<String,View>	getViews(FolderJob folder) Get a list of all the defined views on the server (at the summary level and in the given folder)
boolean	isRunning() Get the current status of the Jenkins end-point by pinging it.
void	quietDown() Sends the Quiet Down (Prepare for shutdown) message
void	renameJob(FolderJob folder, String oldJobName, String newJobName) Rename a job
void	renameJob(FolderJob folder, String oldJobName, String newJobName, Boolean crumbFlag) Rename a job
void	renameJob(String oldJobName, String newJobName) Rename a job
void	renameJob(String oldJobName, String newJobName, Boolean crumbFlag) Rename a job
String	runScript(String script) Runs the provided groovy script on the server and returns the result.
void	updateJob(String jobName, String jobXml) Update the xml description of an existing job
void	updateJob(String jobName, String jobXml, boolean crumbFlag)

Methods inherited from class java.lang.Object

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

Constructor Detail

JenkinsServer

public JenkinsServer(URI serverUri)

Create a new Jenkins server reference given only the server address

Parameters:

serverUri - address of jenkins server (ex. http://localhost:8080/jenkins)

JenkinsServer

public JenkinsServer(URI serverUri,
             String username,
             String passwordOrToken)

Create a new Jenkins server reference given the address and credentials

Parameters:

serverUri - address of jenkins server (ex. http://localhost:8080/jenkins)

username - username to use when connecting

passwordOrToken - password (not recommended) or token (recommended)

JenkinsServer

public JenkinsServer(JenkinsHttpClient client)

Create a new Jenkins server directly from an HTTP client (ADVANCED)

Parameters:

client - Specialized client to use.

Method Detail

isRunning

public boolean isRunning()

Get the current status of the Jenkins end-point by pinging it.

Returns:

true if Jenkins is up and running, false otherwise

getVersion

public String getVersion()

Returns:

The Jenkins version.

getJobs

public Map<String,Job> getJobs()
                        throws IOException

Get a list of all the defined jobs on the server (at the summary level)

Returns:

list of defined jobs (summary level, for details @see Job#details

Throws:

IOException

getJobs

public Map<String,Job> getJobs(FolderJob folder)
                        throws IOException

Get a list of all the defined jobs on the server (in the given folder)

Returns:

list of defined jobs (summary level, for details @see Job#details

Throws:

IOException

getJobs

public Map<String,Job> getJobs(String view)
                        throws IOException

Get a list of all the defined jobs on the server (at the specified view level)

Returns:

list of defined jobs (view level, for details @see Job#details

Throws:

IOException

getJobs

public Map<String,Job> getJobs(FolderJob folder,
                      String view)
                        throws IOException

Get a list of all the defined jobs on the server (at the specified view level and in the specified folder)

Returns:

list of defined jobs (view level, for details @see Job#details

Throws:

IOException

getViews

public Map<String,View> getViews()
                          throws IOException

Get a list of all the defined views on the server (at the summary level)

Returns:

list of defined views

Throws:

IOException

getViews

public Map<String,View> getViews(FolderJob folder)
                          throws IOException

Get a list of all the defined views on the server (at the summary level and in the given folder)

Returns:

list of defined views

Throws:

IOException

getView

public View getView(String name)
             throws IOException

Get a single view object from the server

Parameters:

name - name of the view in Jenkins

Returns:

the view object

Throws:

IOException

getView

public View getView(FolderJob folder,
           String name)
             throws IOException

Get a single view object from the given folder

Parameters:

folder - The name of the folder.

name - name of the view in Jenkins

Returns:

the view object

Throws:

IOException

getJob

public JobWithDetails getJob(String jobName)
                      throws IOException

Get a single Job from the server.

Returns:

A single Job, null if not present

Throws:

IOException

getJob

public JobWithDetails getJob(FolderJob folder,
                    String jobName)
                      throws IOException

Get a single Job from the given folder.

Returns:

A single Job, null if not present

Throws:

IOException

getMavenJob

public MavenJobWithDetails getMavenJob(String jobName)
                                throws IOException

Throws:

IOException

getMavenJob

public MavenJobWithDetails getMavenJob(FolderJob folder,
                              String jobName)
                                throws IOException

Throws:

IOException

getFolderJob

public com.google.common.base.Optional<FolderJob> getFolderJob(Job job)
                                                        throws IOException

Throws:

IOException

createJob

public void createJob(String jobName,
             String jobXml)
               throws IOException

Create a job on the server using the provided xml

Throws:

IOException

createJob

public void createJob(String jobName,
             String jobXml,
             Boolean crumbFlag)
               throws IOException

Create a job on the server using the provided xml

Throws:

IOException

createJob

public void createJob(FolderJob folder,
             String jobName,
             String jobXml)
               throws IOException

Create a job on the server using the provided xml and in the provided folder

Throws:

IOException

createJob

public void createJob(FolderJob folder,
             String jobName,
             String jobXml,
             Boolean crumbFlag)
               throws IOException

Create a job on the server using the provided xml and in the provided folder

Throws:

IOException

createFolder

public void createFolder(String folderName)
                  throws IOException

Create a folder on the server (in the root)

Throws:

IOException

createFolder

public void createFolder(String folderName,
                Boolean crumbFlag)
                  throws IOException

Create a folder on the server (in the root)

Throws:

IOException

createFolder

public void createFolder(FolderJob folder,
                String jobName)
                  throws IOException

Create a job on the server (in the given folder)

Throws:

IOException

createFolder

public void createFolder(FolderJob folder,
                String jobName,
                Boolean crumbFlag)
                  throws IOException

Create a job on the server (in the given folder)

Throws:

IOException

getJobXml

public String getJobXml(String jobName)
                 throws IOException

Get the xml description of an existing job

Returns:

the new job object

Throws:

IOException

getLabel

public LabelWithDetails getLabel(String labelName)
                          throws IOException

Get the description of an existing Label

Returns:

label object

Throws:

IOException

getComputers

public Map<String,Computer> getComputers()
                                  throws IOException

Get a list of all the computers on the server (at the summary level)

Returns:

list of defined computers (summary level, for details @see Computer#details

Throws:

IOException

getComputerSet

public ComputerSet getComputerSet()
                           throws IOException

The ComputerSet class will give informations like ComputerSet.getBusyExecutors() or the ComputerSet.getTotalExecutors().

Returns:

ComputerSet

Throws:

IOException

getPluginManager

public PluginManager getPluginManager()
                               throws IOException

This will give you back the PluginManager.

Returns:

PluginManager

Throws:

IOException - in case of a failure.

updateJob

public void updateJob(String jobName,
             String jobXml)
               throws IOException

Update the xml description of an existing job

Throws:

IOException

updateJob

public void updateJob(String jobName,
             String jobXml,
             boolean crumbFlag)
               throws IOException

Throws:

IOException

addStringParam

public void addStringParam(String jobName,
                  String name,
                  String description,
                  String defaultValue)
                    throws IOException,
                           JAXBException,
                           org.dom4j.DocumentException

Throws:

IOException

JAXBException

org.dom4j.DocumentException

quietDown

public void quietDown()
               throws IOException

Sends the Quiet Down (Prepare for shutdown) message

Throws:

IOException

cancelQuietDown

public void cancelQuietDown()
                     throws IOException

Cancels the Quiet Down (Prepare for shutdown) message

Throws:

IOException

deleteJob

public void deleteJob(String jobName)
               throws IOException

Throws:

IOException

deleteJob

public void deleteJob(FolderJob folder,
             String jobName)
               throws IOException

Delete a job from Jenkins within a folder.

Parameters:

folder - The folder where the given job is located.

jobName - The job which should be deleted.

Throws:

IOException - in case of problems.

deleteJob

public void deleteJob(String jobName,
             boolean crumbFlag)
               throws IOException

Delete a job from Jenkins.

Parameters:

jobName - The name of the job to be deleted.

crumbFlag - The crumFlag.

Throws:

IOException - In case of an failure.

disableJob

public void disableJob(String jobName)
                throws IOException

Throws:

IOException

disableJob

public void disableJob(String jobName,
              boolean crumbFlag)
                throws IOException

Disable a job from Jenkins.

Parameters:

jobName - The name of the job to be deleted.

crumbFlag - The crumFlag.

Throws:

IOException - In case of an failure.

enableJob

public void enableJob(String jobName)
               throws IOException

Throws:

IOException

enableJob

public void enableJob(String jobName,
             boolean crumbFlag)
               throws IOException

Enable a job from Jenkins.

Parameters:

jobName - The name of the job to be deleted.

crumbFlag - The crumFlag.

Throws:

IOException - In case of an failure.

runScript

public String runScript(String script)
                 throws IOException

Runs the provided groovy script on the server and returns the result. This is similar to running groovy scripts using the script console. In the instance where your script causes an exception, the server still returns a 200 status, so detecting errors is very challenging. It is recommended to use heuristics to check your return string for stack traces by detecting strings like "groovy.lang.(something)Exception".

Parameters:

script -

Returns:

results

Throws:

IOException

getQueue

public Queue getQueue()
               throws IOException

Throws:

IOException

getQueueItem

public QueueItem getQueueItem(QueueReference ref)
                       throws IOException

Throws:

IOException

getBuild

public Build getBuild(QueueItem q)
               throws IOException

Throws:

IOException

renameJob

public void renameJob(String oldJobName,
             String newJobName)
               throws IOException

Rename a job

Parameters:

oldJobName - existing job name.

newJobName - The new job name.

Throws:

IOException - In case of a failure.

renameJob

public void renameJob(String oldJobName,
             String newJobName,
             Boolean crumbFlag)
               throws IOException

Rename a job

Parameters:

oldJobName - existing job name.

newJobName - The new job name.

crumbFlag - true to add crumbIssuer false otherwise.

Throws:

IOException - In case of a failure.

renameJob

public void renameJob(FolderJob folder,
             String oldJobName,
             String newJobName)
               throws IOException

Rename a job

Parameters:

FolderJob - The folder.

oldJobName - existing job name.

newJobName - The new job name.

Throws:

IOException - In case of a failure.

renameJob

public void renameJob(FolderJob folder,
             String oldJobName,
             String newJobName,
             Boolean crumbFlag)
               throws IOException

Rename a job

Parameters:

FolderJob - The folder.

oldJobName - existing job name.

newJobName - The new job name.

crumbFlag - true to add crumbIssuer false otherwise.

Throws:

IOException - In case of a failure.