com.offbytwo.jenkins

Class JenkinsServer

java.lang.Object

com.offbytwo.jenkins.JenkinsServer

All Implemented Interfaces:

Closeable, AutoCloseable

public class JenkinsServer
extends Object
implements Closeable

The main starting point for interacting with a Jenkins server.

Constructor Summary

Constructors

Constructor and Description
JenkinsServer(JenkinsHttpConnection 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

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	close() Closes underlying resources.
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	createView(FolderJob folder, String viewName, String viewXml) Create a view on the server using the provided xml and in the provided folder.
void	createView(FolderJob folder, String viewName, String viewXml, Boolean crumbFlag) Create a view on the server using the provided xml and in the provided folder.
void	createView(String viewName, String viewXml) Create a view on the server using the provided xml
void	createView(String viewName, String viewXml, Boolean crumbFlag) Create a view on the server using the provided xml.
void	deleteJob(FolderJob folder, String jobName) Delete a job from Jenkins within a folder.
void	deleteJob(FolderJob folder, String jobName, boolean crumbFlag) Delete a job from Jenkins within a folder.
void	deleteJob(String jobName) Delete a job from jenkins
void	deleteJob(String jobName, boolean crumbFlag) Delete a job from Jenkins.
void	disableJob(String jobName) Disable a job from jenkins
void	disableJob(String jobName, boolean crumbFlag) Disable a job from Jenkins.
void	enableJob(String jobName) Enable a job from jenkins
void	enableJob(String jobName, boolean crumbFlag) Enable a job from Jenkins.
void	exit(Boolean crumbFlag) Shutdown Jenkins without waiting for any existing build to complete
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(FolderJob folder, String jobName) Get the xml description of an existing job.
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)
JenkinsVersion	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
void	restart(Boolean crumbFlag) Restart Jenkins without waiting for any existing build to complete
String	runScript(String script) Runs the provided groovy script on the server and returns the result.
String	runScript(String script, boolean crumbFlag) Runs the provided groovy script on the server and returns the result.
void	safeExit(Boolean crumbFlag) safeExit: Puts Jenkins into the quiet mode, wait for existing builds to be completed, and then shut down Jenkins
void	safeRestart(Boolean crumbFlag) safeRestart: Puts Jenkins into the quiet mode, wait for existing builds to be completed, and then restart Jenkins
void	updateJob(FolderJob folder, String jobName, String jobXml, boolean crumbFlag) Update the xml description of an existing job
void	updateJob(String jobName, String jobXml) Update the xml description of an existing job
void	updateJob(String jobName, String jobXml, boolean crumbFlag) Update the xml description of an existing job
void	updateView(FolderJob folder, String viewName, String viewXml)
void	updateView(FolderJob folder, String viewName, String viewXml, boolean crumbFlag)
void	updateView(String viewName, String viewXml) Update the xml description of an existing view
void	updateView(String viewName, String viewXml, 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(JenkinsHttpConnection 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 JenkinsVersion getVersion()

Returns:

JenkinsVersion

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 - in case of an error.

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)

Parameters:

folder - FolderJob

Returns:

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

Throws:

IOException - in case of an error.

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)

Parameters:

view - The view to get jobs from.

Returns:

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

Throws:

IOException - in case of an error.

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)

Parameters:

folder - FolderJob

view - The view to use.

Returns:

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

Throws:

IOException - in case of an error.

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 - in case of an error.

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)

Parameters:

folder - FolderJob

Returns:

list of defined views

Throws:

IOException - in case of an error.

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 - in case of an error.

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 - in case of an error.

getJob

public JobWithDetails getJob(String jobName)
                      throws IOException

Get a single Job from the server.

Parameters:

jobName - name of the job to get details of.

Returns:

A single Job, null if not present

Throws:

IOException - in case of an error.

getJob

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

Get a single Job from the given folder.

Parameters:

folder - FolderJob

jobName - name of the job to get details of.

Returns:

A single Job, null if not present

Throws:

IOException - in case of an error.

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

Parameters:

jobName - name of the job to be created.

jobXml - the config.xml which should be used to create the job.

Throws:

IOException - in case of an error.

createJob

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

