1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * https://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19
20 package org.apache.commons.exec.launcher;
21
22 import java.io.File;
23 import java.io.IOException;
24 import java.nio.file.Path;
25 import java.util.Map;
26
27 import org.apache.commons.exec.CommandLine;
28
29 /**
30 * Abstracts platform-dependent implementations.
31 */
32 public interface CommandLauncher {
33
34 /**
35 * Executes the given command in a new process.
36 *
37 * @param commandLine The command to execute.
38 * @param env The environment for the new process. If null, the environment of the current process is used.
39 * @return the newly created process.
40 * @throws IOException if attempting to run a command in a specific directory.
41 */
42 Process exec(CommandLine commandLine, Map<String, String> env) throws IOException;
43
44 /**
45 * Executes the given command in a new process, in the given working directory.
46 *
47 * @param commandLine The command to execute.
48 * @param env The environment for the new process. If null, the environment of the current process is used.
49 * @param workingDirectory The directory to start the command in. If null, the current directory is used.
50 * @return the newly created process.
51 * @throws IOException if trying to change directory.
52 */
53 Process exec(CommandLine commandLine, Map<String, String> env, File workingDirectory) throws IOException;
54
55 /**
56 * Executes the given command in a new process, in the given working directory.
57 *
58 * @param commandLine The command to execute.
59 * @param env The environment for the new process. If null, the environment of the current process is used.
60 * @param workingDirectory The directory to start the command in. If null, the current directory is used.
61 * @return the newly created process.
62 * @throws IOException if trying to change directory.
63 * @since 1.5.0
64 */
65 default Process exec(final CommandLine commandLine, final Map<String, String> env, final Path workingDirectory) throws IOException {
66 return exec(commandLine, env, workingDirectory != null ? workingDirectory.toFile() : null);
67 }
68
69 /**
70 * Tests whether {@code exitValue} signals a failure on the current system (OS specific).
71 * <p>
72 * <strong>Note</strong> that this method relies on the conventions of the OS, it will return false results if the application you are running doesn't
73 * follow these conventions. One notable exception is the Java VM provided by HP for OpenVMS - it will return 0 if successful (like on any other platform),
74 * but this signals a failure on OpenVMS. So if you execute a new Java VM on OpenVMS, you cannot trust this method.
75 * </p>
76 *
77 * @param exitValue the exit value (return code) to be checked.
78 * @return {@code true} if {@code exitValue} signals a failure.
79 */
80 boolean isFailure(int exitValue);
81 }