Package: ProcessExecutor

ProcessExecutor

name	instruction	branch	complexity	line	method
forExecutable(String)	M: 0 C: 5 100%	M: 0 C: 0 100%	M: 0 C: 1 100%	M: 0 C: 1 100%	M: 0 C: 1 100%

Coverage

1: package it.tidalwave.util;
2:
3: import javax.annotation.Nonnull;
4: import java.util.List;
5: import java.util.Scanner;
6: import java.io.IOException;
7: import java.nio.file.Path;
8: import it.tidalwave.util.impl.DefaultProcessExecutor;
9:
10: /***************************************************************************************************************************************************************
11: *
12: * A helper class for launching an external process and handling its output.
13: *
14: * @author Fabrizio Giudici
15: *
16: **************************************************************************************************************************************************************/
17: public interface ProcessExecutor
18: {
19: /***********************************************************************************************************************************************************
20: * A container of the console output of the process.
21: **********************************************************************************************************************************************************/
22: public static interface ConsoleOutput
23: {
24: /***************************************************************************************************************
25: *
26: * Starts collection output from the external process.
27: *
28: * @return itself
29: *
30: **************************************************************************************************************/
31: @Nonnull
32: public ConsoleOutput start();
33:
34: /***************************************************************************************************************
35: *
36: * Waits for the completion of the launched process.
37: *
38: * @return itself
39: * @throws InterruptedException if the process was interrupted
40: *
41: **************************************************************************************************************/
42: @Nonnull
43: public ConsoleOutput waitForCompleted ()
44: throws InterruptedException;
45:
46: /***************************************************************************************************************
47: *
48: * Returns a {@link Scanner} on the latest line of output produced that matches a given regular expression,
49: * split on the given delimiter. Remember that the {@code Scanner} must be closed when done.
50: *
51: * @param filterRegexp the regular expression to filter output
52: * @param delimiterRegexp the regular expression to split the line
53: * @return the {@code Scanner} to parse results
54: *
55: **************************************************************************************************************/
56: @Nonnull @SuppressWarnings({"squid:S2095", "IOResourceOpenedButNotSafelyClosed"})
57: public Scanner filteredAndSplitBy (@Nonnull String filterRegexp, @Nonnull String delimiterRegexp);
58:
59: /***************************************************************************************************************
60: *
61: * Returns the output produced by the launched process, filtered by the given regular expression.
62: *
63: * @param filterRegexp the regular expression to filter output
64: * @return the output lines
65: *
66: **************************************************************************************************************/
67: @Nonnull
68: public List<String> filteredBy (@Nonnull String filterRegexp);
69:
70: /***************************************************************************************************************
71: *
72: * Waits for an output line matching the given regular expression to appear.
73: *
74: * @param regexp the regular expression
75: * @return itself
76: * @throws IOException if something goes wrong
77: * @throws InterruptedException if the process has been interrupted
78: *
79: **************************************************************************************************************/
80: @Nonnull
81: public ConsoleOutput waitFor (@Nonnull String regexp)
82: throws InterruptedException, IOException;
83:
84: /***************************************************************************************************************
85: *
86: * Clears the contents collected so far.
87: *
88: **************************************************************************************************************/
89: public void clear();
90:
91: /***************************************************************************************************************
92: *
93: * Reads the output until it's completed.
94: *
95: **************************************************************************************************************/
96: public void read ()
97: throws IOException;
98:
99: /***************************************************************************************************************
100: *
101: *
102: **************************************************************************************************************/
103: @Nonnull
104: public List<String> getContent();
105: }
106:
107: /***********************************************************************************************************************************************************
108: * Specifies the executable to run. It is searched in the path.
109: *
110: * @param executable the executable
111: * @return itself
112: * @throws IOException if something goes wrong
113: **********************************************************************************************************************************************************/
114: @Nonnull
115: public static ProcessExecutor forExecutable (@Nonnull final String executable)
116: throws IOException
117: {
118: return new DefaultProcessExecutor(executable);
119: }
120:
121: /***********************************************************************************************************************************************************
122: * Specifies a single argument for the executable. This method can be called multiple times.
123: *
124: * @param argument the argument
125: * @return itself
126: **********************************************************************************************************************************************************/
127: @Nonnull
128: public ProcessExecutor withArgument (@Nonnull String argument);
129:
130: /***********************************************************************************************************************************************************
131: * Specifies some arguments for the executable. This method can be called multiple times.
132: *
133: * @param arguments the argument
134: * @return itself
135: **********************************************************************************************************************************************************/
136: @Nonnull
137: public ProcessExecutor withArguments (@Nonnull String... arguments);
138:
139: /***********************************************************************************************************************************************************
140: * Specifies the working directory for the executable.
141: *
142: * @param workingDirectory the working directory
143: * @return itself
144: **********************************************************************************************************************************************************/
145: @Nonnull
146: public ProcessExecutor withWorkingDirectory (@Nonnull Path workingDirectory);
147:
148: /***********************************************************************************************************************************************************
149: * Launches the external process and starts collecting its output (which can be analyzed by calling
150: * {@code getStdout()} and {@code getStderr()}.
151: *
152: * @return itself
153: * @throws IOException if something goes wrong
154: **********************************************************************************************************************************************************/
155: @Nonnull
156: ProcessExecutor start()
157: throws IOException;
158:
159: /***********************************************************************************************************************************************************
160: * Waits for the completion of the external process. If the process terminates with a non-zero status code, an
161: * {@link IOException} is thrown.
162: *
163: * @return itself
164: * @throws ProcessExecutorException if the process terminates with a non zero exit code
165: * @throws IOException if something went wrong
166: * @throws InterruptedException if the process has been interrupted
167: **********************************************************************************************************************************************************/
168: @Nonnull
169: public ProcessExecutor waitForCompletion()
170: throws IOException, InterruptedException;
171:
172: /***********************************************************************************************************************************************************
173: * Sends some input to the external process.
174: *
175: * @param string the input to send
176: * @return itself
177: **********************************************************************************************************************************************************/
178: @Nonnull
179: public ProcessExecutor send (@Nonnull String string);
180:
181: @Nonnull
182: public ConsoleOutput getStdout();
183:
184: @Nonnull
185: public ConsoleOutput getStderr();
186: }