Create a job on the server using the provided xml

Parameters:

jobName - name of the job to be created.

jobXml - the config.xml which should be used to create the job.

crumbFlag - true to add crumbIssuer false otherwise.

Throws:

IOException - in case of an error.

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

Parameters:

folder - FolderJob

jobName - name of the job to be created.

jobXml - the config.xml which should be used to create the job.

Throws:

IOException - in case of an error.

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

Parameters:

folder - FolderJob

jobName - name of the job to be created.

jobXml - the config.xml which should be used to create the job.

crumbFlag - true to add crumbIssuer false otherwise.

Throws:

IOException - in case of an error.

createView

public void createView(String viewName,
                       String viewXml)
                throws IOException

Create a view on the server using the provided xml

Parameters:

viewName - name of the view to be created.

viewXml - The configuration for the view.

Throws:

IOException - in case of an error.

createView

public void createView(String viewName,
                       String viewXml,
                       Boolean crumbFlag)
                throws IOException

Create a view on the server using the provided xml.

Parameters:

viewName - name of the view to be created.

viewXml - The configuration for the view.

crumbFlag - true to add crumbIssuer false otherwise.

Throws:

IOException - in case of an error.

createView

public void createView(FolderJob folder,
                       String viewName,
                       String viewXml)
                throws IOException

Create a view on the server using the provided xml and in the provided folder.

Parameters:

folder - FolderJob

viewName - name of the view to be created.

viewXml - The configuration for the view.

Throws:

IOException - in case of an error.

createView

public void createView(FolderJob folder,
                       String viewName,
                       String viewXml,
                       Boolean crumbFlag)
                throws IOException

Create a view on the server using the provided xml and in the provided folder.

Parameters:

folder - the folder.

viewName - the view name.

viewXml - the view xml.

crumbFlag - true to add crumbIssuer false otherwise.

Throws:

IOException - in case of an error.

createFolder

public void createFolder(String folderName)
                  throws IOException

Create a folder on the server (in the root)

Parameters:

folderName - name of the folder.

Throws:

IOException - in case of an error.

createFolder

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

Create a folder on the server (in the root)

Parameters:

folderName - name of the folder.

crumbFlag - true to add crumbIssuer false otherwise.

Throws:

IOException - in case of an error.

createFolder

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

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

Parameters:

folder - FolderJob

jobName - name of the job.

Throws:

IOException - in case of an error.

createFolder

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

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

Parameters:

folder - FolderJob

jobName - name of the job.

crumbFlag - true to add crumbIssuer false otherwise.

Throws:

IOException - in case of an error.

getJobXml

public String getJobXml(String jobName)
                 throws IOException

Get the xml description of an existing job

Parameters:

jobName - name of the job.

Returns:

the new job object

Throws:

IOException - in case of an error.

getJobXml

public String getJobXml(FolderJob folder,
                        String jobName)
                 throws IOException

Get the xml description of an existing job.

Parameters:

jobName - name of the job.

folder - FolderJob

Returns:

the new job object

Throws:

IOException - in case of an error.

getLabel

public LabelWithDetails getLabel(String labelName)
                          throws IOException

Get the description of an existing Label

Parameters:

labelName - name of the label.

Returns:

LabelWithDetails

Throws:

IOException - in case of an error.

getComputers

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

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

Returns:

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

Throws:

IOException - in case of an error.

getComputerSet

public ComputerSet getComputerSet()
                           throws IOException

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

Returns:

ComputerSet

Throws:

IOException - in case of an error.

getPluginManager

public PluginManager getPluginManager()
                               throws IOException

This will give you back the PluginManager.

Returns:

PluginManager

Throws:

IOException - in case of a failure.

updateView

public void updateView(String viewName,
                       String viewXml)
                throws IOException

Update the xml description of an existing view

Parameters:

viewName - name of the view.

viewXml - the view configuration.

Throws:

IOException - in case of an error.

updateView

public void updateView(String viewName,
                       String viewXml,
                       boolean crumbFlag)
                throws IOException

Throws:

IOException

updateView

public void updateView(FolderJob folder,
                       String viewName,
                       String viewXml)
                throws IOException

Throws:

IOException

