org.rundeck.api
Class RundeckClient

java.lang.Object
  org.rundeck.api.RundeckClient

All Implemented Interfaces:

Serializable

public class RundeckClient
extends Object
implements Serializable

Main entry point to talk to a RunDeck instance.
Usage :

 RundeckClient rundeck = new RundeckClient("http://localhost:4440", "admin", "admin");
 List<RundeckJob> jobs = rundeck.getJobs();
 
 RundeckJob job = rundeck.findJob("my-project", "main-group/sub-group", "job-name");
 RundeckExecution execution = rundeck.triggerJob(job.getId(),
                                                 new OptionsBuilder().addOption("version", "1.2.0").toProperties());
 
 List<RundeckExecution> runningExecutions = rundeck.getRunningExecutions("my-project");
 

Author:

Vincent Behar

See Also:

Serialized Form

Field Summary

static String	API_ENDPOINT
static int	API_VERSION

Constructor Summary

RundeckClient(String url, String login, String password)
Instantiate a new RundeckClient for the RunDeck instance at the given url

Method Summary

RundeckAbort	abortExecution(Long executionId) Abort an execution (identified by the given ID).
String	deleteJob(String jobId) Delete a single job, identified by the given ID
boolean	equals(Object obj)
InputStream	exportJob(String jobId) Export the definition of a single job, identified by the given ID
InputStream	exportJobs(String project) Export the definitions of all jobs that belongs to the given project
InputStream	exportJobs(String project, String jobFilter, String groupPath, String... jobIds) Export the definitions of the jobs that belongs to the given project, and matches the given criteria (jobFilter, groupPath and jobIds)
void	exportJobsToFile(String filename, String project) Export the definitions of all jobs that belongs to the given project, as an XML file
void	exportJobsToFile(String filename, String project, String jobFilter, String groupPath, String... jobIds) Export the definitions of the jobs that belongs to the given project, and matches the given criteria (jobFilter, groupPath and jobIds), as an XML file
void	exportJobToFile(String filename, String jobId) Export the definition of a single job (identified by the given ID), as an XML file
RundeckJob	findJob(String project, String groupPath, String name) Find a job, identified by its project, group and name.
RundeckExecution	getExecution(Long executionId) Get a single execution, identified by the given ID
RundeckJob	getJob(String jobId) Get the definition of a single job, identified by the given ID
List<RundeckExecution>	getJobExecutions(String jobId) Get the executions of the given job
List<RundeckExecution>	getJobExecutions(String jobId, RundeckExecution.ExecutionStatus status) Get the executions of the given job
List<RundeckExecution>	getJobExecutions(String jobId, RundeckExecution.ExecutionStatus status, Long max, Long offset) Get the executions of the given job
List<RundeckJob>	getJobs() List all jobs (for all projects)
List<RundeckJob>	getJobs(String project) List all jobs that belongs to the given project
List<RundeckJob>	getJobs(String project, String jobFilter, String groupPath, String... jobIds) List the jobs that belongs to the given project, and matches the given criteria (jobFilter, groupPath and jobIds)
String	getLogin()
RundeckNode	getNode(String name, String project) Get the definition of a single node
List<RundeckNode>	getNodes() List all nodes (for all projects)
List<RundeckNode>	getNodes(String project) List all nodes that belongs to the given project
List<RundeckNode>	getNodes(String project, Properties nodeFilters) List nodes that belongs to the given project
String	getPassword()
RundeckProject	getProject(String projectName) Get the definition of a single project, identified by the given name
List<RundeckProject>	getProjects() List all projects
List<RundeckExecution>	getRunningExecutions() Get all running executions (for all projects)
List<RundeckExecution>	getRunningExecutions(String project) Get the running executions for the given project
RundeckSystemInfo	getSystemInfo() Get system informations about the RunDeck server
String	getUrl()
int	hashCode()
void	ping() Try to "ping" the RunDeck instance to see if it is alive
RundeckExecution	runAdhocCommand(String project, String command) Run an ad-hoc command, and wait until its execution is finished (or aborted) to return.
RundeckExecution	runAdhocCommand(String project, String command, long poolingInterval, TimeUnit poolingUnit) Run an ad-hoc command, and wait until its execution is finished (or aborted) to return.
RundeckExecution	runAdhocCommand(String project, String command, Properties nodeFilters) Run an ad-hoc command, and wait until its execution is finished (or aborted) to return.
RundeckExecution	runAdhocCommand(String project, String command, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing) Run an ad-hoc command, and wait until its execution is finished (or aborted) to return.
RundeckExecution	runAdhocCommand(String project, String command, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing, long poolingInterval, TimeUnit poolingUnit) Run an ad-hoc command, and wait until its execution is finished (or aborted) to return.
RundeckExecution	runAdhocCommand(String project, String command, Properties nodeFilters, long poolingInterval, TimeUnit poolingUnit) Run an ad-hoc command, and wait until its execution is finished (or aborted) to return.
RundeckExecution	runJob(String jobId) Run a RunDeck job (identified by the given ID), and wait until its execution is finished (or aborted) to return.
RundeckExecution	runJob(String jobId, Properties options) Run a RunDeck job (identified by the given ID), and wait until its execution is finished (or aborted) to return.
RundeckExecution	runJob(String jobId, Properties options, long poolingInterval, TimeUnit poolingUnit) Run a RunDeck job (identified by the given ID), and wait until its execution is finished (or aborted) to return.
RundeckExecution	runJob(String jobId, Properties options, Properties nodeFilters) Run a RunDeck job (identified by the given ID), and wait until its execution is finished (or aborted) to return.
RundeckExecution	runJob(String jobId, Properties options, Properties nodeFilters, long poolingInterval, TimeUnit poolingUnit) Run a RunDeck job (identified by the given ID), and wait until its execution is finished (or aborted) to return.
void	testCredentials() Test your credentials (login/password) on the RunDeck instance
String	toString()
RundeckExecution	triggerAdhocCommand(String project, String command) Trigger the execution of an ad-hoc command, and return immediately (without waiting the end of the execution).
RundeckExecution	triggerAdhocCommand(String project, String command, Properties nodeFilters) Trigger the execution of an ad-hoc command, and return immediately (without waiting the end of the execution).
RundeckExecution	triggerAdhocCommand(String project, String command, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing) Trigger the execution of an ad-hoc command, and return immediately (without waiting the end of the execution).
RundeckExecution	triggerJob(String jobId) Trigger the execution of a RunDeck job (identified by the given ID), and return immediately (without waiting the end of the job execution)
RundeckExecution	triggerJob(String jobId, Properties options) Trigger the execution of a RunDeck job (identified by the given ID), and return immediately (without waiting the end of the job execution)
RundeckExecution	triggerJob(String jobId, Properties options, Properties nodeFilters) Trigger the execution of a RunDeck job (identified by the given ID), and return immediately (without waiting the end of the job execution)

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

