GitHub-Mirror/rundeck-api-java-client
2
0
Fork 0
mirror of https://github.com/Fishwaldo/rundeck-api-java-client.git synced 2025-07-07 05:28:21 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update javadoc. utility methods for adhoc script read from file

Browse source
This commit is contained in:
Greg Schueler 2013-07-09 12:15:43 -07:00
parent 5d1ae5fa2c
commit fef0af5e1e
2 changed files with 130 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

50
src/main/java/org/rundeck/api/RunAdhocScriptBuilder.java
View file

@ -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;
}

102
src/main/java/org/rundeck/api/RundeckClient.java
View file

@ -41,13 +41,27 @@ import java.util.concurrent.TimeUnit;
/**
* Main entry point to talk to a RunDeck instance.
* <br>
* <em>Deprecation Warning:</em> 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.
* <br>
* <p>
* <em>Deprecation Warning:</em> 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:
* <ul>
* <li> triggerAdhocScript(...), use {@link #triggerAdhocScript(RunAdhocScript)} and {@link RunAdhocScriptBuilder}</li>
* <li> runAdhocScript(...), use {@link #runAdhocScript(RunAdhocScript)} and {@link RunAdhocScriptBuilder}</li>
* <li> triggerAdhocCommand(...), use {@link #triggerAdhocCommand(RunAdhocCommand)} and {@link
* RunAdhocCommandBuilder}</li>
* <li> runAdhocCommand(...), use {@link #runAdhocCommand(RunAdhocCommand)} and {@link
* RunAdhocCommandBuilder}</li>
* <li> triggerJob(...), use {@link #triggerJob(RunJob)} and {@link
* RunJobBuilder}</li>
* <li> runJob(...), use {@link #runJob(RunJob)} and {@link
* RunJobBuilder}</li>
* </ul>
* </p>
* <p>
* 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.<br>
* documentation for generating such a token.</p>
* <br>
* Usage : <br>
* <code>
@ -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.