001/* 
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 *  contributor license agreements.  See the NOTICE file distributed with
004 *  this work for additional information regarding copyright ownership.
005 *  The ASF licenses this file to You under the Apache License, Version 2.0
006 *  (the "License"); you may not use this file except in compliance with
007 *  the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 *  Unless required by applicable law or agreed to in writing, software
012 *  distributed under the License is distributed on an "AS IS" BASIS,
013 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 *  See the License for the specific language governing permissions and
015 *  limitations under the License.
016 *
017 */
018
019package org.apache.commons.exec.launcher;
020
021import java.io.File;
022import java.io.IOException;
023import java.util.Map;
024
025import org.apache.commons.exec.CommandLine;
026
027/**
028 * Interface to shield the caller from the various platform-dependent
029 * implementations.
030 *
031 * @version $Id: CommandLauncher.java 1636056 2014-11-01 21:12:52Z ggregory $
032 */
033public interface CommandLauncher {
034
035    /**
036     * Launches the given command in a new process.
037     * 
038     * @param cmd
039     *            The command to execute
040     * @param env
041     *            The environment for the new process. If null, the environment
042     *            of the current process is used.
043     * 
044     * @return the newly created process
045     * @throws IOException
046     *             if attempting to run a command in a specific directory
047     */
048    Process exec(final CommandLine cmd, final Map<String, String> env)
049            throws IOException;
050
051    /**
052     * Launches the given command in a new process, in the given working
053     * directory.
054     * 
055     * @param cmd
056     *            The command to execute
057     * @param env
058     *            The environment for the new process. If null, the environment
059     *            of the current process is used.
060     * @param workingDir
061     *            The directory to start the command in. If null, the current
062     *            directory is used
063     *
064     * @return the newly created process
065     * @throws IOException
066     *             if trying to change directory
067     */
068    Process exec(final CommandLine cmd, final Map<String, String> env,
069            final File workingDir) throws IOException;
070
071
072    /**
073     * Checks whether {@code exitValue} signals a failure on the current
074     * system (OS specific).
075     * <p>
076     * <b>Note</b> that this method relies on the conventions of the OS, it
077     * will return false results if the application you are running doesn't
078     * follow these conventions. One notable exception is the Java VM provided
079     * by HP for OpenVMS - it will return 0 if successful (like on any other
080     * platform), but this signals a failure on OpenVMS. So if you execute a new
081     * Java VM on OpenVMS, you cannot trust this method.
082     * </p>
083     *
084     * @param exitValue the exit value (return code) to be checked
085     * @return {@code true} if {@code exitValue} signals a failure
086     */
087    boolean isFailure(final int exitValue);
088}