API_VERSION

public static final transient int API_VERSION

See Also:

Constant Field Values

API_ENDPOINT

public static final transient String API_ENDPOINT

See Also:

Constant Field Values

Constructor Detail

RundeckClient

public RundeckClient(String url,
                     String login,
                     String password)
              throws IllegalArgumentException

Instantiate a new RundeckClient for the RunDeck instance at the given url

Parameters:

url - of the RunDeck instance ("http://localhost:4440", "http://rundeck.your-compagny.com/", etc)

login -

password -

Throws:

IllegalArgumentException - if the url, login or password is blank (null, empty or whitespace)

Method Detail

ping

public void ping()
          throws RundeckApiException

Try to "ping" the RunDeck instance to see if it is alive

Throws:

RundeckApiException - if the ping fails

testCredentials

public void testCredentials()
                     throws RundeckApiException.RundeckApiLoginException

Test your credentials (login/password) on the RunDeck instance

Throws:

RundeckApiException.RundeckApiLoginException - if the login fails

getProjects

public List<RundeckProject> getProjects()
                                 throws RundeckApiException,
                                        RundeckApiException.RundeckApiLoginException

List all projects

Returns:

a List of RundeckProject : might be empty, but won't be null

Throws:

RundeckApiException - in case of error when calling the API

RundeckApiException.RundeckApiLoginException - if the login failed

getProject

public RundeckProject getProject(String projectName)
                          throws RundeckApiException,
                                 RundeckApiException.RundeckApiLoginException,
                                 IllegalArgumentException

Get the definition of a single project, identified by the given name

Parameters:

projectName - name of the project - mandatory

Returns:

a RundeckProject instance - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the projectName is blank (null, empty or whitespace)

getJobs

public List<RundeckJob> getJobs()
                         throws RundeckApiException,
                                RundeckApiException.RundeckApiLoginException

List all jobs (for all projects)

Returns:

a List of RundeckJob : might be empty, but won't be null

Throws:

RundeckApiException - in case of error when calling the API

RundeckApiException.RundeckApiLoginException - if the login failed

getJobs

public List<RundeckJob> getJobs(String project)
                         throws RundeckApiException,
                                RundeckApiException.RundeckApiLoginException,
                                IllegalArgumentException

