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	createJob(String jobName, String jobXml) Create a job on the server using the provided xml
void	createJob(String jobName, String jobXml, Boolean crumbFlag)
void	deleteJob(String jobName)
void	deleteJob(String jobName, boolean crumbFlag) Delete 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().
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(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(String jobName)
QueueItem	getQueueItem(QueueReference ref)
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)
boolean	isRunning() Get the current status of the Jenkins end-point by pinging it.
void	quietDown() Sends the Quiet Down (Prepare for shutdown) message
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

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

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

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

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

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

getMavenJob

public MavenJobWithDetails getMavenJob(String jobName)
                                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

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

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(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.

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

getQueueItem

public QueueItem getQueueItem(QueueReference ref)
                       throws IOException

Throws:

IOException

getBuild

public Build getBuild(QueueItem q)
               throws IOException

Throws:

IOException