From bbcfd1cff736dfd289ba61d5359a3b5594a14338 Mon Sep 17 00:00:00 2001 From: Greg Schueler Date: Tue, 9 Jul 2013 10:22:57 -0700 Subject: [PATCH 1/3] Use builder based arguments for methods * Replace triggerAdhocScript/Command/Job * Add RunAdhocX interfaces * Add RunJob interface and builder --- .../java/org/rundeck/api/DefaultRunAdhoc.java | 54 ++++ .../rundeck/api/DefaultRunAdhocCommand.java | 18 ++ .../rundeck/api/DefaultRunAdhocScript.java | 28 ++ .../java/org/rundeck/api/DefaultRunJob.java | 50 +++ src/main/java/org/rundeck/api/RunAdhoc.java | 38 +++ .../java/org/rundeck/api/RunAdhocCommand.java | 14 + .../rundeck/api/RunAdhocCommandBuilder.java | 55 ++++ .../java/org/rundeck/api/RunAdhocScript.java | 22 ++ .../rundeck/api/RunAdhocScriptBuilder.java | 62 ++++ src/main/java/org/rundeck/api/RunJob.java | 32 ++ .../java/org/rundeck/api/RunJobBuilder.java | 44 +++ .../java/org/rundeck/api/RundeckClient.java | 289 ++++++++++++++++-- .../org/rundeck/api/RundeckClientTest.java | 191 +++++++++++- 13 files changed, 853 insertions(+), 44 deletions(-) create mode 100644 src/main/java/org/rundeck/api/DefaultRunAdhoc.java create mode 100644 src/main/java/org/rundeck/api/DefaultRunAdhocCommand.java create mode 100644 src/main/java/org/rundeck/api/DefaultRunAdhocScript.java create mode 100644 src/main/java/org/rundeck/api/DefaultRunJob.java create mode 100644 src/main/java/org/rundeck/api/RunAdhoc.java create mode 100644 src/main/java/org/rundeck/api/RunAdhocCommand.java create mode 100644 src/main/java/org/rundeck/api/RunAdhocCommandBuilder.java create mode 100644 src/main/java/org/rundeck/api/RunAdhocScript.java create mode 100644 src/main/java/org/rundeck/api/RunAdhocScriptBuilder.java create mode 100644 src/main/java/org/rundeck/api/RunJob.java create mode 100644 src/main/java/org/rundeck/api/RunJobBuilder.java diff --git a/src/main/java/org/rundeck/api/DefaultRunAdhoc.java b/src/main/java/org/rundeck/api/DefaultRunAdhoc.java new file mode 100644 index 0000000..8e1897a --- /dev/null +++ b/src/main/java/org/rundeck/api/DefaultRunAdhoc.java @@ -0,0 +1,54 @@ +package org.rundeck.api; + +import java.util.Properties; + +/** + * Base class for adhoc requests + */ +class DefaultRunAdhoc implements RunAdhoc{ + private String project; + private Properties nodeFilters; + private Integer nodeThreadcount; + private Boolean nodeKeepgoing; + private String asUser; + + public String getProject() { + return project; + } + + public void setProject(String project) { + this.project = project; + } + + public Properties getNodeFilters() { + return nodeFilters; + } + + public void setNodeFilters(Properties nodeFilters) { + this.nodeFilters = nodeFilters; + } + + public Integer getNodeThreadcount() { + return nodeThreadcount; + } + + public void setNodeThreadcount(Integer nodeThreadcount) { + this.nodeThreadcount = nodeThreadcount; + } + + public Boolean getNodeKeepgoing() { + return nodeKeepgoing; + } + + public void setNodeKeepgoing(Boolean nodeKeepgoing) { + this.nodeKeepgoing = nodeKeepgoing; + } + + public String getAsUser() { + return asUser; + } + + public void setAsUser(String asUser) { + this.asUser = asUser; + } +} diff --git a/src/main/java/org/rundeck/api/DefaultRunAdhocCommand.java b/src/main/java/org/rundeck/api/DefaultRunAdhocCommand.java new file mode 100644 index 0000000..33ae58a --- /dev/null +++ b/src/main/java/org/rundeck/api/DefaultRunAdhocCommand.java @@ -0,0 +1,18 @@ +package org.rundeck.api; + +/** + * Implementation of {@link RunAdhocCommand} + */ +class DefaultRunAdhocCommand extends DefaultRunAdhoc implements RunAdhocCommand { + private String command; + + @Override + public String getCommand() { + return command; + } + + public void setCommand(String command) { + this.command = command; + } + +} diff --git a/src/main/java/org/rundeck/api/DefaultRunAdhocScript.java b/src/main/java/org/rundeck/api/DefaultRunAdhocScript.java new file mode 100644 index 0000000..bd6c0e6 --- /dev/null +++ b/src/main/java/org/rundeck/api/DefaultRunAdhocScript.java @@ -0,0 +1,28 @@ +package org.rundeck.api; + +import java.io.InputStream; + +/** + * Bean implementing {@link RunAdhocScript} + */ +class DefaultRunAdhocScript extends DefaultRunAdhoc implements RunAdhocScript { + private InputStream script; + private String argString; + + @Override + public InputStream getScript() { + return script; + } + + public void setScript(InputStream script) { + this.script = script; + } + + public String getArgString() { + return argString; + } + + public void setArgString(String argString) { + this.argString = argString; + } +} diff --git a/src/main/java/org/rundeck/api/DefaultRunJob.java b/src/main/java/org/rundeck/api/DefaultRunJob.java new file mode 100644 index 0000000..fb3ca49 --- /dev/null +++ b/src/main/java/org/rundeck/api/DefaultRunJob.java @@ -0,0 +1,50 @@ +package org.rundeck.api; + +import java.util.Properties; + +/** + * impl of {@link RunJob} + */ +class DefaultRunJob implements RunJob { + private String jobId; + private Properties options; + private Properties nodeFilters; + private String asUser; + + + @Override + public String getJobId() { + return jobId; + } + + @Override + public Properties getOptions() { + return options; + } + + @Override + public Properties getNodeFilters() { + return nodeFilters; + } + + @Override + public String getAsUser() { + return asUser; + } + + public void setJobId(String jobId) { + this.jobId = jobId; + } + + public void setOptions(Properties options) { + this.options = options; + } + + public void setNodeFilters(Properties nodeFilters) { + this.nodeFilters = nodeFilters; + } + + public void setAsUser(String asUser) { + this.asUser = asUser; + } +} diff --git a/src/main/java/org/rundeck/api/RunAdhoc.java b/src/main/java/org/rundeck/api/RunAdhoc.java new file mode 100644 index 0000000..7fe2ddf --- /dev/null +++ b/src/main/java/org/rundeck/api/RunAdhoc.java @@ -0,0 +1,38 @@ +package org.rundeck.api; + +import java.util.Properties; + +/** + * Super interface for adhoc executions + */ +public interface RunAdhoc { + /** + * Project name + * @return + */ + String getProject(); + + /** + * Node filters + * @return + */ + Properties getNodeFilters(); + + /** + * Threadcount + * @return + */ + Integer getNodeThreadcount(); + + /** + * Keepgoing + * @return + */ + Boolean getNodeKeepgoing(); + + /** + * As User + * @return + */ + String getAsUser(); +} diff --git a/src/main/java/org/rundeck/api/RunAdhocCommand.java b/src/main/java/org/rundeck/api/RunAdhocCommand.java new file mode 100644 index 0000000..83c77d1 --- /dev/null +++ b/src/main/java/org/rundeck/api/RunAdhocCommand.java @@ -0,0 +1,14 @@ +package org.rundeck.api; + +/** + * A command to execute + */ +public interface RunAdhocCommand extends RunAdhoc { + + /** + * Command to execute + * @return + */ + String getCommand(); + +} diff --git a/src/main/java/org/rundeck/api/RunAdhocCommandBuilder.java b/src/main/java/org/rundeck/api/RunAdhocCommandBuilder.java new file mode 100644 index 0000000..745b345 --- /dev/null +++ b/src/main/java/org/rundeck/api/RunAdhocCommandBuilder.java @@ -0,0 +1,55 @@ +package org.rundeck.api; + +import java.util.Properties; + +/** + * $INTERFACE is ... User: greg Date: 7/9/13 Time: 10:38 AM + */ +public class RunAdhocCommandBuilder { + private DefaultRunAdhocCommand command; + + public RunAdhocCommandBuilder() { + command = new DefaultRunAdhocCommand(); + } + + public static RunAdhocCommandBuilder builder() { + return new RunAdhocCommandBuilder(); + } + + public RunAdhocCommandBuilder setProject(String project) { + command.setProject(project); + + return this; + } + + public RunAdhocCommandBuilder setCommand(String commandString) { + command.setCommand(commandString); + return this; + } + + public RunAdhocCommandBuilder setNodeFilters(Properties nodeFilters) { + command.setNodeFilters(nodeFilters); + return this; + } + + public RunAdhocCommandBuilder setNodeThreadcount(Integer nodeThreadcount) { + command.setNodeThreadcount(nodeThreadcount); + return this; + } + + public RunAdhocCommandBuilder setNodeKeepgoing(Boolean nodeKeepgoing) { + command.setNodeKeepgoing(nodeKeepgoing); + return this; + } + + public RunAdhocCommandBuilder setAsUser(String asUser) { + command.setAsUser(asUser); + return this; + } + + public RunAdhocCommand create() { + DefaultRunAdhocCommand built = command; + command = new DefaultRunAdhocCommand(); + return built; + } +} diff --git a/src/main/java/org/rundeck/api/RunAdhocScript.java b/src/main/java/org/rundeck/api/RunAdhocScript.java new file mode 100644 index 0000000..98c8d66 --- /dev/null +++ b/src/main/java/org/rundeck/api/RunAdhocScript.java @@ -0,0 +1,22 @@ +package org.rundeck.api; + +import java.io.InputStream; + +/** + * An adhoc script to be executed by Rundeck + */ +public interface RunAdhocScript extends RunAdhoc { + + /** + * Stream containing script + * @return + */ + InputStream getScript(); + + /** + * Arguments to the script + * @return + */ + String getArgString(); + +} diff --git a/src/main/java/org/rundeck/api/RunAdhocScriptBuilder.java b/src/main/java/org/rundeck/api/RunAdhocScriptBuilder.java new file mode 100644 index 0000000..39ba5fc --- /dev/null +++ b/src/main/java/org/rundeck/api/RunAdhocScriptBuilder.java @@ -0,0 +1,62 @@ +package org.rundeck.api; + +import java.io.InputStream; +import java.util.Properties; + +/** + * A builder to create a {@link RunAdhocScript}, use the {@link #builder()} to create a builder, then {@link #create()} to + * build an RunAdhocScript + */ +public class RunAdhocScriptBuilder { + private DefaultRunAdhocScript script; + + public RunAdhocScriptBuilder() { + script = new DefaultRunAdhocScript(); + } + + public static RunAdhocScriptBuilder builder() { + return new RunAdhocScriptBuilder(); + } + + public RunAdhocScriptBuilder setProject(String project) { + script.setProject(project); + + return this; + } + + public RunAdhocScriptBuilder setScript(InputStream stream) { + script.setScript(stream); + return this; + } + + public RunAdhocScriptBuilder setArgString(String argString) { + script.setArgString(argString); + return this; + } + + public RunAdhocScriptBuilder setNodeFilters(Properties nodeFilters) { + script.setNodeFilters(nodeFilters); + return this; + } + + public RunAdhocScriptBuilder setNodeThreadcount(Integer nodeThreadcount) { + script.setNodeThreadcount(nodeThreadcount); + return this; + } + + public RunAdhocScriptBuilder setNodeKeepgoing(Boolean nodeKeepgoing) { + script.setNodeKeepgoing(nodeKeepgoing); + return this; + } + + public RunAdhocScriptBuilder setAsUser(String asUser) { + script.setAsUser(asUser); + return this; + } + + public RunAdhocScript create() { + DefaultRunAdhocScript built = script; + script = new DefaultRunAdhocScript(); + return built; + } +} diff --git a/src/main/java/org/rundeck/api/RunJob.java b/src/main/java/org/rundeck/api/RunJob.java new file mode 100644 index 0000000..3bc7c85 --- /dev/null +++ b/src/main/java/org/rundeck/api/RunJob.java @@ -0,0 +1,32 @@ +package org.rundeck.api; + +import java.util.Properties; + +/** + * Job run request + */ +public interface RunJob { + /** + * Job ID + * @return + */ + String getJobId(); + + /** + * Options to job + * @return + */ + Properties getOptions(); + + /** + * Node filters + * @return + */ + Properties getNodeFilters(); + + /** + * as User + * @return + */ + String getAsUser(); +} diff --git a/src/main/java/org/rundeck/api/RunJobBuilder.java b/src/main/java/org/rundeck/api/RunJobBuilder.java new file mode 100644 index 0000000..83d9e87 --- /dev/null +++ b/src/main/java/org/rundeck/api/RunJobBuilder.java @@ -0,0 +1,44 @@ +package org.rundeck.api; + +import java.util.Properties; + +/** + * Job run request builder + */ +public class RunJobBuilder { + private DefaultRunJob jobRun; + + public static RunJobBuilder builder() { + return new RunJobBuilder(); + } + + public RunJobBuilder() { + jobRun = new DefaultRunJob(); + } + + public RunJobBuilder setJobId(String jobId) { + jobRun.setJobId(jobId); + return this; + } + + public RunJobBuilder setOptions(Properties options) { + jobRun.setOptions(options); + return this; + } + + public RunJobBuilder setNodeFilters(Properties nodeFilters) { + jobRun.setNodeFilters(nodeFilters); + return this; + } + + public RunJobBuilder setAsUser(String asUser) { + jobRun.setAsUser(asUser); + return this; + } + + public RunJob create() { + RunJob built = jobRun; + jobRun = new DefaultRunJob(); + return built; + } +} diff --git a/src/main/java/org/rundeck/api/RundeckClient.java b/src/main/java/org/rundeck/api/RundeckClient.java index 6a64a26..1ae3bb1 100644 --- a/src/main/java/org/rundeck/api/RundeckClient.java +++ b/src/main/java/org/rundeck/api/RundeckClient.java @@ -40,7 +40,11 @@ import java.util.Properties; import java.util.concurrent.TimeUnit; /** - * Main entry point to talk to a RunDeck instance.
+ * Main entry point to talk to a RunDeck instance. + *
+ * Deprecation Warning: The "triggerAdhocScript" methods which take multiple arguments are deprecated in + * favor of {@link #triggerAdhocScript(RunAdhocScript)}. The methods will be removed in version 10 of this library. + *
* You have 2 methods for authentication : login-based or token-based. If you want to use the first, you need to provide * both a "login" and a "password". Otherwise, just provide a "token" (also called "auth-token"). See the RunDeck * documentation for generating such a token.
@@ -176,7 +180,7 @@ public class RundeckClient implements Serializable { * @param sessionID to use for session authentication on the RunDeck instance * @param useToken should be true if using token, false if using sessionID * @throws IllegalArgumentException if the url or token is blank (null, empty or whitespace) - * @deprecated Use the builder {@link RundeckClientBuilder} + * @deprecated Use the builder {@link RundeckClientBuilder}, this method will not be public in version 10 of this library. */ public RundeckClient(String url, String token, String sessionID, boolean useToken) throws IllegalArgumentException { this(url); @@ -872,6 +876,7 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the jobId is blank (null, empty or whitespace) * @see #triggerJob(String, Properties, Properties) * @see #runJob(String) + * @deprecated use {@link #triggerJob(RunJob)}, this method will be removed in version 10 of this library */ public RundeckExecution triggerJob(String jobId) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { @@ -891,6 +896,7 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the jobId is blank (null, empty or whitespace) * @see #triggerJob(String, Properties, Properties) * @see #runJob(String, Properties) + * @deprecated use {@link #triggerJob(RunJob)}, this method will be removed in version 10 of this library */ public RundeckExecution triggerJob(String jobId, Properties options) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { @@ -912,6 +918,7 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the jobId is blank (null, empty or whitespace) * @see #triggerJob(String) * @see #runJob(String, Properties, Properties) + * @deprecated use {@link #triggerJob(RunJob)}, this method will be removed in version 10 of this library */ public RundeckExecution triggerJob(String jobId, Properties options, Properties nodeFilters) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { @@ -933,15 +940,42 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the jobId is blank (null, empty or whitespace) * @see #triggerJob(String) * @see #runJob(String, Properties, Properties) + * @deprecated use {@link #triggerJob(RunJob)}, this method will be removed in version 10 of this library */ public RundeckExecution triggerJob(String jobId, Properties options, Properties nodeFilters, String asUser) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { - AssertUtil.notBlank(jobId, "jobId is mandatory to trigger a job !"); - ApiPathBuilder apiPath = new ApiPathBuilder("/job/", jobId, "/run").param("argString", - ParametersUtil.generateArgString(options)) - .nodeFilters(nodeFilters); - if(null!=asUser) { - apiPath.param("asUser", asUser); + return triggerJob(RunJobBuilder.builder() + .setJobId(jobId) + .setOptions(options) + .setNodeFilters(nodeFilters) + .setAsUser(asUser) + .create()); + } + /** + * Trigger the execution of a RunDeck job (identified by the given ID), and return immediately (without waiting the + * end of the job execution) + * + * @param jobId identifier of the job - mandatory + * @param options of the job - optional. See {@link OptionsBuilder}. + * @param nodeFilters for overriding the nodes on which the job will be executed - optional. See + * {@link NodeFiltersBuilder} + * @param asUser specify a user name to run the job as, must have 'runAs' permission + * @return a {@link 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) + * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) + * @throws RundeckApiTokenException if the token is invalid (in case of token-based authentication) + * @throws IllegalArgumentException if the jobId is blank (null, empty or whitespace) + * @see #triggerJob(String) + * @see #runJob(String, Properties, Properties) + */ + public RundeckExecution triggerJob(RunJob jobRun) + throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { + AssertUtil.notBlank(jobRun.getJobId(), "jobId is mandatory to trigger a job !"); + ApiPathBuilder apiPath = new ApiPathBuilder("/job/", jobRun.getJobId(), "/run").param("argString", + ParametersUtil.generateArgString(jobRun.getOptions())) + .nodeFilters(jobRun.getNodeFilters()); + if(null!=jobRun.getAsUser()) { + apiPath.param("asUser", jobRun.getAsUser()); } return new ApiCall(this).get(apiPath, new ExecutionParser("result/executions/execution")); } @@ -959,6 +993,8 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the jobId is blank (null, empty or whitespace) * @see #triggerJob(String) * @see #runJob(String, Properties, Properties, long, TimeUnit) + * @deprecated use {@link #runJob(RunJob, long, java.util.concurrent.TimeUnit)}, + * this method will be removed in version 10 of this library */ public RundeckExecution runJob(String jobId) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { @@ -979,6 +1015,8 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the jobId is blank (null, empty or whitespace) * @see #triggerJob(String, Properties) * @see #runJob(String, Properties, Properties, long, TimeUnit) + * @deprecated use {@link #runJob(RunJob, long, java.util.concurrent.TimeUnit)}, + * this method will be removed in version 10 of this library */ public RundeckExecution runJob(String jobId, Properties options) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { @@ -1001,12 +1039,34 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the jobId is blank (null, empty or whitespace) * @see #triggerJob(String, Properties, Properties) * @see #runJob(String, Properties, Properties, long, TimeUnit) + * @deprecated use {@link #runJob(RunJob, long, java.util.concurrent.TimeUnit)}, + * this method will be removed in version 10 of this library */ public RundeckExecution runJob(String jobId, Properties options, Properties nodeFilters) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { return runJob(jobId, options, nodeFilters, DEFAULT_POOLING_INTERVAL, DEFAULT_POOLING_UNIT); } + /** + * 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. + * + * @param runJob the job run parameters + * + * @return a {@link 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) + * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) + * @throws RundeckApiTokenException if the token is invalid (in case of token-based authentication) + * @throws IllegalArgumentException if the jobId is blank (null, empty or whitespace) + * @see #triggerJob(RunJob) + * @see #runJob(RunJob, long, TimeUnit) + */ + public RundeckExecution runJob(final RunJob runJob) throws RundeckApiException, RundeckApiLoginException, + RundeckApiTokenException, IllegalArgumentException { + return runJob(runJob, DEFAULT_POOLING_INTERVAL, DEFAULT_POOLING_UNIT); + } /** * 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 @@ -1023,6 +1083,8 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the jobId is blank (null, empty or whitespace) * @see #triggerJob(String, Properties) * @see #runJob(String, Properties, Properties, long, TimeUnit) + * @deprecated use {@link #runJob(RunJob, long, java.util.concurrent.TimeUnit)}, + * this method will be removed in version 10 of this library */ public RundeckExecution runJob(String jobId, Properties options, long poolingInterval, TimeUnit poolingUnit) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { @@ -1047,6 +1109,8 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the jobId is blank (null, empty or whitespace) * @see #triggerJob(String, Properties) * @see #runJob(String, Properties, Properties, long, TimeUnit) + * @deprecated use {@link #runJob(RunJob, long, java.util.concurrent.TimeUnit)}, + * this method will be removed in version 10 of this library */ public RundeckExecution runJob(String jobId, Properties options, Properties nodeFilters, long poolingInterval, TimeUnit poolingUnit) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, @@ -1072,10 +1136,44 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the jobId is blank (null, empty or whitespace) * @see #triggerJob(String, Properties) * @see #runJob(String, Properties, Properties, long, TimeUnit) + * @deprecated use {@link #runJob(RunJob, long, java.util.concurrent.TimeUnit)}, this method will be removed in version 10 of this library */ public RundeckExecution runJob(String jobId, Properties options, Properties nodeFilters, String asUser, long poolingInterval, TimeUnit poolingUnit) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { + return runJob(RunJobBuilder.builder() + .setJobId(jobId) + .setOptions(options) + .setNodeFilters(nodeFilters) + .setAsUser(asUser) + .create(), poolingInterval, poolingUnit); + } + + /** + * 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. + * + * @param jobId identifier of the job - mandatory + * @param options of the job - optional. See {@link OptionsBuilder}. + * @param nodeFilters for overriding the nodes on which the job will be executed - optional. See {@link + * NodeFiltersBuilder} + * @param asUser specify a user name to run the job as, must have 'runAs' permission + * @param poolingInterval for checking the status of the execution. Must be > 0. + * @param poolingUnit unit (seconds, milli-seconds, ...) of the interval. Default to seconds. + * + * @return a {@link 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) + * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) + * @throws RundeckApiTokenException if the token is invalid (in case of token-based authentication) + * @throws IllegalArgumentException if the jobId is blank (null, empty or whitespace) + * @see #triggerJob(RunJob) + */ + public RundeckExecution runJob(final RunJob jobRun, long poolingInterval, + TimeUnit poolingUnit) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, + IllegalArgumentException { + if (poolingInterval <= 0) { poolingInterval = DEFAULT_POOLING_INTERVAL; poolingUnit = DEFAULT_POOLING_UNIT; @@ -1084,7 +1182,7 @@ public class RundeckClient implements Serializable { poolingUnit = DEFAULT_POOLING_UNIT; } - RundeckExecution execution = triggerJob(jobId, options, nodeFilters, asUser); + RundeckExecution execution = triggerJob(jobRun); while (ExecutionStatus.RUNNING.equals(execution.getStatus())) { try { Thread.sleep(poolingUnit.toMillis(poolingInterval)); @@ -1113,6 +1211,7 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the project or command is blank (null, empty or whitespace) * @see #triggerAdhocCommand(String, String, Properties, Integer, Boolean) * @see #runAdhocCommand(String, String) + * @deprecated use {@link #triggerAdhocCommand(RunAdhocCommand)}, will be removed in version 10 of this library */ public RundeckExecution triggerAdhocCommand(String project, String command) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { @@ -1133,6 +1232,7 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the project or command is blank (null, empty or whitespace) * @see #triggerAdhocCommand(String, String, Properties, Integer, Boolean) * @see #runAdhocCommand(String, String, Properties) + * @deprecated use {@link #triggerAdhocCommand(RunAdhocCommand)}, will be removed in version 10 of this library */ public RundeckExecution triggerAdhocCommand(String project, String command, Properties nodeFilters) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { @@ -1155,6 +1255,7 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the project or command is blank (null, empty or whitespace) * @see #triggerAdhocCommand(String, String) * @see #runAdhocCommand(String, String, Properties) + * @deprecated use {@link #triggerAdhocCommand(RunAdhocCommand)}, will be removed in version 10 of this library */ public RundeckExecution triggerAdhocCommand(String project, String command, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing) throws RundeckApiException, RundeckApiLoginException, @@ -1178,21 +1279,51 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the project or command is blank (null, empty or whitespace) * @see #triggerAdhocCommand(String, String) * @see #runAdhocCommand(String, String, Properties) + * @deprecated use {@link #triggerAdhocCommand(RunAdhocCommand)}, will be removed in version 10 of this library */ public RundeckExecution triggerAdhocCommand(String project, String command, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing, String asUser) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { - AssertUtil.notBlank(project, "project is mandatory to trigger an ad-hoc command !"); - AssertUtil.notBlank(command, "command is mandatory to trigger an ad-hoc command !"); - ApiPathBuilder apiPath = new ApiPathBuilder("/run/command").param("project", project) - .param("exec", command) + return triggerAdhocCommand(RunAdhocCommandBuilder.builder() + .setProject(project) + .setCommand(command) + .setNodeFilters(nodeFilters) + .setNodeThreadcount(nodeThreadcount) + .setNodeKeepgoing(nodeKeepgoing) + .setAsUser(asUser) + .create()); + } + /** + * 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. + * + * @param project name of the project - mandatory + * @param command to be executed - mandatory + * @param nodeFilters for selecting nodes on which the command will be executed. See {@link NodeFiltersBuilder} + * @param nodeThreadcount thread count to use (for parallelizing when running on multiple nodes) - optional + * @param nodeKeepgoing if true, continue executing on other nodes even if some fail - optional + * @param asUser specify a user name to run the job as, must have 'runAs' permission + * @return a {@link 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) + * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) + * @throws RundeckApiTokenException if the token is invalid (in case of token-based authentication) + * @throws IllegalArgumentException if the project or command is blank (null, empty or whitespace) + * @see #triggerAdhocCommand(String, String) + * @see #runAdhocCommand(String, String, Properties) + */ + public RundeckExecution triggerAdhocCommand(RunAdhocCommand command) throws RundeckApiException, RundeckApiLoginException, + RundeckApiTokenException, IllegalArgumentException { + AssertUtil.notBlank(command.getProject(), "project is mandatory to trigger an ad-hoc command !"); + AssertUtil.notBlank(command.getCommand(), "command is mandatory to trigger an ad-hoc command !"); + ApiPathBuilder apiPath = new ApiPathBuilder("/run/command").param("project", command.getProject()) + .param("exec", command.getCommand()) .param("nodeThreadcount", - nodeThreadcount) + command.getNodeThreadcount()) .param("nodeKeepgoing", - nodeKeepgoing) - .nodeFilters(nodeFilters); - if(null!=asUser) { - apiPath.param("asUser", asUser); + command.getNodeKeepgoing()) + .nodeFilters(command.getNodeFilters()); + if(null!= command.getAsUser()) { + apiPath.param("asUser", command.getAsUser()); } RundeckExecution execution = new ApiCall(this).get(apiPath, new ExecutionParser("result/execution")); // the first call just returns the ID of the execution, so we need another call to get a "real" execution @@ -1404,6 +1535,7 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #triggerAdhocScript(String, String, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, String) + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} */ public RundeckExecution triggerAdhocScript(String project, String scriptFilename) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException, IOException { @@ -1425,6 +1557,7 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #triggerAdhocScript(String, String, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, String, Properties) + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} */ public RundeckExecution triggerAdhocScript(String project, String scriptFilename, Properties options) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException, @@ -1448,6 +1581,7 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #triggerAdhocScript(String, String, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, String, Properties, Properties) + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} */ public RundeckExecution triggerAdhocScript(String project, String scriptFilename, Properties options, Properties nodeFilters) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, @@ -1473,6 +1607,7 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #triggerAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, String, Properties, Properties, Integer, Boolean, long, TimeUnit) + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} */ public RundeckExecution triggerAdhocScript(String project, String scriptFilename, Properties options, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing) throws RundeckApiException, @@ -1497,15 +1632,50 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #triggerAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, String, Properties, Properties, Integer, Boolean, long, TimeUnit) + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} */ public RundeckExecution triggerAdhocScript(String project, String scriptFilename, Properties options, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing,String asUser) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException, IOException { + return triggerAdhocScript(project, scriptFilename, ParametersUtil.generateArgString(options), nodeFilters, + nodeThreadcount, nodeKeepgoing, asUser); + } + /** + * Trigger the execution of an ad-hoc script, and return immediately (without waiting the end of the execution). The + * script will be dispatched to nodes, accordingly to the nodeFilters parameter. + * + * @param project name of the project - mandatory + * @param scriptFilename filename of the script to be executed - mandatory + * @param options of the script - optional. See {@link OptionsBuilder}. + * @param nodeFilters for selecting nodes on which the command will be executed. See {@link NodeFiltersBuilder} + * @param nodeThreadcount thread count to use (for parallelizing when running on multiple nodes) - optional + * @param nodeKeepgoing if true, continue executing on other nodes even if some fail - optional + * @return a {@link 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) + * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) + * @throws RundeckApiTokenException if the token is invalid (in case of token-based authentication) + * @throws IllegalArgumentException if the project or scriptFilename is blank (null, empty or whitespace) + * @throws IOException if we failed to read the file + * @see #triggerAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean) + * @see #runAdhocScript(String, String, Properties, Properties, Integer, Boolean, long, TimeUnit) + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} + */ + public RundeckExecution triggerAdhocScript(String project, String scriptFilename, String argString, + Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing,String asUser) throws RundeckApiException, + RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException, IOException { AssertUtil.notBlank(scriptFilename, "scriptFilename is mandatory to trigger an ad-hoc script !"); FileInputStream stream = null; try { stream = FileUtils.openInputStream(new File(scriptFilename)); - return triggerAdhocScript(project, stream, options, nodeFilters, nodeThreadcount, nodeKeepgoing, asUser); + return triggerAdhocScript(RunAdhocScriptBuilder.builder() + .setProject(project) + .setScript(stream) + .setNodeFilters(nodeFilters) + .setArgString(argString) + .setNodeThreadcount(nodeThreadcount) + .setNodeKeepgoing(nodeKeepgoing) + .setAsUser(asUser) + .create()); } finally { IOUtils.closeQuietly(stream); } @@ -1524,6 +1694,7 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the project is blank (null, empty or whitespace) or the script is null * @see #triggerAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, InputStream) + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} */ public RundeckExecution triggerAdhocScript(String project, InputStream script) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { @@ -1544,6 +1715,7 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the project is blank (null, empty or whitespace) or the script is null * @see #triggerAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, InputStream, Properties) + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} */ public RundeckExecution triggerAdhocScript(String project, InputStream script, Properties options) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { @@ -1565,6 +1737,7 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the project is blank (null, empty or whitespace) or the script is null * @see #triggerAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, InputStream, Properties, Properties) + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} */ public RundeckExecution triggerAdhocScript(String project, InputStream script, Properties options, Properties nodeFilters) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, @@ -1589,6 +1762,7 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the project is blank (null, empty or whitespace) or the script is null * @see #triggerAdhocScript(String, String, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean, long, TimeUnit) + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} */ public RundeckExecution triggerAdhocScript(String project, InputStream script, Properties options, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing) throws RundeckApiException, @@ -1612,24 +1786,79 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the project is blank (null, empty or whitespace) or the script is null * @see #triggerAdhocScript(String, String, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean, long, TimeUnit) + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} */ public RundeckExecution triggerAdhocScript(String project, InputStream script, Properties options, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing, String asUser) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { - AssertUtil.notBlank(project, "project is mandatory to trigger an ad-hoc script !"); - AssertUtil.notNull(script, "script is mandatory to trigger an ad-hoc script !"); - ApiPathBuilder apiPath = new ApiPathBuilder("/run/script").param("project", project) + return triggerAdhocScript(project, script, ParametersUtil.generateArgString(options), nodeFilters, + nodeThreadcount, nodeKeepgoing, asUser); + } + /** + * Trigger the execution of an ad-hoc script, and return immediately (without waiting the end of the execution). The + * script will be dispatched to nodes, accordingly to the nodeFilters parameter. + * + * @param project name of the project - mandatory + * @param script inputStream for reading the script to be executed - mandatory + * @param options of the script - optional. See {@link OptionsBuilder}. + * @param nodeFilters for selecting nodes on which the command will be executed. See {@link NodeFiltersBuilder} + * @param nodeThreadcount thread count to use (for parallelizing when running on multiple nodes) - optional + * @param nodeKeepgoing if true, continue executing on other nodes even if some fail - optional + * @return a {@link 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) + * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) + * @throws RundeckApiTokenException if the token is invalid (in case of token-based authentication) + * @throws IllegalArgumentException if the project is blank (null, empty or whitespace) or the script is null + * @see #triggerAdhocScript(String, String, Properties, Properties, Integer, Boolean) + * @see #runAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean, long, TimeUnit) + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} + */ + public RundeckExecution triggerAdhocScript(String project, InputStream script, String argString, + Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing, String asUser) throws RundeckApiException, + RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { + return triggerAdhocScript(RunAdhocScriptBuilder.builder() + .setProject(project) + .setScript(script) + .setNodeFilters(nodeFilters) + .setArgString(argString) + .setNodeThreadcount(nodeThreadcount) + .setNodeKeepgoing(nodeKeepgoing) + .setAsUser(asUser) + .create()); + } + /** + * Trigger the execution of an ad-hoc script, and return immediately (without waiting the end of the execution). The + * script will be dispatched to nodes, accordingly to the nodeFilters parameter. + * + * @param project name of the project - mandatory + * @param script inputStream for reading the script to be executed - mandatory + * @param options of the script - optional. See {@link OptionsBuilder}. + * @param nodeFilters for selecting nodes on which the command will be executed. See {@link NodeFiltersBuilder} + * @param nodeThreadcount thread count to use (for parallelizing when running on multiple nodes) - optional + * @param nodeKeepgoing if true, continue executing on other nodes even if some fail - optional + * @return a {@link 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) + * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) + * @throws RundeckApiTokenException if the token is invalid (in case of token-based authentication) + * @throws IllegalArgumentException if the project is blank (null, empty or whitespace) or the script is null + * @see #triggerAdhocScript(String, String, Properties, Properties, Integer, Boolean) + * @see #runAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean, long, TimeUnit) + */ + public RundeckExecution triggerAdhocScript(RunAdhocScript adhocScript) throws RundeckApiException, + RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { + AssertUtil.notBlank(adhocScript.getProject(), "project is mandatory to trigger an ad-hoc script !"); + AssertUtil.notNull(adhocScript.getScript(), "script is mandatory to trigger an ad-hoc script !"); + ApiPathBuilder apiPath = new ApiPathBuilder("/run/script").param("project", adhocScript.getProject()) .attach("scriptFile", - script) - .param("argString", - ParametersUtil.generateArgString(options)) + adhocScript.getScript()) + .param("argString",adhocScript.getArgString()) .param("nodeThreadcount", - nodeThreadcount) + adhocScript.getNodeThreadcount()) .param("nodeKeepgoing", - nodeKeepgoing) - .nodeFilters(nodeFilters); - if(null!=asUser) { - apiPath.param("asUser", asUser); + adhocScript.getNodeKeepgoing()) + .nodeFilters(adhocScript.getNodeFilters()); + if(null!=adhocScript.getAsUser()) { + apiPath.param("asUser", adhocScript.getAsUser()); } RundeckExecution execution = new ApiCall(this).post(apiPath, new ExecutionParser("result/execution")); // the first call just returns the ID of the execution, so we need another call to get a "real" execution diff --git a/src/test/java/org/rundeck/api/RundeckClientTest.java b/src/test/java/org/rundeck/api/RundeckClientTest.java index f5de6ae..5a35dab 100644 --- a/src/test/java/org/rundeck/api/RundeckClientTest.java +++ b/src/test/java/org/rundeck/api/RundeckClientTest.java @@ -28,10 +28,7 @@ import org.rundeck.api.query.ExecutionQuery; import org.rundeck.api.util.PagedResults; import java.io.ByteArrayInputStream; -import java.util.ArrayList; -import java.util.Arrays; -import java.util.Date; -import java.util.List; +import java.util.*; /** @@ -347,13 +344,13 @@ public class RundeckClientTest { final RundeckJobDelete delete = deleteTest.getResults().get(0); Assert.assertFalse(delete.isSuccessful()); Assert.assertNotNull(delete.getError()); - Assert.assertEquals("unauthorized",delete.getErrorCode()); + Assert.assertEquals("unauthorized", delete.getErrorCode()); Assert.assertNull(delete.getMessage()); Assert.assertEquals("3a6d16be-4268-4d26-86a9-cebc1781f768", delete.getId()); } @Test @Betamax(tape = "trigger_job_basic") - public void triggerJobBasic() throws Exception { + public void triggerJobDeprecatedBasic() throws Exception { RundeckClient client = createClient(TEST_TOKEN_3); final RundeckExecution test @@ -366,6 +363,38 @@ public class RundeckClientTest { Assert.assertEquals("admin", test.getStartedBy()); Assert.assertEquals(RundeckExecution.ExecutionStatus.RUNNING, test.getStatus()); + } + @Test + @Betamax(tape = "trigger_job_basic") + public void triggerJobBasic() throws Exception { + RundeckClient client = createClient(TEST_TOKEN_3); + + final RundeckExecution test + = client.triggerJob(RunJobBuilder.builder().setJobId("3170ba0e-6093-4b58-94d2-52988aefbfc9").create()); + + Assert.assertEquals((Long) 19L, test.getId()); + Assert.assertEquals(null, test.getArgstring()); + Assert.assertEquals(null, test.getAbortedBy()); + Assert.assertEquals("echo hi there ${job.username} ; sleep 90", test.getDescription()); + Assert.assertEquals("admin", test.getStartedBy()); + Assert.assertEquals(RundeckExecution.ExecutionStatus.RUNNING, test.getStatus()); + + } + @Test + @Betamax(tape = "trigger_job_as_user") + public void triggerJobDeprecatedAsUser() throws Exception { + RundeckClient client = createClient(TEST_TOKEN_3); + + final RundeckExecution test + = client.triggerJob("3170ba0e-6093-4b58-94d2-52988aefbfc9", null, null, "api-java-client-user-test1"); + + Assert.assertEquals((Long) 20L, test.getId()); + Assert.assertEquals(null, test.getArgstring()); + Assert.assertEquals(null, test.getAbortedBy()); + Assert.assertEquals("echo hi there ${job.username} ; sleep 90", test.getDescription()); + Assert.assertEquals("api-java-client-user-test1", test.getStartedBy()); + Assert.assertEquals(RundeckExecution.ExecutionStatus.RUNNING, test.getStatus()); + } @Test @Betamax(tape = "trigger_job_as_user") @@ -373,7 +402,10 @@ public class RundeckClientTest { RundeckClient client = createClient(TEST_TOKEN_3); final RundeckExecution test - = client.triggerJob("3170ba0e-6093-4b58-94d2-52988aefbfc9",null,null,"api-java-client-user-test1"); + = client.triggerJob(RunJobBuilder.builder() + .setJobId("3170ba0e-6093-4b58-94d2-52988aefbfc9") + .setAsUser("api-java-client-user-test1") + .create()); Assert.assertEquals((Long)20L, test.getId()); Assert.assertEquals(null, test.getArgstring()); @@ -385,7 +417,7 @@ public class RundeckClientTest { } @Test @Betamax(tape = "trigger_job_as_user_unauthorized") - public void triggerJobAsUserUnauthorized() throws Exception { + public void triggerJobDeprecatedAsUserUnauthorized() throws Exception { RundeckClient client = createClient(TEST_TOKEN_3); final RundeckExecution test; @@ -396,10 +428,26 @@ public class RundeckClientTest { Assert.assertEquals("Not authorized for action \"Run as User\" for Job ID 3170ba0e-6093-4b58-94d2-52988aefbfc9", e.getMessage()); } } + @Test + @Betamax(tape = "trigger_job_as_user_unauthorized") + public void triggerJobAsUserUnauthorized() throws Exception { + RundeckClient client = createClient(TEST_TOKEN_3); + + final RundeckExecution test; + try { + test = client.triggerJob(RunJobBuilder.builder() + .setJobId("3170ba0e-6093-4b58-94d2-52988aefbfc9") + .setAsUser("api-java-client-user-test2") + .create()); + Assert.fail("should not succeed"); + } catch (RundeckApiException e) { + Assert.assertEquals("Not authorized for action \"Run as User\" for Job ID 3170ba0e-6093-4b58-94d2-52988aefbfc9", e.getMessage()); + } + } @Test @Betamax(tape = "trigger_adhoc_command") - public void triggerAdhocCommand() throws Exception { + public void triggerAdhocCommandDeprecated() throws Exception { RundeckClient client = createClient(TEST_TOKEN_3); final RundeckExecution test @@ -413,9 +461,28 @@ public class RundeckClientTest { Assert.assertEquals(RundeckExecution.ExecutionStatus.SUCCEEDED, test.getStatus()); } + @Test + @Betamax(tape = "trigger_adhoc_command") + public void triggerAdhocCommand() throws Exception { + RundeckClient client = createClient(TEST_TOKEN_3); + + final RundeckExecution test + = client.triggerAdhocCommand(RunAdhocCommandBuilder.builder() + .setProject("test") + .setCommand("echo test trigger_adhoc_command") + .create()); + + Assert.assertEquals((Long) 23L, test.getId()); + Assert.assertEquals(null, test.getArgstring()); + Assert.assertEquals(null, test.getAbortedBy()); + Assert.assertEquals("echo test trigger_adhoc_command", test.getDescription()); + Assert.assertEquals("admin", test.getStartedBy()); + Assert.assertEquals(RundeckExecution.ExecutionStatus.SUCCEEDED, test.getStatus()); + } + @Test @Betamax(tape = "trigger_adhoc_command_as_user") - public void triggerAdhocCommandAsUser() throws Exception { + public void triggerAdhocCommandDeprecatedAsUser() throws Exception { RundeckClient client = createClient(TEST_TOKEN_3); final RundeckExecution test @@ -429,8 +496,29 @@ public class RundeckClientTest { Assert.assertEquals(RundeckExecution.ExecutionStatus.SUCCEEDED, test.getStatus()); } @Test + @Betamax(tape = "trigger_adhoc_command_as_user") + public void triggerAdhocCommandAsUser() throws Exception { + RundeckClient client = createClient(TEST_TOKEN_3); + + final RundeckExecution test + = client.triggerAdhocCommand( + RunAdhocCommandBuilder.builder() + .setProject("test") + .setCommand("echo test trigger_adhoc_command_as_user") + .setAsUser("api-java-client-test-run-command-as-user1") + .create() + ); + + Assert.assertEquals((Long) 24L, test.getId()); + Assert.assertEquals(null, test.getArgstring()); + Assert.assertEquals(null, test.getAbortedBy()); + Assert.assertEquals("echo test trigger_adhoc_command_as_user", test.getDescription()); + Assert.assertEquals("api-java-client-test-run-command-as-user1", test.getStartedBy()); + Assert.assertEquals(RundeckExecution.ExecutionStatus.SUCCEEDED, test.getStatus()); + } + @Test @Betamax(tape = "trigger_adhoc_command_as_user_unauthorized") - public void triggerAdhocCommandAsUserUnauthorized() throws Exception { + public void triggerAdhocCommandDeprecatedAsUserUnauthorized() throws Exception { RundeckClient client = createClient(TEST_TOKEN_3); final RundeckExecution test; @@ -441,7 +529,44 @@ public class RundeckClientTest { Assert.assertEquals("Not authorized for action \"Run as User\" for Run Adhoc", e.getMessage()); } } + @Test + @Betamax(tape = "trigger_adhoc_command_as_user_unauthorized") + public void triggerAdhocCommandAsUserUnauthorized() throws Exception { + RundeckClient client = createClient(TEST_TOKEN_3); + final RundeckExecution test; + try { + test = client.triggerAdhocCommand( + RunAdhocCommandBuilder.builder() + .setProject("test") + .setCommand("echo test trigger_adhoc_command_as_user") + .setAsUser("api-java-client-test-run-command-as-user1") + .create() + ); + Assert.fail("should not succeed"); + } catch (RundeckApiException e) { + Assert.assertEquals("Not authorized for action \"Run as User\" for Run Adhoc", e.getMessage()); + } + } + + @Test + @Betamax(tape = "trigger_adhoc_script") + public void triggerAdhocScriptDeprecated() throws Exception { + RundeckClient client = createClient(TEST_TOKEN_3); + String script = "#!/bin/bash\n" + + "echo test trigger_adhoc_script\n"; + ByteArrayInputStream byteArrayInputStream = new ByteArrayInputStream(script.getBytes()); + + final RundeckExecution test + = client.triggerAdhocScript("test", byteArrayInputStream,(Properties) null, null, null, null, null); + + Assert.assertEquals((Long) 25L, test.getId()); + Assert.assertEquals(null, test.getArgstring()); + Assert.assertEquals(null, test.getAbortedBy()); + Assert.assertEquals("#!/bin/bash\necho test trigger_adhoc_script", test.getDescription()); + Assert.assertEquals("admin", test.getStartedBy()); + Assert.assertEquals(RundeckExecution.ExecutionStatus.RUNNING, test.getStatus()); + } @Test @Betamax(tape = "trigger_adhoc_script") public void triggerAdhocScript() throws Exception { @@ -451,7 +576,8 @@ public class RundeckClientTest { ByteArrayInputStream byteArrayInputStream = new ByteArrayInputStream(script.getBytes()); final RundeckExecution test - = client.triggerAdhocScript("test", byteArrayInputStream, null, null, null, null, null); + = client.triggerAdhocScript(RunAdhocScriptBuilder.builder().setProject("test").setScript + (byteArrayInputStream).create()); Assert.assertEquals((Long) 25L, test.getId()); Assert.assertEquals(null, test.getArgstring()); @@ -462,6 +588,24 @@ public class RundeckClientTest { } @Test @Betamax(tape = "trigger_adhoc_script_as_user") + public void triggerAdhocScriptDeprecatedAsUser() throws Exception { + RundeckClient client = createClient(TEST_TOKEN_3); + String script = "#!/bin/bash\n" + + "echo test trigger_adhoc_script\n"; + ByteArrayInputStream byteArrayInputStream = new ByteArrayInputStream(script.getBytes()); + + final RundeckExecution test + = client.triggerAdhocScript("test", byteArrayInputStream, (Properties) null, null, null, null, "api-java-client-test-adhoc-script-as-user1"); + + Assert.assertEquals((Long) 26L, test.getId()); + Assert.assertEquals(null, test.getArgstring()); + Assert.assertEquals(null, test.getAbortedBy()); + Assert.assertEquals("#!/bin/bash\necho test trigger_adhoc_script", test.getDescription()); + Assert.assertEquals("api-java-client-test-adhoc-script-as-user1", test.getStartedBy()); + Assert.assertEquals(RundeckExecution.ExecutionStatus.RUNNING, test.getStatus()); + } + @Test + @Betamax(tape = "trigger_adhoc_script_as_user") public void triggerAdhocScriptAsUser() throws Exception { RundeckClient client = createClient(TEST_TOKEN_3); String script = "#!/bin/bash\n" + @@ -469,7 +613,8 @@ public class RundeckClientTest { ByteArrayInputStream byteArrayInputStream = new ByteArrayInputStream(script.getBytes()); final RundeckExecution test - = client.triggerAdhocScript("test", byteArrayInputStream, null, null, null, null, "api-java-client-test-adhoc-script-as-user1"); + = client.triggerAdhocScript(RunAdhocScriptBuilder.builder().setProject("test").setScript + (byteArrayInputStream).setAsUser("api-java-client-test-adhoc-script-as-user1").create()); Assert.assertEquals((Long) 26L, test.getId()); Assert.assertEquals(null, test.getArgstring()); @@ -480,6 +625,23 @@ public class RundeckClientTest { } @Test @Betamax(tape = "trigger_adhoc_script_as_user_unauthorized") + public void triggerAdhocScriptDeprecatedAsUserUnauthorized() throws Exception { + RundeckClient client = createClient(TEST_TOKEN_3); + String script = "#!/bin/bash\n" + + "echo test trigger_adhoc_script\n"; + ByteArrayInputStream byteArrayInputStream = new ByteArrayInputStream(script.getBytes()); + + try{ + final RundeckExecution test + = client.triggerAdhocScript("test", byteArrayInputStream, (Properties) null, null, null, null, "api-java-client-test-adhoc-script-as-user1"); + Assert.fail("should not succeed"); + } catch (RundeckApiException e) { + Assert.assertEquals("Not authorized for action \"Run as User\" for Run Adhoc", e.getMessage()); + } + + } + @Test + @Betamax(tape = "trigger_adhoc_script_as_user_unauthorized") public void triggerAdhocScriptAsUserUnauthorized() throws Exception { RundeckClient client = createClient(TEST_TOKEN_3); String script = "#!/bin/bash\n" + @@ -488,7 +650,8 @@ public class RundeckClientTest { try{ final RundeckExecution test - = client.triggerAdhocScript("test", byteArrayInputStream, null, null, null, null, "api-java-client-test-adhoc-script-as-user1"); + = client.triggerAdhocScript(RunAdhocScriptBuilder.builder().setProject("test").setScript + (byteArrayInputStream).setAsUser("api-java-client-test-adhoc-script-as-user1").create()); Assert.fail("should not succeed"); } catch (RundeckApiException e) { Assert.assertEquals("Not authorized for action \"Run as User\" for Run Adhoc", e.getMessage()); From 5d1ae5fa2ce23e18392ecad39027cc6b8c6d441d Mon Sep 17 00:00:00 2001 From: Greg Schueler Date: Tue, 9 Jul 2013 11:48:28 -0700 Subject: [PATCH 2/3] Deprecate run* methods --- src/main/java/org/rundeck/api/RunAdhoc.java | 10 +- .../java/org/rundeck/api/RunAdhocCommand.java | 2 +- .../java/org/rundeck/api/RunAdhocScript.java | 2 +- src/main/java/org/rundeck/api/RunJob.java | 10 +- .../java/org/rundeck/api/RundeckClient.java | 563 +++++++++++------- 5 files changed, 368 insertions(+), 219 deletions(-) diff --git a/src/main/java/org/rundeck/api/RunAdhoc.java b/src/main/java/org/rundeck/api/RunAdhoc.java index 7fe2ddf..0713cc8 100644 --- a/src/main/java/org/rundeck/api/RunAdhoc.java +++ b/src/main/java/org/rundeck/api/RunAdhoc.java @@ -7,31 +7,31 @@ import java.util.Properties; */ public interface RunAdhoc { /** - * Project name + * Project name, required * @return */ String getProject(); /** - * Node filters + * Filters for selecting nodes on which the command will be executed. See {@link NodeFiltersBuilder} * @return */ Properties getNodeFilters(); /** - * Threadcount + * Thread count to use (for parallelizing when running on multiple nodes) - optional * @return */ Integer getNodeThreadcount(); /** - * Keepgoing + * if true, continue executing on other nodes even if some fail - optional * @return */ Boolean getNodeKeepgoing(); /** - * As User + * Specify a user name to run the job as, must have 'runAs' permission * @return */ String getAsUser(); diff --git a/src/main/java/org/rundeck/api/RunAdhocCommand.java b/src/main/java/org/rundeck/api/RunAdhocCommand.java index 83c77d1..6b6debe 100644 --- a/src/main/java/org/rundeck/api/RunAdhocCommand.java +++ b/src/main/java/org/rundeck/api/RunAdhocCommand.java @@ -6,7 +6,7 @@ package org.rundeck.api; public interface RunAdhocCommand extends RunAdhoc { /** - * Command to execute + * Command to executed * @return */ String getCommand(); diff --git a/src/main/java/org/rundeck/api/RunAdhocScript.java b/src/main/java/org/rundeck/api/RunAdhocScript.java index 98c8d66..c4076f1 100644 --- a/src/main/java/org/rundeck/api/RunAdhocScript.java +++ b/src/main/java/org/rundeck/api/RunAdhocScript.java @@ -8,7 +8,7 @@ import java.io.InputStream; public interface RunAdhocScript extends RunAdhoc { /** - * Stream containing script + * InputStream for reading the script to be executed - mandatory * @return */ InputStream getScript(); diff --git a/src/main/java/org/rundeck/api/RunJob.java b/src/main/java/org/rundeck/api/RunJob.java index 3bc7c85..429c502 100644 --- a/src/main/java/org/rundeck/api/RunJob.java +++ b/src/main/java/org/rundeck/api/RunJob.java @@ -7,25 +7,27 @@ import java.util.Properties; */ public interface RunJob { /** - * Job ID + * Identifier of the job - mandatory * @return */ String getJobId(); /** - * Options to job + * Options of the job - optional. See {@link OptionsBuilder}. * @return */ Properties getOptions(); /** - * Node filters + * Node filters for overriding the nodes on which the job will be executed - optional. See + * {@link NodeFiltersBuilder} + * * @return */ Properties getNodeFilters(); /** - * as User + * Specify a user name to run the job as, must have 'runAs' permission * @return */ String getAsUser(); diff --git a/src/main/java/org/rundeck/api/RundeckClient.java b/src/main/java/org/rundeck/api/RundeckClient.java index 1ae3bb1..ee36331 100644 --- a/src/main/java/org/rundeck/api/RundeckClient.java +++ b/src/main/java/org/rundeck/api/RundeckClient.java @@ -56,20 +56,20 @@ import java.util.concurrent.TimeUnit; * RundeckClient rundeck = new RundeckClient("http://localhost:4440", "admin", "admin"); * // or for a token-based authentication : * RundeckClient rundeck = new RundeckClient("http://localhost:4440", "PDDNKo5VE29kpk4prOUDr2rsKdRkEvsD"); - * + * * List<RundeckProject> projects = rundeck.getProjects(); - * + * * 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"); - * + * * rundeck.exportJobsToFile("/tmp/jobs.xml", FileType.XML, "my-project"); * rundeck.importJobs("/tmp/jobs.xml", FileType.XML); * * - * + * * @author Vincent Behar */ public class RundeckClient implements Serializable { @@ -118,7 +118,7 @@ public class RundeckClient implements Serializable { private String login; private String password; - + private String sessionID; void setToken(String token) { @@ -156,7 +156,7 @@ public class RundeckClient implements Serializable { /** * Instantiate a new {@link RundeckClient} for the RunDeck instance at the given url, using login-based * authentication. - * + * * @param url of the RunDeck instance ("http://localhost:4440", "http://rundeck.your-compagny.com/", etc) * @param login to use for authentication on the RunDeck instance * @param password to use for authentication on the RunDeck instance @@ -172,9 +172,9 @@ public class RundeckClient implements Serializable { } /** - * Instantiate a new {@link RundeckClient} for the RunDeck instance at the given url, + * Instantiate a new {@link RundeckClient} for the RunDeck instance at the given url, * using token-based or session-based authentication. Either token or sessionID must be valid - * + * * @param url of the RunDeck instance ("http://localhost:4440", "http://rundeck.your-compagny.com/", etc) * @param token to use for authentication on the RunDeck instance * @param sessionID to use for session authentication on the RunDeck instance @@ -186,12 +186,12 @@ public class RundeckClient implements Serializable { this(url); if(useToken){ - AssertUtil.notBlank(token, "Token is mandatory!"); + AssertUtil.notBlank(token, "Token is mandatory!"); this.token = token; this.sessionID = null; } else { - AssertUtil.notBlank(sessionID, "sessionID is mandatory!"); + AssertUtil.notBlank(sessionID, "sessionID is mandatory!"); this.sessionID = sessionID; this.token = null; } @@ -221,7 +221,7 @@ public class RundeckClient implements Serializable { /** * Try to "ping" the RunDeck instance to see if it is alive - * + * * @throws RundeckApiException if the ping fails */ public void ping() throws RundeckApiException { @@ -230,7 +230,7 @@ public class RundeckClient implements Serializable { /** * Test the authentication on the RunDeck instance. - * + * * @return sessionID if doing username+password login and it succeeded * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) * @throws RundeckApiTokenException if the token is invalid (in case of token-based authentication) @@ -254,7 +254,7 @@ public class RundeckClient implements Serializable { /** * List all projects - * + * * @return a {@link List} of {@link RundeckProject} : might be empty, but won't be null * @throws RundeckApiException in case of error when calling the API * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) @@ -268,7 +268,7 @@ public class RundeckClient implements Serializable { /** * Get the definition of a single project, identified by the given name - * + * * @param projectName name of the project - mandatory * @return a {@link RundeckProject} instance - won't be null * @throws RundeckApiException in case of error when calling the API (non-existent project with this name) @@ -289,7 +289,7 @@ public class RundeckClient implements Serializable { /** * List all jobs (for all projects) - * + * * @return a {@link List} of {@link RundeckJob} : might be empty, but won't be null * @throws RundeckApiException in case of error when calling the API * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) @@ -305,7 +305,7 @@ public class RundeckClient implements Serializable { /** * List all jobs that belongs to the given project - * + * * @param project name of the project - mandatory * @return a {@link List} of {@link 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) @@ -321,7 +321,7 @@ public class RundeckClient implements Serializable { /** * List the jobs that belongs to the given project, and matches the given criteria (jobFilter, groupPath and jobIds) - * + * * @param project name of the project - mandatory * @param jobFilter a filter for the job Name - optional * @param groupPath a group or partial group path to include all jobs within that group path - optional @@ -345,7 +345,7 @@ public class RundeckClient implements Serializable { /** * Export the definitions of all jobs that belongs to the given project - * + * * @param filename path of the file where the content should be saved - mandatory * @param format of the export. See {@link FileType} - mandatory * @param project name of the project - mandatory @@ -366,7 +366,7 @@ public class RundeckClient implements Serializable { /** * Export the definitions of all jobs that belongs to the given project - * + * * @param filename path of the file where the content should be saved - mandatory * @param format of the export. See {@link FileType} - mandatory * @param project name of the project - mandatory @@ -386,7 +386,7 @@ public class RundeckClient implements Serializable { /** * Export the definitions of the jobs that belongs to the given project, and matches the given criteria (jobFilter, * groupPath and jobIds) - * + * * @param filename path of the file where the content should be saved - mandatory * @param format of the export. See {@link FileType} - mandatory * @param project name of the project - mandatory @@ -417,7 +417,7 @@ public class RundeckClient implements Serializable { /** * Export the definitions of the jobs that belongs to the given project, and matches the given criteria (jobFilter, * groupPath and jobIds) - * + * * @param filename path of the file where the content should be saved - mandatory * @param format of the export. See {@link FileType} - mandatory * @param project name of the project - mandatory @@ -438,11 +438,11 @@ public class RundeckClient implements Serializable { AssertUtil.notBlank(filename, "filename is mandatory to export a job !"); InputStream inputStream = exportJobs(format, project, jobFilter, groupPath, jobIds); FileUtils.writeByteArrayToFile(new File(filename), IOUtils.toByteArray(inputStream)); - } + } /** * Export the definitions of all jobs that belongs to the given project - * + * * @param format of the export. See {@link FileType} - mandatory * @param project name of the project - mandatory * @return an {@link InputStream} instance, not linked to any network resources - won't be null @@ -462,7 +462,7 @@ public class RundeckClient implements Serializable { /** * Export the definitions of all jobs that belongs to the given project - * + * * @param format of the export. See {@link FileType} - mandatory * @param project name of the project - mandatory * @return an {@link InputStream} instance, not linked to any network resources - won't be null @@ -481,7 +481,7 @@ public class RundeckClient implements Serializable { /** * Export the definitions of the jobs that belongs to the given project, and matches the given criteria (jobFilter, * groupPath and jobIds) - * + * * @param format of the export. See {@link FileType} - mandatory * @param project name of the project - mandatory * @param jobFilter a filter for the job Name - optional @@ -505,7 +505,7 @@ public class RundeckClient implements Serializable { /** * Export the definitions of the jobs that belongs to the given project, and matches the given criteria (jobFilter, * groupPath and jobIds) - * + * * @param format of the export. See {@link FileType} - mandatory * @param project name of the project - mandatory * @param jobFilter a filter for the job Name - optional @@ -531,7 +531,7 @@ public class RundeckClient implements Serializable { /** * Export the definition of a single job (identified by the given ID) - * + * * @param filename path of the file where the content should be saved - mandatory * @param format of the export. See {@link FileType} - mandatory * @param jobId identifier of the job - mandatory @@ -553,7 +553,7 @@ public class RundeckClient implements Serializable { /** * Export the definition of a single job (identified by the given ID) - * + * * @param filename path of the file where the content should be saved - mandatory * @param format of the export. See {@link FileType} - mandatory * @param jobId identifier of the job - mandatory @@ -575,7 +575,7 @@ public class RundeckClient implements Serializable { /** * Export the definition of a single job, identified by the given ID - * + * * @param format of the export. See {@link FileType} - mandatory * @param jobId identifier of the job - mandatory * @return an {@link InputStream} instance, not linked to any network resources - won't be null @@ -595,7 +595,7 @@ public class RundeckClient implements Serializable { /** * Export the definition of a single job, identified by the given ID - * + * * @param format of the export. See {@link FileType} - mandatory * @param jobId identifier of the job - mandatory * @return an {@link InputStream} instance, not linked to any network resources - won't be null @@ -615,7 +615,7 @@ public class RundeckClient implements Serializable { /** * Import the definitions of jobs, from the given file - * + * * @param filename of the file containing the jobs definitions - mandatory * @param fileType type of the file. See {@link FileType} - mandatory * @return a {@link RundeckJobsImportResult} instance - won't be null @@ -636,7 +636,7 @@ public class RundeckClient implements Serializable { /** * Import the definitions of jobs, from the given file - * + * * @param filename of the file containing the jobs definitions - mandatory * @param fileType type of the file. See {@link FileType} - mandatory * @return a {@link RundeckJobsImportResult} instance - won't be null @@ -655,7 +655,7 @@ public class RundeckClient implements Serializable { /** * Import the definitions of jobs, from the given file, using the given behavior - * + * * @param filename of the file containing the jobs definitions - mandatory * @param fileType type of the file. See {@link FileType} - mandatory * @param importBehavior see {@link RundeckJobsImportMethod} @@ -680,7 +680,7 @@ public class RundeckClient implements Serializable { /** * Import the definitions of jobs, from the given file, using the given behavior - * + * * @param filename of the file containing the jobs definitions - mandatory * @param fileType type of the file. See {@link FileType} - mandatory * @param importBehavior see {@link RundeckJobsImportMethod} @@ -707,7 +707,7 @@ public class RundeckClient implements Serializable { /** * Import the definitions of jobs, from the given input stream - * + * * @param stream inputStream for reading the definitions - mandatory * @param fileType type of the file. See {@link FileType} - mandatory * @return a {@link RundeckJobsImportResult} instance - won't be null @@ -727,7 +727,7 @@ public class RundeckClient implements Serializable { /** * Import the definitions of jobs, from the given input stream - * + * * @param stream inputStream for reading the definitions - mandatory * @param fileType type of the file. See {@link FileType} - mandatory * @return a {@link RundeckJobsImportResult} instance - won't be null @@ -745,7 +745,7 @@ public class RundeckClient implements Serializable { /** * Import the definitions of jobs, from the given input stream, using the given behavior - * + * * @param stream inputStream for reading the definitions - mandatory * @param fileType type of the file. See {@link FileType} - mandatory * @param importBehavior see {@link RundeckJobsImportMethod} @@ -768,7 +768,7 @@ public class RundeckClient implements Serializable { /** * Import the definitions of jobs, from the given input stream, using the given behavior - * + * * @param stream inputStream for reading the definitions - mandatory * @param fileType type of the file. See {@link FileType} - mandatory * @param importBehavior see {@link RundeckJobsImportMethod} @@ -793,7 +793,7 @@ public class RundeckClient implements Serializable { /** * 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). - * + * * @param project name of the project - mandatory * @param groupPath group to which the job belongs (if it belongs to a group) - optional * @param name of the job to find - mandatory @@ -814,7 +814,7 @@ public class RundeckClient implements Serializable { /** * Get the definition of a single job, identified by the given ID - * + * * @param jobId identifier of the job - mandatory * @return a {@link RundeckJob} instance - won't be null * @throws RundeckApiException in case of error when calling the API (non-existent job with this ID) @@ -832,7 +832,7 @@ public class RundeckClient implements Serializable { /** * Delete a single job, identified by the given ID - * + * * @param jobId identifier of the job - mandatory * @return 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) @@ -867,7 +867,7 @@ public class RundeckClient implements Serializable { /** * Trigger the execution of a RunDeck job (identified by the given ID), and return immediately (without waiting the * end of the job execution) - * + * * @param jobId identifier of the job - mandatory * @return a {@link 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) @@ -886,7 +886,7 @@ public class RundeckClient implements Serializable { /** * Trigger the execution of a RunDeck job (identified by the given ID), and return immediately (without waiting the * end of the job execution) - * + * * @param jobId identifier of the job - mandatory * @param options of the job - optional. See {@link OptionsBuilder}. * @return a {@link RundeckExecution} instance for the newly created (and running) execution - won't be null @@ -906,7 +906,7 @@ public class RundeckClient implements Serializable { /** * Trigger the execution of a RunDeck job (identified by the given ID), and return immediately (without waiting the * end of the job execution) - * + * * @param jobId identifier of the job - mandatory * @param options of the job - optional. See {@link OptionsBuilder}. * @param nodeFilters for overriding the nodes on which the job will be executed - optional. See @@ -955,11 +955,7 @@ public class RundeckClient implements Serializable { * Trigger the execution of a RunDeck job (identified by the given ID), and return immediately (without waiting the * end of the job execution) * - * @param jobId identifier of the job - mandatory - * @param options of the job - optional. See {@link OptionsBuilder}. - * @param nodeFilters for overriding the nodes on which the job will be executed - optional. See - * {@link NodeFiltersBuilder} - * @param asUser specify a user name to run the job as, must have 'runAs' permission + * @param jobRun the RunJob, see {@link RunJobBuilder} * @return a {@link 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) * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) @@ -968,7 +964,7 @@ public class RundeckClient implements Serializable { * @see #triggerJob(String) * @see #runJob(String, Properties, Properties) */ - public RundeckExecution triggerJob(RunJob jobRun) + public RundeckExecution triggerJob(final RunJob jobRun) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { AssertUtil.notBlank(jobRun.getJobId(), "jobId is mandatory to trigger a job !"); ApiPathBuilder apiPath = new ApiPathBuilder("/job/", jobRun.getJobId(), "/run").param("argString", @@ -984,7 +980,7 @@ public class RundeckClient implements Serializable { * 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. - * + * * @param jobId identifier of the job - mandatory * @return a {@link 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) @@ -1005,7 +1001,7 @@ public class RundeckClient implements Serializable { * 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. - * + * * @param jobId identifier of the job - mandatory * @param options of the job - optional. See {@link OptionsBuilder}. * @return a {@link RundeckExecution} instance for the (finished/aborted) execution - won't be null @@ -1027,7 +1023,7 @@ public class RundeckClient implements Serializable { * 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. - * + * * @param jobId identifier of the job - mandatory * @param options of the job - optional. See {@link OptionsBuilder}. * @param nodeFilters for overriding the nodes on which the job will be executed - optional. See @@ -1052,7 +1048,7 @@ public class RundeckClient implements Serializable { * 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. * - * @param runJob the job run parameters + * @param jobRun the RunJob, see {@link RunJobBuilder} * * @return a {@link RundeckExecution} instance for the (finished/aborted) execution - won't be null * @@ -1071,7 +1067,7 @@ public class RundeckClient implements Serializable { * 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. - * + * * @param jobId identifier of the job - mandatory * @param options of the job - optional. See {@link OptionsBuilder}. * @param poolingInterval for checking the status of the execution. Must be > 0. @@ -1095,7 +1091,7 @@ public class RundeckClient implements Serializable { * 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. - * + * * @param jobId identifier of the job - mandatory * @param options of the job - optional. See {@link OptionsBuilder}. * @param nodeFilters for overriding the nodes on which the job will be executed - optional. See @@ -1154,11 +1150,7 @@ public class RundeckClient implements Serializable { * 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. * - * @param jobId identifier of the job - mandatory - * @param options of the job - optional. See {@link OptionsBuilder}. - * @param nodeFilters for overriding the nodes on which the job will be executed - optional. See {@link - * NodeFiltersBuilder} - * @param asUser specify a user name to run the job as, must have 'runAs' permission + * @param jobRun the RunJob, see {@link RunJobBuilder} * @param poolingInterval for checking the status of the execution. Must be > 0. * @param poolingUnit unit (seconds, milli-seconds, ...) of the interval. Default to seconds. * @@ -1201,7 +1193,7 @@ public class RundeckClient implements Serializable { /** * 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. - * + * * @param project name of the project - mandatory * @param command to be executed - mandatory * @return a {@link RundeckExecution} instance for the newly created (and running) execution - won't be null @@ -1221,7 +1213,7 @@ public class RundeckClient implements Serializable { /** * 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. - * + * * @param project name of the project - mandatory * @param command to be executed - mandatory * @param nodeFilters for selecting nodes on which the command will be executed. See {@link NodeFiltersBuilder} @@ -1242,7 +1234,7 @@ public class RundeckClient implements Serializable { /** * 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. - * + * * @param project name of the project - mandatory * @param command to be executed - mandatory * @param nodeFilters for selecting nodes on which the command will be executed. See {@link NodeFiltersBuilder} @@ -1297,12 +1289,7 @@ public class RundeckClient implements Serializable { * 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. * - * @param project name of the project - mandatory - * @param command to be executed - mandatory - * @param nodeFilters for selecting nodes on which the command will be executed. See {@link NodeFiltersBuilder} - * @param nodeThreadcount thread count to use (for parallelizing when running on multiple nodes) - optional - * @param nodeKeepgoing if true, continue executing on other nodes even if some fail - optional - * @param asUser specify a user name to run the job as, must have 'runAs' permission + * @param command the RunAdhocCommand. Project and command are mandatory, see {@link RunAdhocCommandBuilder} * @return a {@link 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) * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) @@ -1334,7 +1321,7 @@ public class RundeckClient implements Serializable { * 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. - * + * * @param project name of the project - mandatory * @param command to be executed - mandatory * @return a {@link RundeckExecution} instance for the (finished/aborted) execution - won't be null @@ -1344,6 +1331,8 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the project or command is blank (null, empty or whitespace) * @see #runAdhocCommand(String, String, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocCommand(String, String) + * @deprecated use {@link #runAdhocCommand(RunAdhocCommand)}, this method will + * be removed in version 10 of this library */ public RundeckExecution runAdhocCommand(String project, String command) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { @@ -1355,7 +1344,7 @@ public class RundeckClient implements Serializable { * 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. - * + * * @param project name of the project - mandatory * @param command to be executed - mandatory * @param poolingInterval for checking the status of the execution. Must be > 0. @@ -1367,6 +1356,8 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the project or command is blank (null, empty or whitespace) * @see #runAdhocCommand(String, String, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocCommand(String, String) + * @deprecated use {@link #runAdhocCommand(RunAdhocCommand, long, java.util.concurrent.TimeUnit)}, this method will + * be removed in version 10 of this library */ public RundeckExecution runAdhocCommand(String project, String command, long poolingInterval, TimeUnit poolingUnit) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { @@ -1377,7 +1368,7 @@ public class RundeckClient implements Serializable { * 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. - * + * * @param project name of the project - mandatory * @param command to be executed - mandatory * @param nodeFilters for selecting nodes on which the command will be executed. See {@link NodeFiltersBuilder} @@ -1388,6 +1379,8 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the project or command is blank (null, empty or whitespace) * @see #runAdhocCommand(String, String, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocCommand(String, String, Properties) + * @deprecated use {@link #runAdhocCommand(RunAdhocCommand)}, this method will + * be removed in version 10 of this library */ public RundeckExecution runAdhocCommand(String project, String command, Properties nodeFilters) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { @@ -1399,7 +1392,7 @@ public class RundeckClient implements Serializable { * 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. - * + * * @param project name of the project - mandatory * @param command to be executed - mandatory * @param nodeFilters for selecting nodes on which the command will be executed. See {@link NodeFiltersBuilder} @@ -1412,6 +1405,8 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the project or command is blank (null, empty or whitespace) * @see #runAdhocCommand(String, String, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocCommand(String, String, Properties) + * @deprecated use {@link #runAdhocCommand(RunAdhocCommand, long, java.util.concurrent.TimeUnit)}, this method will + * be removed in version 10 of this library */ public RundeckExecution runAdhocCommand(String project, String command, Properties nodeFilters, long poolingInterval, TimeUnit poolingUnit) throws RundeckApiException, RundeckApiLoginException, @@ -1423,7 +1418,7 @@ public class RundeckClient implements Serializable { * 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. - * + * * @param project name of the project - mandatory * @param command to be executed - mandatory * @param nodeFilters for selecting nodes on which the command will be executed. See {@link NodeFiltersBuilder} @@ -1436,6 +1431,8 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the project or command is blank (null, empty or whitespace) * @see #runAdhocCommand(String, String, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocCommand(String, String, Properties, Integer, Boolean) + * @deprecated use {@link #runAdhocCommand(RunAdhocCommand)}, this method will + * be removed in version 10 of this library */ public RundeckExecution runAdhocCommand(String project, String command, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing) throws RundeckApiException, RundeckApiLoginException, @@ -1451,29 +1448,25 @@ public class RundeckClient implements Serializable { /** * 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. - * - * @param project name of the project - mandatory - * @param command to be executed - mandatory - * @param nodeFilters for selecting nodes on which the command will be executed. See {@link NodeFiltersBuilder} - * @param nodeThreadcount thread count to use (for parallelizing when running on multiple nodes) - optional - * @param nodeKeepgoing if true, continue executing on other nodes even if some fail - optional - * @param poolingInterval for checking the status of the execution. Must be > 0. - * @param poolingUnit unit (seconds, milli-seconds, ...) of the interval. Default to seconds. + * 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. + * + * @param command the RunAdhocCommand, see {@link RunAdhocCommandBuilder} * @return a {@link 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) * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) * @throws RundeckApiTokenException if the token is invalid (in case of token-based authentication) * @throws IllegalArgumentException if the project or command is blank (null, empty or whitespace) - * @see #triggerAdhocCommand(String, String, Properties, Integer, Boolean) + * @see #runAdhocCommand(String, String, Properties, Integer, Boolean, long, TimeUnit) + * @see #triggerAdhocCommand(RunAdhocCommand) */ - public RundeckExecution runAdhocCommand(String project, String command, Properties nodeFilters, - Integer nodeThreadcount, Boolean nodeKeepgoing, long poolingInterval, TimeUnit poolingUnit) - throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { - return runAdhocCommand(project, command, nodeFilters, nodeThreadcount, nodeKeepgoing, null, poolingInterval, poolingUnit); + public RundeckExecution runAdhocCommand(RunAdhocCommand command) throws RundeckApiException, RundeckApiLoginException, + RundeckApiTokenException, IllegalArgumentException { + return runAdhocCommand(command, + DEFAULT_POOLING_INTERVAL, + DEFAULT_POOLING_UNIT); } + /** * 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 @@ -1493,10 +1486,69 @@ public class RundeckClient implements Serializable { * @throws RundeckApiTokenException if the token is invalid (in case of token-based authentication) * @throws IllegalArgumentException if the project or command is blank (null, empty or whitespace) * @see #triggerAdhocCommand(String, String, Properties, Integer, Boolean) + * @deprecated use {@link #runAdhocCommand(RunAdhocCommand, long, java.util.concurrent.TimeUnit)}, this method will + * be removed in version 10 of this library + */ + public RundeckExecution runAdhocCommand(String project, String command, Properties nodeFilters, + Integer nodeThreadcount, Boolean nodeKeepgoing, long poolingInterval, TimeUnit poolingUnit) + throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { + return runAdhocCommand(project, command, nodeFilters, nodeThreadcount, nodeKeepgoing, null, poolingInterval, poolingUnit); + } + + /** + * 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. + * + * @param project name of the project - mandatory + * @param command to be executed - mandatory + * @param nodeFilters for selecting nodes on which the command will be executed. See {@link NodeFiltersBuilder} + * @param nodeThreadcount thread count to use (for parallelizing when running on multiple nodes) - optional + * @param nodeKeepgoing if true, continue executing on other nodes even if some fail - optional + * @param poolingInterval for checking the status of the execution. Must be > 0. + * @param poolingUnit unit (seconds, milli-seconds, ...) of the interval. Default to seconds. + * + * @return a {@link 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) + * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) + * @throws RundeckApiTokenException if the token is invalid (in case of token-based authentication) + * @throws IllegalArgumentException if the project or command is blank (null, empty or whitespace) + * @see #triggerAdhocCommand(String, String, Properties, Integer, Boolean) + * @deprecated use {@link #runAdhocCommand(RunAdhocCommand, long, java.util.concurrent.TimeUnit)}, this method will + * be removed in version 10 of this library */ public RundeckExecution runAdhocCommand(String project, String command, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing, String asUser, long poolingInterval, TimeUnit poolingUnit) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { + return runAdhocCommand(RunAdhocCommandBuilder.builder() + .setProject(project) + .setCommand(command) + .setNodeFilters(nodeFilters) + .setNodeThreadcount(nodeThreadcount) + .setNodeKeepgoing(nodeKeepgoing) + .setAsUser(asUser) + .create(), poolingInterval, poolingUnit); + } + /** + * 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. + * + * @param command the RunAdhocCommand, see {@link RunAdhocCommandBuilder} + * @param poolingInterval for checking the status of the execution. Must be > 0. + * @param poolingUnit unit (seconds, milli-seconds, ...) of the interval. Default to seconds. + * @return a {@link 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) + * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) + * @throws RundeckApiTokenException if the token is invalid (in case of token-based authentication) + * @throws IllegalArgumentException if the project or command is blank (null, empty or whitespace) + * @see #triggerAdhocCommand(RunAdhocCommand) + */ + public RundeckExecution runAdhocCommand(RunAdhocCommand command, long poolingInterval, TimeUnit poolingUnit) + throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { if (poolingInterval <= 0) { poolingInterval = DEFAULT_POOLING_INTERVAL; poolingUnit = DEFAULT_POOLING_UNIT; @@ -1505,7 +1557,7 @@ public class RundeckClient implements Serializable { poolingUnit = DEFAULT_POOLING_UNIT; } - RundeckExecution execution = triggerAdhocCommand(project, command, nodeFilters, nodeThreadcount, nodeKeepgoing,asUser); + RundeckExecution execution = triggerAdhocCommand(command); while (ExecutionStatus.RUNNING.equals(execution.getStatus())) { try { Thread.sleep(poolingUnit.toMillis(poolingInterval)); @@ -1524,7 +1576,7 @@ public class RundeckClient implements Serializable { /** * Trigger the execution of an ad-hoc script, and return immediately (without waiting the end of the execution). The * script will not be dispatched to nodes, but be executed on the RunDeck server. - * + * * @param project name of the project - mandatory * @param scriptFilename filename of the script to be executed - mandatory * @return a {@link RundeckExecution} instance for the newly created (and running) execution - won't be null @@ -1535,7 +1587,8 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #triggerAdhocScript(String, String, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, String) - * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)}, this method will be + * removed in version 10 of this library */ public RundeckExecution triggerAdhocScript(String project, String scriptFilename) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException, IOException { @@ -1545,7 +1598,7 @@ public class RundeckClient implements Serializable { /** * Trigger the execution of an ad-hoc script, and return immediately (without waiting the end of the execution). The * script will not be dispatched to nodes, but be executed on the RunDeck server. - * + * * @param project name of the project - mandatory * @param scriptFilename filename of the script to be executed - mandatory * @param options of the script - optional. See {@link OptionsBuilder}. @@ -1557,7 +1610,8 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #triggerAdhocScript(String, String, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, String, Properties) - * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)}, this method will be + * removed in version 10 of this library */ public RundeckExecution triggerAdhocScript(String project, String scriptFilename, Properties options) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException, @@ -1568,7 +1622,7 @@ public class RundeckClient implements Serializable { /** * Trigger the execution of an ad-hoc script, and return immediately (without waiting the end of the execution). The * script will be dispatched to nodes, accordingly to the nodeFilters parameter. - * + * * @param project name of the project - mandatory * @param scriptFilename filename of the script to be executed - mandatory * @param options of the script - optional. See {@link OptionsBuilder}. @@ -1581,7 +1635,8 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #triggerAdhocScript(String, String, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, String, Properties, Properties) - * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)}, this method will be + * removed in version 10 of this library */ public RundeckExecution triggerAdhocScript(String project, String scriptFilename, Properties options, Properties nodeFilters) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, @@ -1592,7 +1647,7 @@ public class RundeckClient implements Serializable { /** * Trigger the execution of an ad-hoc script, and return immediately (without waiting the end of the execution). The * script will be dispatched to nodes, accordingly to the nodeFilters parameter. - * + * * @param project name of the project - mandatory * @param scriptFilename filename of the script to be executed - mandatory * @param options of the script - optional. See {@link OptionsBuilder}. @@ -1607,7 +1662,8 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #triggerAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, String, Properties, Properties, Integer, Boolean, long, TimeUnit) - * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)}, this method will be + * removed in version 10 of this library */ public RundeckExecution triggerAdhocScript(String project, String scriptFilename, Properties options, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing) throws RundeckApiException, @@ -1632,7 +1688,8 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #triggerAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, String, Properties, Properties, Integer, Boolean, long, TimeUnit) - * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)}, this method will be + * removed in version 10 of this library */ public RundeckExecution triggerAdhocScript(String project, String scriptFilename, Properties options, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing,String asUser) throws RundeckApiException, @@ -1658,7 +1715,8 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #triggerAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, String, Properties, Properties, Integer, Boolean, long, TimeUnit) - * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)}, this method will be + * removed in version 10 of this library */ public RundeckExecution triggerAdhocScript(String project, String scriptFilename, String argString, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing,String asUser) throws RundeckApiException, @@ -1684,7 +1742,7 @@ public class RundeckClient implements Serializable { /** * Trigger the execution of an ad-hoc script, and return immediately (without waiting the end of the execution). The * script will not be dispatched to nodes, but be executed on the RunDeck server. - * + * * @param project name of the project - mandatory * @param script inputStream for reading the script to be executed - mandatory * @return a {@link RundeckExecution} instance for the newly created (and running) execution - won't be null @@ -1694,7 +1752,8 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the project is blank (null, empty or whitespace) or the script is null * @see #triggerAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, InputStream) - * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)}, this method will be + * removed in version 10 of this library */ public RundeckExecution triggerAdhocScript(String project, InputStream script) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { @@ -1704,7 +1763,7 @@ public class RundeckClient implements Serializable { /** * Trigger the execution of an ad-hoc script, and return immediately (without waiting the end of the execution). The * script will not be dispatched to nodes, but be executed on the RunDeck server. - * + * * @param project name of the project - mandatory * @param script inputStream for reading the script to be executed - mandatory * @param options of the script - optional. See {@link OptionsBuilder}. @@ -1715,7 +1774,8 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the project is blank (null, empty or whitespace) or the script is null * @see #triggerAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, InputStream, Properties) - * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)}, this method will be + * removed in version 10 of this library */ public RundeckExecution triggerAdhocScript(String project, InputStream script, Properties options) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { @@ -1725,7 +1785,7 @@ public class RundeckClient implements Serializable { /** * Trigger the execution of an ad-hoc script, and return immediately (without waiting the end of the execution). The * script will be dispatched to nodes, accordingly to the nodeFilters parameter. - * + * * @param project name of the project - mandatory * @param script inputStream for reading the script to be executed - mandatory * @param options of the script - optional. See {@link OptionsBuilder}. @@ -1737,7 +1797,8 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the project is blank (null, empty or whitespace) or the script is null * @see #triggerAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, InputStream, Properties, Properties) - * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)}, this method will be + * removed in version 10 of this library */ public RundeckExecution triggerAdhocScript(String project, InputStream script, Properties options, Properties nodeFilters) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, @@ -1748,7 +1809,7 @@ public class RundeckClient implements Serializable { /** * Trigger the execution of an ad-hoc script, and return immediately (without waiting the end of the execution). The * script will be dispatched to nodes, accordingly to the nodeFilters parameter. - * + * * @param project name of the project - mandatory * @param script inputStream for reading the script to be executed - mandatory * @param options of the script - optional. See {@link OptionsBuilder}. @@ -1762,7 +1823,8 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the project is blank (null, empty or whitespace) or the script is null * @see #triggerAdhocScript(String, String, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean, long, TimeUnit) - * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)}, this method will be + * removed in version 10 of this library */ public RundeckExecution triggerAdhocScript(String project, InputStream script, Properties options, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing) throws RundeckApiException, @@ -1786,7 +1848,8 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the project is blank (null, empty or whitespace) or the script is null * @see #triggerAdhocScript(String, String, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean, long, TimeUnit) - * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)}, this method will be + * removed in version 10 of this library */ public RundeckExecution triggerAdhocScript(String project, InputStream script, Properties options, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing, String asUser) throws RundeckApiException, @@ -1811,7 +1874,8 @@ public class RundeckClient implements Serializable { * @throws IllegalArgumentException if the project is blank (null, empty or whitespace) or the script is null * @see #triggerAdhocScript(String, String, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean, long, TimeUnit) - * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)} + * @deprecated use {@link #triggerAdhocScript(RunAdhocScript)}, this method will be + * removed in version 10 of this library */ public RundeckExecution triggerAdhocScript(String project, InputStream script, String argString, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing, String asUser) throws RundeckApiException, @@ -1830,12 +1894,7 @@ public class RundeckClient implements Serializable { * Trigger the execution of an ad-hoc script, and return immediately (without waiting the end of the execution). The * script will be dispatched to nodes, accordingly to the nodeFilters parameter. * - * @param project name of the project - mandatory - * @param script inputStream for reading the script to be executed - mandatory - * @param options of the script - optional. See {@link OptionsBuilder}. - * @param nodeFilters for selecting nodes on which the command will be executed. See {@link NodeFiltersBuilder} - * @param nodeThreadcount thread count to use (for parallelizing when running on multiple nodes) - optional - * @param nodeKeepgoing if true, continue executing on other nodes even if some fail - optional + * @param script the RunAdhocScript, see {@link RunAdhocScriptBuilder} * @return a {@link 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) * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) @@ -1844,21 +1903,21 @@ public class RundeckClient implements Serializable { * @see #triggerAdhocScript(String, String, Properties, Properties, Integer, Boolean) * @see #runAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean, long, TimeUnit) */ - public RundeckExecution triggerAdhocScript(RunAdhocScript adhocScript) throws RundeckApiException, + public RundeckExecution triggerAdhocScript(RunAdhocScript script) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { - AssertUtil.notBlank(adhocScript.getProject(), "project is mandatory to trigger an ad-hoc script !"); - AssertUtil.notNull(adhocScript.getScript(), "script is mandatory to trigger an ad-hoc script !"); - ApiPathBuilder apiPath = new ApiPathBuilder("/run/script").param("project", adhocScript.getProject()) + AssertUtil.notBlank(script.getProject(), "project is mandatory to trigger an ad-hoc script !"); + AssertUtil.notNull(script.getScript(), "script is mandatory to trigger an ad-hoc script !"); + ApiPathBuilder apiPath = new ApiPathBuilder("/run/script").param("project", script.getProject()) .attach("scriptFile", - adhocScript.getScript()) - .param("argString",adhocScript.getArgString()) + script.getScript()) + .param("argString",script.getArgString()) .param("nodeThreadcount", - adhocScript.getNodeThreadcount()) + script.getNodeThreadcount()) .param("nodeKeepgoing", - adhocScript.getNodeKeepgoing()) - .nodeFilters(adhocScript.getNodeFilters()); - if(null!=adhocScript.getAsUser()) { - apiPath.param("asUser", adhocScript.getAsUser()); + script.getNodeKeepgoing()) + .nodeFilters(script.getNodeFilters()); + if(null!=script.getAsUser()) { + apiPath.param("asUser", script.getAsUser()); } RundeckExecution execution = new ApiCall(this).post(apiPath, new ExecutionParser("result/execution")); // the first call just returns the ID of the execution, so we need another call to get a "real" execution @@ -1869,7 +1928,7 @@ public class RundeckClient implements Serializable { * Run an ad-hoc script, 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 script will not be dispatched to nodes, but be executed on the RunDeck server. - * + * * @param project name of the project - mandatory * @param scriptFilename filename of the script to be executed - mandatory * @return a {@link RundeckExecution} instance for the (finished/aborted) execution - won't be null @@ -1880,6 +1939,8 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #runAdhocScript(String, String, Properties, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocScript(String, String) + * @deprecated use {@link #runAdhocScript(RunAdhocScript)}, this method will be + * removed in version 10 of this library */ public RundeckExecution runAdhocScript(String project, String scriptFilename) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException, IOException { @@ -1891,7 +1952,7 @@ public class RundeckClient implements Serializable { * server at regular interval (configured by the poolingInterval/poolingUnit couple) to know if the execution is * finished (or aborted) or is still running. The script will not be dispatched to nodes, but be executed on the * RunDeck server. - * + * * @param project name of the project - mandatory * @param scriptFilename filename of the script to be executed - mandatory * @param poolingInterval for checking the status of the execution. Must be > 0. @@ -1904,6 +1965,8 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #runAdhocScript(String, String, Properties, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocScript(String, String) + * @deprecated use {@link #runAdhocScript(RunAdhocScript, long, java.util.concurrent.TimeUnit)}, this method will be + * removed in version 10 of this library */ public RundeckExecution runAdhocScript(String project, String scriptFilename, long poolingInterval, TimeUnit poolingUnit) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, @@ -1915,7 +1978,7 @@ public class RundeckClient implements Serializable { * Run an ad-hoc script, 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 script will not be dispatched to nodes, but be executed on the RunDeck server. - * + * * @param project name of the project - mandatory * @param scriptFilename filename of the script to be executed - mandatory * @param options of the script - optional. See {@link OptionsBuilder}. @@ -1927,6 +1990,8 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #runAdhocScript(String, String, Properties, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocScript(String, String, Properties) + * @deprecated use {@link #runAdhocScript(RunAdhocScript)}, this method will be + * removed in version 10 of this library */ public RundeckExecution runAdhocScript(String project, String scriptFilename, Properties options) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException, @@ -1939,7 +2004,7 @@ public class RundeckClient implements Serializable { * server at regular interval (configured by the poolingInterval/poolingUnit couple) to know if the execution is * finished (or aborted) or is still running. The script will not be dispatched to nodes, but be executed on the * RunDeck server. - * + * * @param project name of the project - mandatory * @param scriptFilename filename of the script to be executed - mandatory * @param options of the script - optional. See {@link OptionsBuilder}. @@ -1953,6 +2018,8 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #runAdhocScript(String, String, Properties, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocScript(String, String, Properties) + * @deprecated use {@link #runAdhocScript(RunAdhocScript, long, java.util.concurrent.TimeUnit)}, this method will be + * removed in version 10 of this library */ public RundeckExecution runAdhocScript(String project, String scriptFilename, Properties options, long poolingInterval, TimeUnit poolingUnit) throws RundeckApiException, RundeckApiLoginException, @@ -1964,7 +2031,7 @@ public class RundeckClient implements Serializable { * Run an ad-hoc script, 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 script will be dispatched to nodes, accordingly to the nodeFilters parameter. - * + * * @param project name of the project - mandatory * @param scriptFilename filename of the script to be executed - mandatory * @param options of the script - optional. See {@link OptionsBuilder}. @@ -1977,6 +2044,8 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #runAdhocScript(String, String, Properties, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocScript(String, String, Properties, Properties) + * @deprecated use {@link #runAdhocScript(RunAdhocScript)}, this method will be + * removed in version 10 of this library */ public RundeckExecution runAdhocScript(String project, String scriptFilename, Properties options, Properties nodeFilters) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, @@ -1989,7 +2058,7 @@ public class RundeckClient implements Serializable { * server at regular interval (configured by the poolingInterval/poolingUnit couple) to know if the execution is * finished (or aborted) or is still running. The script will be dispatched to nodes, accordingly to the nodeFilters * parameter. - * + * * @param project name of the project - mandatory * @param scriptFilename filename of the script to be executed - mandatory * @param options of the script - optional. See {@link OptionsBuilder}. @@ -2004,6 +2073,8 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #runAdhocScript(String, String, Properties, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocScript(String, String, Properties, Properties) + * @deprecated use {@link #runAdhocScript(RunAdhocScript, long, java.util.concurrent.TimeUnit)}, this method will be + * removed in version 10 of this library */ public RundeckExecution runAdhocScript(String project, String scriptFilename, Properties options, Properties nodeFilters, long poolingInterval, TimeUnit poolingUnit) throws RundeckApiException, @@ -2015,7 +2086,7 @@ public class RundeckClient implements Serializable { * Run an ad-hoc script, 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 script will be dispatched to nodes, accordingly to the nodeFilters parameter. - * + * * @param project name of the project - mandatory * @param scriptFilename filename of the script to be executed - mandatory * @param options of the script - optional. See {@link OptionsBuilder}. @@ -2030,6 +2101,8 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #runAdhocScript(String, String, Properties, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocScript(String, String, Properties, Properties, Integer, Boolean) + * @deprecated use {@link #runAdhocScript(RunAdhocScript)}, this method will be + * removed in version 10 of this library */ public RundeckExecution runAdhocScript(String project, String scriptFilename, Properties options, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing) throws RundeckApiException, @@ -2049,7 +2122,7 @@ public class RundeckClient implements Serializable { * server at regular interval (configured by the poolingInterval/poolingUnit couple) to know if the execution is * finished (or aborted) or is still running. The script will be dispatched to nodes, accordingly to the nodeFilters * parameter. - * + * * @param project name of the project - mandatory * @param scriptFilename filename of the script to be executed - mandatory * @param options of the script - optional. See {@link OptionsBuilder}. @@ -2066,6 +2139,9 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #runAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocScript(String, String, Properties, Properties, Integer, Boolean) + * + * @deprecated use {@link #runAdhocScript(RunAdhocScript, long, java.util.concurrent.TimeUnit)}, this method will be + * removed in version 10 of this library */ public RundeckExecution runAdhocScript(String project, String scriptFilename, Properties options, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing, long poolingInterval, @@ -2075,14 +2151,16 @@ public class RundeckClient implements Serializable { FileInputStream stream = null; try { stream = FileUtils.openInputStream(new File(scriptFilename)); - return runAdhocScript(project, - stream, - options, - nodeFilters, - nodeThreadcount, - nodeKeepgoing, - poolingInterval, - poolingUnit); + return runAdhocScript(RunAdhocScriptBuilder.builder() + .setProject(project) + .setScript(stream) + .setNodeFilters(nodeFilters) + .setArgString(ParametersUtil.generateArgString(options)) + .setNodeThreadcount(nodeThreadcount) + .setNodeKeepgoing(nodeKeepgoing) + .create(), + poolingInterval, + poolingUnit); } finally { IOUtils.closeQuietly(stream); } @@ -2092,7 +2170,7 @@ public class RundeckClient implements Serializable { * Run an ad-hoc script, 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 script will not be dispatched to nodes, but be executed on the RunDeck server. - * + * * @param project name of the project - mandatory * @param script inputStream for reading the script to be executed - mandatory * @return a {@link RundeckExecution} instance for the (finished/aborted) execution - won't be null @@ -2103,6 +2181,8 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #runAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocScript(String, InputStream) + * @deprecated use {@link #runAdhocScript(RunAdhocScript)}, this method will be + * removed in version 10 of this library */ public RundeckExecution runAdhocScript(String project, InputStream script) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException, IOException { @@ -2114,7 +2194,7 @@ public class RundeckClient implements Serializable { * server at regular interval (configured by the poolingInterval/poolingUnit couple) to know if the execution is * finished (or aborted) or is still running. The script will not be dispatched to nodes, but be executed on the * RunDeck server. - * + * * @param project name of the project - mandatory * @param script inputStream for reading the script to be executed - mandatory * @param poolingInterval for checking the status of the execution. Must be > 0. @@ -2127,6 +2207,8 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #runAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocScript(String, InputStream) + * @deprecated use {@link #runAdhocScript(RunAdhocScript, long, java.util.concurrent.TimeUnit)}, this method will be + * removed in version 10 of this library */ public RundeckExecution runAdhocScript(String project, InputStream script, long poolingInterval, TimeUnit poolingUnit) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, @@ -2138,7 +2220,7 @@ public class RundeckClient implements Serializable { * Run an ad-hoc script, 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 script will not be dispatched to nodes, but be executed on the RunDeck server. - * + * * @param project name of the project - mandatory * @param script inputStream for reading the script to be executed - mandatory * @param options of the script - optional. See {@link OptionsBuilder}. @@ -2150,6 +2232,8 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #runAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocScript(String, InputStream, Properties) + * @deprecated use {@link #runAdhocScript(RunAdhocScript)}, this method will be + * removed in version 10 of this library */ public RundeckExecution runAdhocScript(String project, InputStream script, Properties options) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException, @@ -2162,7 +2246,7 @@ public class RundeckClient implements Serializable { * server at regular interval (configured by the poolingInterval/poolingUnit couple) to know if the execution is * finished (or aborted) or is still running. The script will not be dispatched to nodes, but be executed on the * RunDeck server. - * + * * @param project name of the project - mandatory * @param script inputStream for reading the script to be executed - mandatory * @param options of the script - optional. See {@link OptionsBuilder}. @@ -2176,6 +2260,8 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #runAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocScript(String, InputStream, Properties) + * @deprecated use {@link #runAdhocScript(RunAdhocScript, long, java.util.concurrent.TimeUnit)}, this method will be + * removed in version 10 of this library */ public RundeckExecution runAdhocScript(String project, InputStream script, Properties options, long poolingInterval, TimeUnit poolingUnit) throws RundeckApiException, RundeckApiLoginException, @@ -2187,7 +2273,7 @@ public class RundeckClient implements Serializable { * Run an ad-hoc script, 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 script will be dispatched to nodes, accordingly to the nodeFilters parameter. - * + * * @param project name of the project - mandatory * @param script inputStream for reading the script to be executed - mandatory * @param options of the script - optional. See {@link OptionsBuilder}. @@ -2200,6 +2286,8 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #runAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocScript(String, InputStream, Properties, Properties) + * @deprecated use {@link #runAdhocScript(RunAdhocScript)}, this method will be + * removed in version 10 of this library */ public RundeckExecution runAdhocScript(String project, InputStream script, Properties options, Properties nodeFilters) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, @@ -2212,7 +2300,7 @@ public class RundeckClient implements Serializable { * server at regular interval (configured by the poolingInterval/poolingUnit couple) to know if the execution is * finished (or aborted) or is still running. The script will be dispatched to nodes, accordingly to the nodeFilters * parameter. - * + * * @param project name of the project - mandatory * @param script inputStream for reading the script to be executed - mandatory * @param options of the script - optional. See {@link OptionsBuilder}. @@ -2227,6 +2315,8 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #runAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocScript(String, InputStream, Properties, Properties) + * @deprecated use {@link #runAdhocScript(RunAdhocScript, long, java.util.concurrent.TimeUnit)}, this method will be + * removed in version 10 of this library */ public RundeckExecution runAdhocScript(String project, InputStream script, Properties options, Properties nodeFilters, long poolingInterval, TimeUnit poolingUnit) throws RundeckApiException, @@ -2238,7 +2328,7 @@ public class RundeckClient implements Serializable { * Run an ad-hoc script, 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 script will be dispatched to nodes, accordingly to the nodeFilters parameter. - * + * * @param project name of the project - mandatory * @param script inputStream for reading the script to be executed - mandatory * @param options of the script - optional. See {@link OptionsBuilder}. @@ -2253,6 +2343,8 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #runAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean) + * @deprecated use {@link #runAdhocScript(RunAdhocScript)}, this method will be + * removed in version 10 of this library */ public RundeckExecution runAdhocScript(String project, InputStream script, Properties options, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing) throws RundeckApiException, @@ -2269,33 +2361,26 @@ public class RundeckClient implements Serializable { /** * Run an ad-hoc script, 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 script will be dispatched to nodes, accordingly to the nodeFilters - * parameter. - * - * @param project name of the project - mandatory - * @param script inputStream for reading the script to be executed - mandatory - * @param options of the script - optional. See {@link OptionsBuilder}. - * @param nodeFilters for selecting nodes on which the script will be executed. See {@link NodeFiltersBuilder} - * @param nodeThreadcount thread count to use (for parallelizing when running on multiple nodes) - optional - * @param nodeKeepgoing if true, continue executing on other nodes even if some fail - optional - * @param poolingInterval for checking the status of the execution. Must be > 0. - * @param poolingUnit unit (seconds, milli-seconds, ...) of the interval. Default to seconds. + * server at regular interval (every 5 seconds) to know if the execution is finished (or aborted) or is still + * running. The script will be dispatched to nodes, accordingly to the nodeFilters parameter. + * + * @param script the RunAdhocScript, see {@link RunAdhocScriptBuilder} * @return a {@link 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) * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) * @throws RundeckApiTokenException if the token is invalid (in case of token-based authentication) * @throws IllegalArgumentException if the project is blank (null, empty or whitespace) or the script is null * @throws IOException if we failed to read the file - * @see #runAdhocScript(String, String, Properties, Properties, Integer, Boolean, long, TimeUnit) - * @see #triggerAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean) + * @see #runAdhocScript(RunAdhocScript, long, java.util.concurrent.TimeUnit) + * @see #triggerAdhocScript(RunAdhocScript) */ - public RundeckExecution runAdhocScript(String project, InputStream script, Properties options, - Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing, long poolingInterval, - TimeUnit poolingUnit) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, - IllegalArgumentException { - return runAdhocScript(project, script, options, nodeFilters, nodeThreadcount, nodeKeepgoing, null, poolingInterval, poolingUnit); + public RundeckExecution runAdhocScript(RunAdhocScript script) throws RundeckApiException, + RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException, IOException { + return runAdhocScript(script, + DEFAULT_POOLING_INTERVAL, + DEFAULT_POOLING_UNIT); } + /** * Run an ad-hoc script, 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 @@ -2318,11 +2403,78 @@ public class RundeckClient implements Serializable { * @throws IOException if we failed to read the file * @see #runAdhocScript(String, String, Properties, Properties, Integer, Boolean, long, TimeUnit) * @see #triggerAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean) + * @deprecated use {@link #runAdhocScript(RunAdhocScript, long, java.util.concurrent.TimeUnit)}, this method will be + * removed in version 10 of this library + */ + public RundeckExecution runAdhocScript(String project, InputStream script, Properties options, + Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing, long poolingInterval, + TimeUnit poolingUnit) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, + IllegalArgumentException { + return runAdhocScript(project, script, options, nodeFilters, nodeThreadcount, nodeKeepgoing, null, poolingInterval, poolingUnit); + } + + /** + * Run an ad-hoc script, 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 script will be dispatched to nodes, accordingly to the nodeFilters + * parameter. + * + * @param project name of the project - mandatory + * @param script inputStream for reading the script to be executed - mandatory + * @param options of the script - optional. See {@link OptionsBuilder}. + * @param nodeFilters for selecting nodes on which the script will be executed. See {@link NodeFiltersBuilder} + * @param nodeThreadcount thread count to use (for parallelizing when running on multiple nodes) - optional + * @param nodeKeepgoing if true, continue executing on other nodes even if some fail - optional + * @param poolingInterval for checking the status of the execution. Must be > 0. + * @param poolingUnit unit (seconds, milli-seconds, ...) of the interval. Default to seconds. + * + * @return a {@link 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) + * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) + * @throws RundeckApiTokenException if the token is invalid (in case of token-based authentication) + * @throws IllegalArgumentException if the project is blank (null, empty or whitespace) or the script is null + * @throws IOException if we failed to read the file + * @see #runAdhocScript(String, String, Properties, Properties, Integer, Boolean, long, TimeUnit) + * @see #triggerAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean) + * @deprecated use {@link #runAdhocScript(RunAdhocScript, long, java.util.concurrent.TimeUnit)}, this method will be + * removed in version 10 of this library */ public RundeckExecution runAdhocScript(String project, InputStream script, Properties options, Properties nodeFilters, Integer nodeThreadcount, Boolean nodeKeepgoing, String asUser, long poolingInterval, TimeUnit poolingUnit) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException { + return runAdhocScript(RunAdhocScriptBuilder.builder() + .setProject(project) + .setScript(script) + .setNodeFilters(nodeFilters) + .setArgString(ParametersUtil.generateArgString(options)) + .setNodeThreadcount(nodeThreadcount) + .setNodeKeepgoing(nodeKeepgoing) + .setAsUser(asUser) + .create(), poolingInterval, poolingUnit); + } + /** + * Run an ad-hoc script, 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 script will be dispatched to nodes, accordingly to the nodeFilters + * parameter. + * + * @param script the RunAdhocScript, see {@link RunAdhocScriptBuilder} + * @param poolingInterval for checking the status of the execution. Must be > 0. + * @param poolingUnit unit (seconds, milli-seconds, ...) of the interval. Default to seconds. + * @return a {@link 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) + * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) + * @throws RundeckApiTokenException if the token is invalid (in case of token-based authentication) + * @throws IllegalArgumentException if the project is blank (null, empty or whitespace) or the script is null + * @throws IOException if we failed to read the file + * @see #runAdhocScript(String, String, Properties, Properties, Integer, Boolean, long, TimeUnit) + * @see #triggerAdhocScript(String, InputStream, Properties, Properties, Integer, Boolean) + */ + public RundeckExecution runAdhocScript(final RunAdhocScript script, long poolingInterval, + TimeUnit poolingUnit) throws RundeckApiException, RundeckApiLoginException, RundeckApiTokenException, + IllegalArgumentException { if (poolingInterval <= 0) { poolingInterval = DEFAULT_POOLING_INTERVAL; poolingUnit = DEFAULT_POOLING_UNIT; @@ -2331,12 +2483,7 @@ public class RundeckClient implements Serializable { poolingUnit = DEFAULT_POOLING_UNIT; } - RundeckExecution execution = triggerAdhocScript(project, - script, - options, - nodeFilters, - nodeThreadcount, - nodeKeepgoing,asUser); + RundeckExecution execution = triggerAdhocScript(script); while (ExecutionStatus.RUNNING.equals(execution.getStatus())) { try { Thread.sleep(poolingUnit.toMillis(poolingInterval)); @@ -2354,7 +2501,7 @@ public class RundeckClient implements Serializable { /** * Get all running executions (for all projects) - * + * * @return a {@link List} of {@link RundeckExecution} : might be empty, but won't be null * @throws RundeckApiException in case of error when calling the API * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) @@ -2372,7 +2519,7 @@ public class RundeckClient implements Serializable { /** * Get the running executions for the given project - * + * * @param project name of the project - mandatory * @return a {@link List} of {@link 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) @@ -2391,7 +2538,7 @@ public class RundeckClient implements Serializable { /** * Get the executions of the given job - * + * * @param jobId identifier of the job - mandatory * @return a {@link List} of {@link 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) @@ -2407,7 +2554,7 @@ public class RundeckClient implements Serializable { /** * Get the executions of the given job - * + * * @param jobId identifier of the job - mandatory * @param status of the executions, see {@link ExecutionStatus} - optional (null for all) * @return a {@link List} of {@link RundeckExecution} : might be empty, but won't be null @@ -2426,7 +2573,7 @@ public class RundeckClient implements Serializable { /** * Get the executions of the given job - * + * * @param jobId identifier of the job - mandatory * @param status of the executions, see {@link ExecutionStatus} - optional (null for all) * @return a {@link List} of {@link RundeckExecution} : might be empty, but won't be null @@ -2443,7 +2590,7 @@ public class RundeckClient implements Serializable { /** * Get the executions of the given job - * + * * @param jobId identifier of the job - mandatory * @param status of the executions, see {@link ExecutionStatus} - optional (null for all) * @param max number of results to return - optional (null for all) @@ -2466,7 +2613,7 @@ public class RundeckClient implements Serializable { /** * Get the executions of the given job - * + * * @param jobId identifier of the job - mandatory * @param status of the executions, see {@link ExecutionStatus} - optional (null for all) * @param max number of results to return - optional (null for all) @@ -2518,7 +2665,7 @@ public class RundeckClient implements Serializable { /** * Get a single execution, identified by the given ID - * + * * @param executionId identifier of the execution - mandatory * @return a {@link RundeckExecution} instance - won't be null * @throws RundeckApiException in case of error when calling the API (non-existent execution with this ID) @@ -2535,7 +2682,7 @@ public class RundeckClient implements Serializable { /** * Abort an execution (identified by the given ID). The execution should be running... - * + * * @param executionId identifier of the execution - mandatory * @return a {@link RundeckAbort} instance - won't be null * @throws RundeckApiException in case of error when calling the API (non-existent execution with this ID) @@ -2574,7 +2721,7 @@ public class RundeckClient implements Serializable { /** * Get the (events) history for the given project - * + * * @param project name of the project - mandatory * @return a {@link RundeckHistory} instance - won't be null * @throws RundeckApiException in case of error when calling the API (non-existent project with this name) @@ -2590,7 +2737,7 @@ public class RundeckClient implements Serializable { /** * Get the (events) history for the given project - * + * * @param project name of the project - mandatory * @param max number of results to return - optional (default to 20) * @param offset the 0-indexed offset for the first result to return - optional (default to O) @@ -2608,7 +2755,7 @@ public class RundeckClient implements Serializable { /** * Get the (events) history for the given project - * + * * @param project name of the project - mandatory * @param jobId include only events matching the given job ID - optional * @param reportId include only events matching the given report ID - optional @@ -2627,7 +2774,7 @@ public class RundeckClient implements Serializable { /** * Get the (events) history for the given project - * + * * @param project name of the project - mandatory * @param jobId include only events matching the given job ID - optional * @param reportId include only events matching the given report ID - optional @@ -2648,7 +2795,7 @@ public class RundeckClient implements Serializable { /** * Get the (events) history for the given project - * + * * @param project name of the project - mandatory * @param recent include only events matching the given period of time. Format : "XY", where X is an integer, and Y * is one of : "h" (hour), "d" (day), "w" (week), "m" (month), "y" (year). Example : "2w" (= last 2 @@ -2667,7 +2814,7 @@ public class RundeckClient implements Serializable { /** * Get the (events) history for the given project - * + * * @param project name of the project - mandatory * @param recent include only events matching the given period of time. Format : "XY", where X is an integer, and Y * is one of : "h" (hour), "d" (day), "w" (week), "m" (month), "y" (year). Example : "2w" (= last 2 @@ -2688,7 +2835,7 @@ public class RundeckClient implements Serializable { /** * Get the (events) history for the given project - * + * * @param project name of the project - mandatory * @param begin date for the earlier events to retrieve - optional * @param end date for the latest events to retrieve - optional @@ -2706,7 +2853,7 @@ public class RundeckClient implements Serializable { /** * Get the (events) history for the given project - * + * * @param project name of the project - mandatory * @param begin date for the earlier events to retrieve - optional * @param end date for the latest events to retrieve - optional @@ -2726,7 +2873,7 @@ public class RundeckClient implements Serializable { /** * Get the (events) history for the given project - * + * * @param project name of the project - mandatory * @param jobId include only events matching the given job ID - optional * @param reportId include only events matching the given report ID - optional @@ -2813,7 +2960,7 @@ public class RundeckClient implements Serializable { /** * List all nodes (for all projects) - * + * * @return a {@link List} of {@link RundeckNode} : might be empty, but won't be null * @throws RundeckApiException in case of error when calling the API * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) @@ -2829,7 +2976,7 @@ public class RundeckClient implements Serializable { /** * List all nodes that belongs to the given project - * + * * @param project name of the project - mandatory * @return a {@link List} of {@link 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) @@ -2845,7 +2992,7 @@ public class RundeckClient implements Serializable { /** * List nodes that belongs to the given project - * + * * @param project name of the project - mandatory * @param nodeFilters for filtering the nodes - optional. See {@link NodeFiltersBuilder} * @return a {@link List} of {@link RundeckNode} : might be empty, but won't be null @@ -2864,7 +3011,7 @@ public class RundeckClient implements Serializable { /** * Get the definition of a single node - * + * * @param name of the node - mandatory * @param project name of the project - mandatory * @return a {@link RundeckNode} instance - won't be null @@ -2883,7 +3030,7 @@ public class RundeckClient implements Serializable { /** * Get the output of a job execution - * + * * @param id of the execution - mandatory * @return an {@link InputStream} instance, not linked to any network resources - won't be null * @throws RundeckApiException in case of error when calling the API (non-existent name or project with this name) @@ -2899,7 +3046,7 @@ public class RundeckClient implements Serializable { /** * Get the html page of the user's profile - * + * * @param username - mandatory * @return an {@link InputStream} instance, not linked to any network resources - won't be null * @throws RundeckApiException in case of error when calling the API (non-existent name or project with this name) @@ -2916,7 +3063,7 @@ public class RundeckClient implements Serializable { /** * Generate a new token and get the result page (which is the html page of the user's profile) - * + * * @param username - mandatory * @return an {@link InputStream} instance, not linked to any network resources - won't be null * @throws RundeckApiException in case of error when calling the API (non-existent name or project with this name) @@ -2930,10 +3077,10 @@ public class RundeckClient implements Serializable { return new ApiCall(this).getNonApi(new ApiPathBuilder("/user/generateApiToken?login=", username)); } - + /** * Get the execution output of the given job - * + * * @param executionId identifier of the execution - mandatory * @param offset byte offset to read from in the file. 0 indicates the beginning. * @param lastlines nnumber of lines to retrieve from the end of the available output. If specified it will override the offset value and return only the specified number of lines at the end of the log. @@ -2955,10 +3102,10 @@ public class RundeckClient implements Serializable { new OutputParser("result/output", createOutputEntryParser())); } - + /** * Get the execution output of the given job - * + * * @param jobId identifier of the job - mandatory * @param offset byte offset to read from in the file. 0 indicates the beginning. * @param lastmod epoch datestamp in milliseconds, return results only if modification changed since the specified date OR if more data is available at the given offset @@ -2993,7 +3140,7 @@ public class RundeckClient implements Serializable { /** * Get system informations about the RunDeck server - * + * * @return a {@link RundeckSystemInfo} instance - won't be null * @throws RundeckApiException in case of error when calling the API * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) From fef0af5e1e13df890b401452497dc3b044793640 Mon Sep 17 00:00:00 2001 From: Greg Schueler Date: Tue, 9 Jul 2013 12:15:43 -0700 Subject: [PATCH 3/3] Update javadoc. utility methods for adhoc script read from file --- .../rundeck/api/RunAdhocScriptBuilder.java | 50 ++++++--- .../java/org/rundeck/api/RundeckClient.java | 102 ++++++++++++++++-- 2 files changed, 130 insertions(+), 22 deletions(-) diff --git a/src/main/java/org/rundeck/api/RunAdhocScriptBuilder.java b/src/main/java/org/rundeck/api/RunAdhocScriptBuilder.java index 39ba5fc..2cf8e01 100644 --- a/src/main/java/org/rundeck/api/RunAdhocScriptBuilder.java +++ b/src/main/java/org/rundeck/api/RunAdhocScriptBuilder.java @@ -4,58 +4,84 @@ import java.io.InputStream; import java.util.Properties; /** - * A builder to create a {@link RunAdhocScript}, use the {@link #builder()} to create a builder, then {@link #create()} to - * build an RunAdhocScript + * A builder to create a {@link RunAdhocScript}, use the {@link #builder()} to create a builder, then {@link #create()} + * to build an RunAdhocScript */ public class RunAdhocScriptBuilder { private DefaultRunAdhocScript script; - public RunAdhocScriptBuilder() { + private RunAdhocScriptBuilder() { script = new DefaultRunAdhocScript(); } + public RunAdhocScriptBuilder(final RunAdhocScript oldScript) { + script = new DefaultRunAdhocScript(); + setAsUser(oldScript.getAsUser()); + setArgString(oldScript.getArgString()); + setProject(oldScript.getProject()); + setScript(oldScript.getScript()); + setNodeFilters(oldScript.getNodeFilters()); + setNodeKeepgoing(oldScript.getNodeKeepgoing()); + setNodeThreadcount(oldScript.getNodeThreadcount()); + } + + /** + * Create a new builder + * + * @return + */ public static RunAdhocScriptBuilder builder() { return new RunAdhocScriptBuilder(); } - public RunAdhocScriptBuilder setProject(String project) { - script.setProject(project); + /** + * Create a builder initialized with an existing {@link RunAdhocScript} + * + * @param script + * + * @return this builder + */ + public static RunAdhocScriptBuilder builder(final RunAdhocScript script) { + return new RunAdhocScriptBuilder(script); + } + public RunAdhocScriptBuilder setProject(final String project) { + script.setProject(project); return this; } - public RunAdhocScriptBuilder setScript(InputStream stream) { + public RunAdhocScriptBuilder setScript(final InputStream stream) { script.setScript(stream); return this; } - public RunAdhocScriptBuilder setArgString(String argString) { + public RunAdhocScriptBuilder setArgString(final String argString) { script.setArgString(argString); return this; } - public RunAdhocScriptBuilder setNodeFilters(Properties nodeFilters) { + public RunAdhocScriptBuilder setNodeFilters(final Properties nodeFilters) { script.setNodeFilters(nodeFilters); return this; } - public RunAdhocScriptBuilder setNodeThreadcount(Integer nodeThreadcount) { + public RunAdhocScriptBuilder setNodeThreadcount(final Integer nodeThreadcount) { script.setNodeThreadcount(nodeThreadcount); return this; } - public RunAdhocScriptBuilder setNodeKeepgoing(Boolean nodeKeepgoing) { + public RunAdhocScriptBuilder setNodeKeepgoing(final Boolean nodeKeepgoing) { script.setNodeKeepgoing(nodeKeepgoing); return this; } - public RunAdhocScriptBuilder setAsUser(String asUser) { + public RunAdhocScriptBuilder setAsUser(final String asUser) { script.setAsUser(asUser); return this; } public RunAdhocScript create() { - DefaultRunAdhocScript built = script; + final DefaultRunAdhocScript built = script; script = new DefaultRunAdhocScript(); return built; } diff --git a/src/main/java/org/rundeck/api/RundeckClient.java b/src/main/java/org/rundeck/api/RundeckClient.java index ee36331..f417017 100644 --- a/src/main/java/org/rundeck/api/RundeckClient.java +++ b/src/main/java/org/rundeck/api/RundeckClient.java @@ -41,13 +41,27 @@ import java.util.concurrent.TimeUnit; /** * Main entry point to talk to a RunDeck instance. - *
- * Deprecation Warning: The "triggerAdhocScript" methods which take multiple arguments are deprecated in - * favor of {@link #triggerAdhocScript(RunAdhocScript)}. The methods will be removed in version 10 of this library. - *
+ *

+ * Deprecation Warning: These methods which take multiple arguments are deprecated in + * favor of single argument versions, and associated Builder classes to generate them. + * These methods will be removed in version 10 of this library: + *

    + *
  • triggerAdhocScript(...), use {@link #triggerAdhocScript(RunAdhocScript)} and {@link RunAdhocScriptBuilder}
    • + *
  • runAdhocScript(...), use {@link #runAdhocScript(RunAdhocScript)} and {@link RunAdhocScriptBuilder}
    • + *
  • triggerAdhocCommand(...), use {@link #triggerAdhocCommand(RunAdhocCommand)} and {@link + * RunAdhocCommandBuilder}
    • + *
  • runAdhocCommand(...), use {@link #runAdhocCommand(RunAdhocCommand)} and {@link + * RunAdhocCommandBuilder}
    • + *
  • triggerJob(...), use {@link #triggerJob(RunJob)} and {@link + * RunJobBuilder}
    • + *
  • runJob(...), use {@link #runJob(RunJob)} and {@link + * RunJobBuilder}
    • + *
+ *

+ *

* You have 2 methods for authentication : login-based or token-based. If you want to use the first, you need to provide * both a "login" and a "password". Otherwise, just provide a "token" (also called "auth-token"). See the RunDeck - * documentation for generating such a token.
+ * documentation for generating such a token.

*
* Usage :
* @@ -1048,7 +1062,7 @@ public class RundeckClient implements Serializable { * 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. * - * @param jobRun the RunJob, see {@link RunJobBuilder} + * @param runJob the RunJob, see {@link RunJobBuilder} * * @return a {@link RundeckExecution} instance for the (finished/aborted) execution - won't be null * @@ -1703,7 +1717,7 @@ public class RundeckClient implements Serializable { * * @param project name of the project - mandatory * @param scriptFilename filename of the script to be executed - mandatory - * @param options of the script - optional. See {@link OptionsBuilder}. + * @param argString arguments of the script - optional. * @param nodeFilters for selecting nodes on which the command will be executed. See {@link NodeFiltersBuilder} * @param nodeThreadcount thread count to use (for parallelizing when running on multiple nodes) - optional * @param nodeKeepgoing if true, continue executing on other nodes even if some fail - optional @@ -1863,7 +1877,7 @@ public class RundeckClient implements Serializable { * * @param project name of the project - mandatory * @param script inputStream for reading the script to be executed - mandatory - * @param options of the script - optional. See {@link OptionsBuilder}. + * @param argString arguments of the script - optional. * @param nodeFilters for selecting nodes on which the command will be executed. See {@link NodeFiltersBuilder} * @param nodeThreadcount thread count to use (for parallelizing when running on multiple nodes) - optional * @param nodeKeepgoing if true, continue executing on other nodes even if some fail - optional @@ -1890,6 +1904,38 @@ public class RundeckClient implements Serializable { .setAsUser(asUser) .create()); } + + /** + * Trigger the execution of an ad-hoc script read from a file, and return immediately (without waiting the end of + * the execution). The script will be dispatched to nodes, accordingly to the nodeFilters parameter. + * + * @param script the RunAdhocScript, see {@link RunAdhocScriptBuilder} + * @param scriptFilename a file to read as the input script stream + * + * @return a {@link 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) + * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) + * @throws RundeckApiTokenException if the token is invalid (in case of token-based authentication) + * @throws IllegalArgumentException if the project is blank (null, empty or whitespace) or the script is null + * @throws IOException if an error occurs reading the script file + * @see #triggerAdhocScript(RunAdhocScript) + * @see #runAdhocScript(RunAdhocScript, long, java.util.concurrent.TimeUnit) + */ + public RundeckExecution triggerAdhocScript(final RunAdhocScript script, final String scriptFilename) throws + RundeckApiException, + RundeckApiLoginException, RundeckApiTokenException, IllegalArgumentException, IOException { + AssertUtil.notBlank(scriptFilename, "scriptFilename is mandatory to trigger an ad-hoc script !"); + FileInputStream stream = null; + try { + stream = FileUtils.openInputStream(new File(scriptFilename)); + return triggerAdhocScript(RunAdhocScriptBuilder.builder(script) + .setScript(stream) + .create()); + } finally { + IOUtils.closeQuietly(stream); + } + } /** * Trigger the execution of an ad-hoc script, and return immediately (without waiting the end of the execution). The * script will be dispatched to nodes, accordingly to the nodeFilters parameter. @@ -2454,6 +2500,42 @@ public class RundeckClient implements Serializable { .setAsUser(asUser) .create(), poolingInterval, poolingUnit); } + + /** + * Run an ad-hoc script read from a file, 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 script will be dispatched to nodes, accordingly to + * the nodeFilters parameter. + * + * @param script the RunAdhocScript, see {@link RunAdhocScriptBuilder} + * @param scriptFilename filename of a script to read + * @param poolingInterval for checking the status of the execution. Must be > 0. + * @param poolingUnit unit (seconds, milli-seconds, ...) of the interval. Default to seconds. + * + * @return a {@link 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) + * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) + * @throws RundeckApiTokenException if the token is invalid (in case of token-based authentication) + * @throws IllegalArgumentException if the project is blank (null, empty or whitespace) or the script is null + * @throws IOException if we failed to read the file + * @see #runAdhocScript(RunAdhocScript) + * @see #triggerAdhocScript(RunAdhocScript, String) + */ + public RundeckExecution runAdhocScript(final RunAdhocScript script, final String scriptFilename, + final long poolingInterval, final TimeUnit poolingUnit) throws RundeckApiException, + RundeckApiLoginException, RundeckApiTokenException, + IllegalArgumentException, IOException { + FileInputStream stream = null; + try { + stream = FileUtils.openInputStream(new File(scriptFilename)); + return runAdhocScript(RunAdhocScriptBuilder.builder(script) + .setScript(stream) + .create(), poolingInterval, poolingUnit); + } finally { + IOUtils.closeQuietly(stream); + } + } /** * Run an ad-hoc script, 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 @@ -3031,7 +3113,7 @@ public class RundeckClient implements Serializable { /** * Get the output of a job execution * - * @param id of the execution - mandatory + * @param executionId id of the execution - mandatory * @return an {@link InputStream} instance, not linked to any network resources - won't be null * @throws RundeckApiException in case of error when calling the API (non-existent name or project with this name) * @throws RundeckApiLoginException if the login fails (in case of login-based authentication) @@ -3106,7 +3188,7 @@ public class RundeckClient implements Serializable { /** * Get the execution output of the given job * - * @param jobId identifier of the job - mandatory + * @param executionId identifier of the execution - mandatory * @param offset byte offset to read from in the file. 0 indicates the beginning. * @param lastmod epoch datestamp in milliseconds, return results only if modification changed since the specified date OR if more data is available at the given offset * @param maxlines maximum number of lines to retrieve forward from the specified offset.