Package: ProcessExecutor$ConsoleOutput

ProcessExecutor$ConsoleOutput

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