List all jobs that belongs to the given project

Parameters:

project - name of the project - mandatory

Returns:

a List of RundeckJob : might be empty, but won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the project is blank (null, empty or whitespace)

See Also:

getJobs(String, String, String, String...)

getJobs

public List<RundeckJob> getJobs(String project,
                                String jobFilter,
                                String groupPath,
                                String... jobIds)
                         throws RundeckApiException,
                                RundeckApiException.RundeckApiLoginException,
                                IllegalArgumentException

List the jobs that belongs to the given project, and matches the given criteria (jobFilter, groupPath and jobIds)

Parameters:

project - name of the project - mandatory

jobFilter - a filter for the job Name - optional

groupPath - a group or partial group path to include all jobs within that group path - optional

jobIds - a list of Job IDs to include - optional

Returns:

a List of RundeckJob : might be empty, but won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the project is blank (null, empty or whitespace)

See Also:

getJobs(String)

exportJobsToFile

public void exportJobsToFile(String filename,
                             String project)
                      throws RundeckApiException,
                             RundeckApiException.RundeckApiLoginException,
                             IllegalArgumentException,
                             IOException

Export the definitions of all jobs that belongs to the given project, as an XML file

Parameters:

filename - path of the file where the content should be saved

project - name of the project - mandatory

Throws:

RundeckApiException - in case of error when calling the API (non-existent project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the project is blank (null, empty or whitespace)

IOException - if we failed to write to the file

See Also:

exportJobsToFile(String, String, String, String, String...), exportJobs(String)

exportJobsToFile

public void exportJobsToFile(String filename,
                             String project,
                             String jobFilter,
                             String groupPath,
                             String... jobIds)
                      throws RundeckApiException,
                             RundeckApiException.RundeckApiLoginException,
                             IllegalArgumentException,
                             IOException

Export the definitions of the jobs that belongs to the given project, and matches the given criteria (jobFilter, groupPath and jobIds), as an XML file

Parameters:

filename - path of the file where the content should be saved

project - name of the project - mandatory

jobFilter - a filter for the job Name - optional

groupPath - a group or partial group path to include all jobs within that group path - optional

jobIds - a list of Job IDs to include - optional

Throws:

RundeckApiException - in case of error when calling the API (non-existent project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the project is blank (null, empty or whitespace)

IOException - if we failed to write to the file

See Also:

exportJobsToFile(String, String), exportJobs(String, String, String, String...)

exportJobs

public InputStream exportJobs(String project)
                       throws RundeckApiException,
                              RundeckApiException.RundeckApiLoginException,
                              IllegalArgumentException

Export the definitions of all jobs that belongs to the given project

Parameters:

project - name of the project - mandatory

Returns:

an InputStream instance, not linked to any network resources - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the project is blank (null, empty or whitespace)

See Also:

exportJobs(String, String, String, String...), exportJobsToFile(String, String)

exportJobs

public InputStream exportJobs(String project,
                              String jobFilter,
                              String groupPath,
                              String... jobIds)
                       throws RundeckApiException,
                              RundeckApiException.RundeckApiLoginException,
                              IllegalArgumentException

Export the definitions of the jobs that belongs to the given project, and matches the given criteria (jobFilter, groupPath and jobIds)

Parameters:

project - name of the project - mandatory

jobFilter - a filter for the job Name - optional

groupPath - a group or partial group path to include all jobs within that group path - optional

jobIds - a list of Job IDs to include - optional

Returns:

an InputStream instance, not linked to any network resources - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the project is blank (null, empty or whitespace)

See Also:

exportJobs(String), exportJobsToFile(String, String, String, String, String...)

exportJobToFile

public void exportJobToFile(String filename,
                            String jobId)
                     throws RundeckApiException,
                            RundeckApiException.RundeckApiLoginException,
                            IllegalArgumentException,
                            IOException

Export the definition of a single job (identified by the given ID), as an XML file

Parameters:

filename - path of the file where the content should be saved

jobId - identifier of the job - mandatory

Throws:

RundeckApiException - in case of error when calling the API (non-existent job with this ID)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the jobId is blank (null, empty or whitespace)

IOException - if we failed to write to the file

See Also:

exportJob(String), getJob(String)

exportJob

public InputStream exportJob(String jobId)
                      throws RundeckApiException,
                             RundeckApiException.RundeckApiLoginException,
                             IllegalArgumentException

Export the definition of a single job, identified by the given ID

Parameters:

jobId - identifier of the job - mandatory

Returns:

an InputStream instance, not linked to any network resources - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent job with this ID)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the jobId is blank (null, empty or whitespace)

See Also:

exportJobToFile(String, String), getJob(String)

findJob

public RundeckJob findJob(String project,
                          String groupPath,
                          String name)
                   throws RundeckApiException,
                          RundeckApiException.RundeckApiLoginException,
                          IllegalArgumentException

Find a job, identified by its project, group and name. Note that the groupPath is optional, as a job does not need to belong to a group (either pass null, or an empty string).

Parameters:

project - name of the project - mandatory

groupPath - group to which the job belongs (if it belongs to a group) - optional

name - of the job to find - mandatory

Returns:

a RundeckJob instance - null if not found

Throws:

RundeckApiException - in case of error when calling the API (non-existent project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the project or the name is blank (null, empty or whitespace)

See Also:

getJob(String)

getJob

public RundeckJob getJob(String jobId)
                  throws RundeckApiException,
                         RundeckApiException.RundeckApiLoginException,
                         IllegalArgumentException

Get the definition of a single job, identified by the given ID

Parameters:

jobId - identifier of the job - mandatory

Returns:

a RundeckJob instance - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent job with this ID)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the jobId is blank (null, empty or whitespace)

See Also:

findJob(String, String, String), exportJob(String)

deleteJob

public String deleteJob(String jobId)
                 throws RundeckApiException,
                        RundeckApiException.RundeckApiLoginException,
                        IllegalArgumentException

Delete a single job, identified by the given ID

Parameters:

jobId - identifier of the job - mandatory

Returns:

the success message (note that in case of error, you'll get an exception)

Throws:

RundeckApiException - in case of error when calling the API (non-existent job with this ID)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the jobId is blank (null, empty or whitespace)

triggerJob

public RundeckExecution triggerJob(String jobId)
                            throws RundeckApiException,
                                   RundeckApiException.RundeckApiLoginException,
                                   IllegalArgumentException

Trigger the execution of a RunDeck job (identified by the given ID), and return immediately (without waiting the end of the job execution)

Parameters:

jobId - identifier of the job - mandatory

Returns:

a RundeckExecution instance for the newly created (and running) execution - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent job with this ID)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the jobId is blank (null, empty or whitespace)

See Also:

triggerJob(String, Properties, Properties), runJob(String)

triggerJob

public RundeckExecution triggerJob(String jobId,
                                   Properties options)
                            throws RundeckApiException,
                                   RundeckApiException.RundeckApiLoginException,
                                   IllegalArgumentException

Trigger the execution of a RunDeck job (identified by the given ID), and return immediately (without waiting the end of the job execution)

Parameters:

jobId - identifier of the job - mandatory

options - of the job - optional. See OptionsBuilder.

Returns:

a RundeckExecution instance for the newly created (and running) execution - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent job with this ID)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the jobId is blank (null, empty or whitespace)