updateView

public void updateView(FolderJob folder,
                       String viewName,
                       String viewXml,
                       boolean crumbFlag)
                throws IOException

Throws:

IOException

updateJob

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

Update the xml description of an existing job

Parameters:

jobName - name of the job to be updated.

jobXml - the configuration to be used for updating.

Throws:

IOException - in case of an error.

updateJob

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

Update the xml description of an existing job

Parameters:

jobName - name of the job to be updated.

jobXml - the configuration to be used for updating.

crumbFlag - true/false.

Throws:

IOException - in case of an error.

updateJob

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

Update the xml description of an existing job

Parameters:

folder - the folder.

jobName - the name of the job.

jobXml - the job xml configuration.

crumbFlag - true/false.

Throws:

IOException - in case of an error.

addStringParam

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

Parameters:

jobName - name of the job.

name - name of the parameter.

description - of the parameters.

defaultValue - the defaultValue for the parameters.

Throws:

IOException - in case of an error.

JAXBException - in case of an error.

org.dom4j.DocumentException - in case of an error.

quietDown

public void quietDown()
               throws IOException

Sends the Quiet Down (Prepare for shutdown) message

Throws:

IOException - in case of an error.

cancelQuietDown

public void cancelQuietDown()
                     throws IOException

Cancels the Quiet Down (Prepare for shutdown) message

Throws:

IOException - in case of an error.

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 an error.

deleteJob

public void deleteJob(FolderJob folder,
                      String jobName,
                      boolean crumbFlag)
               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.

crumbFlag - The crumbFlag

Throws:

IOException - in case of problems.

deleteJob

public void deleteJob(String jobName)
               throws IOException

Delete a job from jenkins

Parameters:

jobName - The name of the job which should be deleted.

Throws:

IOException - in case of an error.

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 - true to add crumbIssuer false otherwise.

Throws:

IOException - In case of an failure.

disableJob

public void disableJob(String jobName)
                throws IOException

Disable a job from jenkins

Parameters:

jobName - The name of the job which should be disabled.

Throws:

IOException - in case of an error.

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 - true to add crumbIssuer false otherwise.

Throws:

IOException - In case of an failure.

enableJob

public void enableJob(String jobName)
               throws IOException

Enable a job from jenkins

Parameters:

jobName - name of the job which should be enabled.

Throws:

IOException - In case of an failure.

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 - true to add crumbIssuer false otherwise.

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 - The script to be executed.

Returns:

results The results of the script.

Throws:

IOException - in case of an error.

runScript

public String runScript(String script,
                        boolean crumbFlag)
                 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 - The script to run.

crumbFlag - true to add crumbIssuer false otherwise.

Returns:

results The results of the run of the script.

Throws:

IOException - in case of an error.

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:

folder - FolderJob

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:

folder - FolderJob

oldJobName - existing job name.

newJobName - The new job name.

crumbFlag - true to add crumbIssuer false otherwise.

Throws:

IOException - In case of a failure.

close

public void close()

Closes underlying resources. Closed instances should no longer be used Closing an already closed instance has no side effects

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

restart

public void restart(Boolean crumbFlag)
             throws IOException

Restart Jenkins without waiting for any existing build to complete

Parameters:

crumbFlag - true to add crumbIssuer false otherwise.

Throws:

IOException - in case of an error.

safeRestart

public void safeRestart(Boolean crumbFlag)
                 throws IOException

safeRestart: Puts Jenkins into the quiet mode, wait for existing builds to be completed, and then restart Jenkins

Parameters:

crumbFlag - true to add crumbIssuer false otherwise.

Throws:

IOException - in case of an error.

exit

public void exit(Boolean crumbFlag)
          throws IOException

Shutdown Jenkins without waiting for any existing build to complete

Parameters:

crumbFlag - true to add crumbIssuer false otherwise.

Throws:

IOException - in case of an error.

safeExit

public void safeExit(Boolean crumbFlag)
              throws IOException

safeExit: Puts Jenkins into the quiet mode, wait for existing builds to be completed, and then shut down Jenkins

Parameters:

crumbFlag - true to add crumbIssuer false otherwise.

Throws:

IOException - in case of an error.