com.alanbuttars.commons.cli.request.CommandLineRequestBuilder Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of commons-cli Show documentation
Commons CLI is an API for simplifying the deployment and evaluation of command line processes.
The newest version!
/*
 * Copyright (C) Alan Buttars
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.alanbuttars.commons.cli.request;

import static com.alanbuttars.commons.util.validators.Arguments.verify;
import static com.alanbuttars.commons.util.validators.Arguments.verifyNonEmpty;
import static com.alanbuttars.commons.util.validators.Arguments.verifyNonNegativeNumber;
import static com.alanbuttars.commons.util.validators.Arguments.verifyNonNull;

import java.util.ArrayList;
import java.util.List;

import com.alanbuttars.commons.cli.evaluator.CommandLineEvaluator;
import com.alanbuttars.commons.cli.evaluator.CommandLineEvaluatorExitStatusImpl;
import com.alanbuttars.commons.cli.util.Argument;

/**
 * A builder pattern class which generates a {@link CommandLineRequest}. An explanation of methods:
 *
 * 
 * {@link #withEvaluator(CommandLineEvaluator)}

 * By default, process results are evaluated with a {@link CommandLineEvaluatorExitStatusImpl}, which does nothing more
 * than fail processes which return a non-zero exit code. This behavior can be changed by invoking
 * {@link #withEvaluator(CommandLineEvaluator)} with either an existing or anonymous evaluation function.
 * 
 *
 * 
 * {@link #interruptOnFailure()}

 * By default, processes are not interrupted when a failure is first detected. For example, let us take
 * the request:
 *
 * 
 * new CommandLineRequestBuilder().build("echo ERROR; sleep 5; echo END");
 * 
 *
 * Even if the {@link #evaluator} detects that "ERROR" indicates a failure, by default the process will not be halted
 * until the command completes. This behavior can be circumvented with:
 *
 *  * new CommandLineRequestBuilder().interruptOnFailure().build("echo ERROR; sleep 5; echo END");
 * 
 *
 * 
 *
 * @author Alan Buttars
 *
 */
public class CommandLineRequestBuilder {

	private CommandLineEvaluator evaluator;
	private boolean interruptOnFailure;
	private long interruptAfter;

	/**
	 * Instantiates a new builder with defaults:
	 */
	public CommandLineRequestBuilder() {
		this.evaluator = new CommandLineEvaluatorExitStatusImpl();
		this.interruptOnFailure = false;
		this.interruptAfter = 0;
	}

	/**
	 * Sets the function used to evaluate {@link Process} results.
	 *
	 * @param evaluator
	 *            Non-null evaluation function
	 */
	public CommandLineRequestBuilder withEvaluator(CommandLineEvaluator evaluator) {
		verifyNonNull(evaluator, "Evaluator must be non-null");
		this.evaluator = evaluator;
		return this;
	}

	/**
	 * Indicates that the {@link Process} should be interrupted at the first indication of a failure identifed by the
	 * {@link #evaluator}.
	 */
	public CommandLineRequestBuilder interruptOnFailure() {
		this.interruptOnFailure = true;
		return this;
	}

	/**
	 * The time, in milliseconds, that the {@link Process} should be allowed to run. If the thread runs longer than this
	 * time limit, the thread will be interrupted and {@link CommandLineEvaluator#evaluateException(Exception)} will be
	 * invoked with a {@link InterruptedException}.
	 *
	 * @param milliseconds
	 */
	public CommandLineRequestBuilder interruptAfter(int milliseconds) {
		verifyNonNegativeNumber(milliseconds, "Milliseconds must be non-negative");
		this.interruptAfter = milliseconds;
		return this;
	}

	/**
	 * Builds a {@link CommandLineRequest} with String command.
	 *
	 * @param command
	 *            Non-null and non-blank command line arguments
	 * @return the request
	 */
	public CommandLineRequest build(String command) {
		verifyNonNull(command, "Command must be non-null");
		verifyNonEmpty(command, "Command must be non-empty");

		List arguments = new ArrayList();
		for (String commandPart : command.split(" ")) {
			arguments.add(new Argument(commandPart));
		}
		return build(arguments);
	}

	/**
	 * Builds a {@link CommandLineRequest} with arguments.
	 *
	 * @param arguments
	 *            Non-null and non-empty command line arguments
	 * @return the request
	 */
	public CommandLineRequest build(List arguments) {
		verifyNonNull(arguments, "Arguments must be non-null");
		verify(!arguments.isEmpty(), "Arguments must be non-empty");

		CommandLineRequest request = new CommandLineRequest();
		request.setArguments(arguments);
		request.setEvaluator(evaluator);
		request.setInterruptOnFailure(interruptOnFailure);
		request.setInterruptAfter(interruptAfter);
		return request;
	}

}