See Also:

triggerJob(String, Properties, Properties), runJob(String, Properties)

triggerJob

public RundeckExecution triggerJob(String jobId,
                                   Properties options,
                                   Properties nodeFilters)
                            throws RundeckApiException,
                                   RundeckApiException.RundeckApiLoginException,
                                   IllegalArgumentException

Trigger the execution of a RunDeck job (identified by the given ID), and return immediately (without waiting the end of the job execution)

Parameters:

jobId - identifier of the job - mandatory

options - of the job - optional. See OptionsBuilder.

nodeFilters - for overriding the nodes on which the job will be executed - optional. See NodeFiltersBuilder

Returns:

a RundeckExecution instance for the newly created (and running) execution - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent job with this ID)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the jobId is blank (null, empty or whitespace)

See Also:

triggerJob(String), runJob(String, Properties, Properties)

runJob

public RundeckExecution runJob(String jobId)
                        throws RundeckApiException,
                               RundeckApiException.RundeckApiLoginException,
                               IllegalArgumentException

Run a RunDeck job (identified by the given ID), and wait until its execution is finished (or aborted) to return. We will poll the RunDeck server at regular interval (every 5 seconds) to know if the execution is finished (or aborted) or is still running.

Parameters:

jobId - identifier of the job - mandatory

Returns:

a RundeckExecution instance for the (finished/aborted) execution - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent job with this ID)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the jobId is blank (null, empty or whitespace)

See Also:

triggerJob(String), runJob(String, Properties, Properties, long, TimeUnit)

runJob

public RundeckExecution runJob(String jobId,
                               Properties options)
                        throws RundeckApiException,
                               RundeckApiException.RundeckApiLoginException,
                               IllegalArgumentException

Run a RunDeck job (identified by the given ID), and wait until its execution is finished (or aborted) to return. We will poll the RunDeck server at regular interval (every 5 seconds) to know if the execution is finished (or aborted) or is still running.

Parameters:

jobId - identifier of the job - mandatory

options - of the job - optional. See OptionsBuilder.

Returns:

a RundeckExecution instance for the (finished/aborted) execution - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent job with this ID)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the jobId is blank (null, empty or whitespace)

See Also:

triggerJob(String, Properties), runJob(String, Properties, Properties, long, TimeUnit)

runJob

public RundeckExecution runJob(String jobId,
                               Properties options,
                               Properties nodeFilters)
                        throws RundeckApiException,
                               RundeckApiException.RundeckApiLoginException,
                               IllegalArgumentException

Run a RunDeck job (identified by the given ID), and wait until its execution is finished (or aborted) to return. We will poll the RunDeck server at regular interval (every 5 seconds) to know if the execution is finished (or aborted) or is still running.

Parameters:

jobId - identifier of the job - mandatory

options - of the job - optional. See OptionsBuilder.

nodeFilters - for overriding the nodes on which the job will be executed - optional. See NodeFiltersBuilder

Returns:

a RundeckExecution instance for the (finished/aborted) execution - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent job with this ID)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the jobId is blank (null, empty or whitespace)

See Also:

triggerJob(String, Properties, Properties), runJob(String, Properties, Properties, long, TimeUnit)

runJob

public RundeckExecution runJob(String jobId,
                               Properties options,
                               long poolingInterval,
                               TimeUnit poolingUnit)
                        throws RundeckApiException,
                               RundeckApiException.RundeckApiLoginException,
                               IllegalArgumentException

Run a RunDeck job (identified by the given ID), and wait until its execution is finished (or aborted) to return. We will poll the RunDeck server at regular interval (configured by the poolingInterval/poolingUnit couple) to know if the execution is finished (or aborted) or is still running.

Parameters:

jobId - identifier of the job - mandatory

options - of the job - optional. See OptionsBuilder.

poolingInterval - for checking the status of the execution. Must be > 0.

poolingUnit - unit (seconds, milli-seconds, ...) of the interval. Default to seconds.

Returns:

a RundeckExecution instance for the (finished/aborted) execution - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent job with this ID)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the jobId is blank (null, empty or whitespace)

See Also:

triggerJob(String, Properties), runJob(String, Properties, Properties, long, TimeUnit)

runJob

public RundeckExecution runJob(String jobId,
                               Properties options,
                               Properties nodeFilters,
                               long poolingInterval,
                               TimeUnit poolingUnit)
                        throws RundeckApiException,
                               RundeckApiException.RundeckApiLoginException,
                               IllegalArgumentException

Run a RunDeck job (identified by the given ID), and wait until its execution is finished (or aborted) to return. We will poll the RunDeck server at regular interval (configured by the poolingInterval/poolingUnit couple) to know if the execution is finished (or aborted) or is still running.

Parameters:

jobId - identifier of the job - mandatory

options - of the job - optional. See OptionsBuilder.

nodeFilters - for overriding the nodes on which the job will be executed - optional. See NodeFiltersBuilder

poolingInterval - for checking the status of the execution. Must be > 0.

poolingUnit - unit (seconds, milli-seconds, ...) of the interval. Default to seconds.

Returns:

a RundeckExecution instance for the (finished/aborted) execution - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent job with this ID)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the jobId is blank (null, empty or whitespace)

See Also:

triggerJob(String, Properties), runJob(String, Properties, Properties, long, TimeUnit)

triggerAdhocCommand

public RundeckExecution triggerAdhocCommand(String project,
                                            String command)
                                     throws RundeckApiException,
                                            RundeckApiException.RundeckApiLoginException,
                                            IllegalArgumentException

Trigger the execution of an ad-hoc command, and return immediately (without waiting the end of the execution). The command will not be dispatched to nodes, but be executed on the RunDeck server.

Parameters:

project - name of the project - mandatory

command - to be executed - mandatory

Returns:

a RundeckExecution instance for the newly created (and running) execution - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the project or command is blank (null, empty or whitespace)

See Also:

triggerAdhocCommand(String, String, Properties, Integer, Boolean), runAdhocCommand(String, String)

triggerAdhocCommand

public RundeckExecution triggerAdhocCommand(String project,
                                            String command,
                                            Properties nodeFilters)
                                     throws RundeckApiException,
                                            RundeckApiException.RundeckApiLoginException,
                                            IllegalArgumentException

Trigger the execution of an ad-hoc command, and return immediately (without waiting the end of the execution). The command will be dispatched to nodes, accordingly to the nodeFilters parameter.

Parameters:

project - name of the project - mandatory

command - to be executed - mandatory

nodeFilters - for selecting nodes on which the command will be executed. See NodeFiltersBuilder

Returns:

a RundeckExecution instance for the newly created (and running) execution - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the project or command is blank (null, empty or whitespace)

See Also:

triggerAdhocCommand(String, String, Properties, Integer, Boolean), runAdhocCommand(String, String, Properties)

triggerAdhocCommand

public RundeckExecution triggerAdhocCommand(String project,
                                            String command,
                                            Properties nodeFilters,
                                            Integer nodeThreadcount,
                                            Boolean nodeKeepgoing)
                                     throws RundeckApiException,
                                            RundeckApiException.RundeckApiLoginException,
                                            IllegalArgumentException

Trigger the execution of an ad-hoc command, and return immediately (without waiting the end of the execution). The command will be dispatched to nodes, accordingly to the nodeFilters parameter.

Parameters:

project - name of the project - mandatory

command - to be executed - mandatory

nodeFilters - for selecting nodes on which the command will be executed. See NodeFiltersBuilder

nodeThreadcount - thread count to use (for parallelizing when running on multiple nodes) - optional

nodeKeepgoing - if true, continue executing on other nodes even if some fail - optional

Returns:

a RundeckExecution instance for the newly created (and running) execution - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the project or command is blank (null, empty or whitespace)

See Also:

triggerAdhocCommand(String, String), runAdhocCommand(String, String, Properties)

runAdhocCommand

public RundeckExecution runAdhocCommand(String project,
                                        String command)
                                 throws RundeckApiException,
                                        RundeckApiException.RundeckApiLoginException,
                                        IllegalArgumentException

Run an ad-hoc command, and wait until its execution is finished (or aborted) to return. We will poll the RunDeck server at regular interval (every 5 seconds) to know if the execution is finished (or aborted) or is still running. The command will not be dispatched to nodes, but be executed on the RunDeck server.

Parameters:

project - name of the project - mandatory

command - to be executed - mandatory

Returns:

a RundeckExecution instance for the (finished/aborted) execution - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the project or command is blank (null, empty or whitespace)

See Also:

runAdhocCommand(String, String, Properties, Integer, Boolean, long, TimeUnit), triggerAdhocCommand(String, String)

runAdhocCommand

public RundeckExecution runAdhocCommand(String project,
                                        String command,
                                        long poolingInterval,
                                        TimeUnit poolingUnit)
                                 throws RundeckApiException,
                                        RundeckApiException.RundeckApiLoginException,
                                        IllegalArgumentException

Run an ad-hoc command, and wait until its execution is finished (or aborted) to return. We will poll the RunDeck server at regular interval (configured by the poolingInterval/poolingUnit couple) to know if the execution is finished (or aborted) or is still running. The command will not be dispatched to nodes, but be executed on the RunDeck server.

Parameters:

project - name of the project - mandatory

command - to be executed - mandatory

poolingInterval - for checking the status of the execution. Must be > 0.

poolingUnit - unit (seconds, milli-seconds, ...) of the interval. Default to seconds.

Returns:

a RundeckExecution instance for the (finished/aborted) execution - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the project or command is blank (null, empty or whitespace)

See Also:

runAdhocCommand(String, String, Properties, Integer, Boolean, long, TimeUnit), triggerAdhocCommand(String, String)

runAdhocCommand

public RundeckExecution runAdhocCommand(String project,
                                        String command,
                                        Properties nodeFilters)
                                 throws RundeckApiException,
                                        RundeckApiException.RundeckApiLoginException,
                                        IllegalArgumentException

Run an ad-hoc command, and wait until its execution is finished (or aborted) to return. We will poll the RunDeck server at regular interval (every 5 seconds) to know if the execution is finished (or aborted) or is still running. The command will be dispatched to nodes, accordingly to the nodeFilters parameter.

Parameters:

project - name of the project - mandatory

command - to be executed - mandatory

nodeFilters - for selecting nodes on which the command will be executed. See NodeFiltersBuilder

Returns:

a RundeckExecution instance for the (finished/aborted) execution - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the project or command is blank (null, empty or whitespace)

See Also:

runAdhocCommand(String, String, Properties, Integer, Boolean, long, TimeUnit), triggerAdhocCommand(String, String, Properties)

runAdhocCommand

public RundeckExecution runAdhocCommand(String project,
                                        String command,
                                        Properties nodeFilters,
                                        long poolingInterval,
                                        TimeUnit poolingUnit)
                                 throws RundeckApiException,
                                        RundeckApiException.RundeckApiLoginException,
                                        IllegalArgumentException

Run an ad-hoc command, and wait until its execution is finished (or aborted) to return. We will poll the RunDeck server at regular interval (configured by the poolingInterval/poolingUnit couple) to know if the execution is finished (or aborted) or is still running. The command will be dispatched to nodes, accordingly to the nodeFilters parameter.

Parameters:

project - name of the project - mandatory

command - to be executed - mandatory

nodeFilters - for selecting nodes on which the command will be executed. See NodeFiltersBuilder

poolingInterval - for checking the status of the execution. Must be > 0.

poolingUnit - unit (seconds, milli-seconds, ...) of the interval. Default to seconds.

Returns:

a RundeckExecution instance for the (finished/aborted) execution - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the project or command is blank (null, empty or whitespace)

See Also:

runAdhocCommand(String, String, Properties, Integer, Boolean, long, TimeUnit), triggerAdhocCommand(String, String, Properties)

runAdhocCommand

public RundeckExecution runAdhocCommand(String project,
                                        String command,
                                        Properties nodeFilters,
                                        Integer nodeThreadcount,
                                        Boolean nodeKeepgoing)
                                 throws RundeckApiException,
                                        RundeckApiException.RundeckApiLoginException,
                                        IllegalArgumentException

Run an ad-hoc command, and wait until its execution is finished (or aborted) to return. We will poll the RunDeck server at regular interval (every 5 seconds) to know if the execution is finished (or aborted) or is still running. The command will be dispatched to nodes, accordingly to the nodeFilters parameter.

Parameters:

project - name of the project - mandatory

command - to be executed - mandatory

nodeFilters - for selecting nodes on which the command will be executed. See NodeFiltersBuilder

nodeThreadcount - thread count to use (for parallelizing when running on multiple nodes) - optional

nodeKeepgoing - if true, continue executing on other nodes even if some fail - optional

Returns:

a RundeckExecution instance for the (finished/aborted) execution - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the project or command is blank (null, empty or whitespace)

See Also:

runAdhocCommand(String, String, Properties, Integer, Boolean, long, TimeUnit), triggerAdhocCommand(String, String, Properties, Integer, Boolean)

runAdhocCommand

public RundeckExecution runAdhocCommand(String project,
                                        String command,
                                        Properties nodeFilters,
                                        Integer nodeThreadcount,
                                        Boolean nodeKeepgoing,
                                        long poolingInterval,
                                        TimeUnit poolingUnit)
                                 throws RundeckApiException,
                                        RundeckApiException.RundeckApiLoginException,
                                        IllegalArgumentException

Run an ad-hoc command, and wait until its execution is finished (or aborted) to return. We will poll the RunDeck server at regular interval (configured by the poolingInterval/poolingUnit couple) to know if the execution is finished (or aborted) or is still running. The command will be dispatched to nodes, accordingly to the nodeFilters parameter.

Parameters:

project - name of the project - mandatory

command - to be executed - mandatory

nodeFilters - for selecting nodes on which the command will be executed. See NodeFiltersBuilder

nodeThreadcount - thread count to use (for parallelizing when running on multiple nodes) - optional

nodeKeepgoing - if true, continue executing on other nodes even if some fail - optional

poolingInterval - for checking the status of the execution. Must be > 0.

poolingUnit - unit (seconds, milli-seconds, ...) of the interval. Default to seconds.

Returns:

a RundeckExecution instance for the (finished/aborted) execution - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the project or command is blank (null, empty or whitespace)

See Also:

triggerAdhocCommand(String, String, Properties, Integer, Boolean)

getRunningExecutions

public List<RundeckExecution> getRunningExecutions()
                                            throws RundeckApiException,
                                                   RundeckApiException.RundeckApiLoginException

Get all running executions (for all projects)

Returns:

a List of RundeckExecution : might be empty, but won't be null

Throws:

RundeckApiException - in case of error when calling the API

RundeckApiException.RundeckApiLoginException - if the login failed

getRunningExecutions

public List<RundeckExecution> getRunningExecutions(String project)
                                            throws RundeckApiException,
                                                   RundeckApiException.RundeckApiLoginException,
                                                   IllegalArgumentException

Get the running executions for the given project

Parameters:

project - name of the project - mandatory

Returns:

a List of RundeckExecution : might be empty, but won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the project is blank (null, empty or whitespace)

getJobExecutions

public List<RundeckExecution> getJobExecutions(String jobId)
                                        throws RundeckApiException,
                                               RundeckApiException.RundeckApiLoginException,
                                               IllegalArgumentException

Get the executions of the given job

Parameters:

jobId - identifier of the job - mandatory

Returns:

a List of RundeckExecution : might be empty, but won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent job with this ID)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the jobId is blank (null, empty or whitespace)

getJobExecutions

public List<RundeckExecution> getJobExecutions(String jobId,
                                               RundeckExecution.ExecutionStatus status)
                                        throws RundeckApiException,
                                               RundeckApiException.RundeckApiLoginException,
                                               IllegalArgumentException

Get the executions of the given job

Parameters:

jobId - identifier of the job - mandatory

status - of the executions - optional (null for all)

Returns:

a List of RundeckExecution : might be empty, but won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent job with this ID)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the jobId is blank (null, empty or whitespace)

getJobExecutions

public List<RundeckExecution> getJobExecutions(String jobId,
                                               RundeckExecution.ExecutionStatus status,
                                               Long max,
                                               Long offset)
                                        throws RundeckApiException,
                                               RundeckApiException.RundeckApiLoginException,
                                               IllegalArgumentException

Get the executions of the given job

Parameters:

jobId - identifier of the job - mandatory

status - of the executions - optional (null for all)

max - number of results to return - optional (null for all)

offset - the 0-indexed offset for the first result to return - optional

Returns:

a List of RundeckExecution : might be empty, but won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent job with this ID)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the jobId is blank (null, empty or whitespace)

getExecution

public RundeckExecution getExecution(Long executionId)
                              throws RundeckApiException,
                                     RundeckApiException.RundeckApiLoginException,
                                     IllegalArgumentException

Get a single execution, identified by the given ID

Parameters:

executionId - identifier of the execution - mandatory

Returns:

a RundeckExecution instance - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent execution with this ID)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the executionId is null

abortExecution

public RundeckAbort abortExecution(Long executionId)
                            throws RundeckApiException,
                                   RundeckApiException.RundeckApiLoginException,
                                   IllegalArgumentException

Abort an execution (identified by the given ID). The execution should be running...

Parameters:

executionId - identifier of the execution - mandatory

Returns:

a RundeckAbort instance - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent execution with this ID)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the executionId is null

getNodes

public List<RundeckNode> getNodes()
                           throws RundeckApiException,
                                  RundeckApiException.RundeckApiLoginException

List all nodes (for all projects)

Returns:

a List of RundeckNode : might be empty, but won't be null

Throws:

RundeckApiException - in case of error when calling the API

RundeckApiException.RundeckApiLoginException - if the login failed

getNodes

public List<RundeckNode> getNodes(String project)
                           throws RundeckApiException,
                                  RundeckApiException.RundeckApiLoginException,
                                  IllegalArgumentException

List all nodes that belongs to the given project

Parameters:

project - name of the project - mandatory

Returns:

a List of RundeckNode : might be empty, but won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the project is blank (null, empty or whitespace)

See Also:

getNodes(String, Properties)

getNodes

public List<RundeckNode> getNodes(String project,
                                  Properties nodeFilters)
                           throws RundeckApiException,
                                  RundeckApiException.RundeckApiLoginException,
                                  IllegalArgumentException

List nodes that belongs to the given project

Parameters:

project - name of the project - mandatory

nodeFilters - for filtering the nodes - optional. See NodeFiltersBuilder

Returns:

a List of RundeckNode : might be empty, but won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the project is blank (null, empty or whitespace)

getNode

public RundeckNode getNode(String name,
                           String project)
                    throws RundeckApiException,
                           RundeckApiException.RundeckApiLoginException,
                           IllegalArgumentException

Get the definition of a single node

Parameters:

name - of the node - mandatory

project - name of the project - mandatory

Returns:

a RundeckNode instance - won't be null

Throws:

RundeckApiException - in case of error when calling the API (non-existent name or project with this name)

RundeckApiException.RundeckApiLoginException - if the login failed

IllegalArgumentException - if the name or project is blank (null, empty or whitespace)

getSystemInfo

public RundeckSystemInfo getSystemInfo()
                                throws RundeckApiException,
                                       RundeckApiException.RundeckApiLoginException

Get system informations about the RunDeck server

Returns:

a RundeckSystemInfo instance - won't be null

Throws:

RundeckApiException - in case of error when calling the API

RundeckApiException - if the login failed

RundeckApiException.RundeckApiLoginException

getUrl

public String getUrl()

getLogin

public String getLogin()

getPassword

public String getPassword()

toString

public String toString()

Overrides:

toString in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object