Package: ProcessExecutor

ProcessExecutor

Coverage

1: /*
2: * *********************************************************************************************************************
3: *
4: * TheseFoolishThings: Miscellaneous utilities
5: * http://tidalwave.it/projects/thesefoolishthings
6: *
7: * Copyright (C) 2009 - 2024 by Tidalwave s.a.s. (http://tidalwave.it)
8: *
9: * *********************************************************************************************************************
10: *
11: * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
12: * the License. You may obtain a copy of the License at
13: *
14: * http://www.apache.org/licenses/LICENSE-2.0
15: *
16: * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
17: * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
18: * specific language governing permissions and limitations under the License.
19: *
20: * *********************************************************************************************************************
21: *
22: * git clone https://bitbucket.org/tidalwave/thesefoolishthings-src
23: * git clone https://github.com/tidalwave-it/thesefoolishthings-src
24: *
25: * *********************************************************************************************************************
26: */
27: package it.tidalwave.util;
28:
29: import javax.annotation.CheckForNull;
30: import javax.annotation.Nonnull;
31: import javax.annotation.concurrent.ThreadSafe;
32: import java.util.List;
33: import java.util.Scanner;
34: import java.io.IOException;
35: import it.tidalwave.util.spi.DefaultProcessExecutor;
36:
37: /***********************************************************************************************************************
38: *
39: * A facility that provides means for launching an external process, scraping its stdout and stderr in real-time and
40: * sending commands by means of its stdin.
41: *
42: * @see DefaultProcessExecutor
43: *
44: * @author Fabrizio Giudici
45: * @since 1.39
46: *
47: **********************************************************************************************************************/
48: @ThreadSafe
49: public interface ProcessExecutor
50: {
51: /*******************************************************************************************************************
52: *
53: * This interface provides operations that can be performed on the stdout or stderr consoles attached to the
54: * external process.
55: *
56: ******************************************************************************************************************/
57: public static interface ConsoleOutput
58: {
59: /***************************************************************************************************************
60: *
61: * A listener that is invoked whenever a line is read from the console.
62: *
63: **************************************************************************************************************/
64: public static interface Listener
65: {
66: public void onReceived (@Nonnull String string);
67: }
68:
69: /***************************************************************************************************************
70: *
71: * Returns {@code true} if the latest received line matches the given regular expression.
72: *
73: * @param regexp the regular expression
74: * @return {@code true} in case of match
75: *
76: **************************************************************************************************************/
77: public boolean latestLineMatches (@Nonnull String regexp);
78:
79: /***************************************************************************************************************
80: *
81: * Returns a list of lines that match the given regular expression.
82: *
83: * @param regexp the regular expression
84: * @return the list of matching lines
85: *
86: **************************************************************************************************************/
87: @Nonnull
88: public List<String> filteredBy (@Nonnull String regexp);
89:
90: /***************************************************************************************************************
91: *
92: * Returns a {@link Scanner} over the latest line matching a given regular expression, with the specific
93: * delimiter regular expression.
94: *
95: * @param regexp the regular expression for the filter
96: * @param delimiterRegexp the regular expression for the {@code Scanner}
97: * @return the list of matching lines
98: *
99: **************************************************************************************************************/
100: @Nonnull
101: public Scanner filteredAndSplitBy (@Nonnull String regexp, @Nonnull String delimiterRegexp);
102:
103: /***************************************************************************************************************
104: *
105: * Waits for a line matching the given regular expression to appear.
106: *
107: * @param regexp the regular expression
108: * @return itself for chaining methods
109: * @throws InterruptedException if the wait has been interrupted
110: * @throws IOException in case the process has terminated or another I/O error
111: *
112: **************************************************************************************************************/
113: @Nonnull
114: public ConsoleOutput waitFor (@Nonnull String regexp)
115: throws InterruptedException, IOException;
116:
117: /***************************************************************************************************************
118: *
119: * Clears the buffer of lines. This means that no filtering or waiting operation can be performed on the
120: * output produced so far. It will be possible to perform further operations on the output produced from now
121: * on.
122: *
123: **************************************************************************************************************/
124: public void clear();
125:
126: /***************************************************************************************************************
127: *
128: * Sets a listener.
129: *
130: * @see Listener
131: * @param listener the listener
132: *
133: **************************************************************************************************************/
134: public void setListener (@Nonnull Listener listener);
135:
136: /***************************************************************************************************************
137: *
138: * Returns the set listener
139: *
140: * @see Listener
141: * @return the listener
142: *
143: **************************************************************************************************************/
144: @CheckForNull
145: public Listener getListener();
146: }
147:
148: /*******************************************************************************************************************
149: *
150: * Adds some arguments to pass to the external process.
151: *
152: * @param arguments the arguments
153: * @return itself for chaining methods
154: *
155: ******************************************************************************************************************/
156: @Nonnull
157: public ProcessExecutor withArguments (@Nonnull String ... arguments);
158:
159: /*******************************************************************************************************************
160: *
161: * Adds a single argument to pass to the external process.
162: *
163: * @param argument the argument
164: * @return itself for chaining methods
165: *
166: ******************************************************************************************************************/
167: @Nonnull
168: public ProcessExecutor withArgument (@Nonnull String argument);
169:
170: /*******************************************************************************************************************
171: *
172: * Starts the external process.
173: *
174: * @return itself for chaining methods
175: * @throws IOException in case of error
176: *
177: ******************************************************************************************************************/
178: @Nonnull
179: public ProcessExecutor start()
180: throws IOException;
181:
182: /*******************************************************************************************************************
183: *
184: * Stops the external process.
185: *
186: ******************************************************************************************************************/
187: public void stop();
188:
189: /*******************************************************************************************************************
190: *
191: * Waits for the termination of the external process.
192: *
193: * @return itself for chaining methods
194: * @throws InterruptedException if the wait has been interrupted
195: * @throws IOException in case of I/O error
196: *
197: ******************************************************************************************************************/
198: @SuppressWarnings("RedundantThrows")
199: @Nonnull
200: public ProcessExecutor waitForCompletion()
201: throws IOException, InterruptedException;
202:
203: /*******************************************************************************************************************
204: *
205: * Sends a string to the stdin of the running process. If a carriage return is needed, it must be explicitly placed
206: * in the string.
207: *
208: * @param string the string to send
209: * @return itself for chaining methods
210: * @throws IOException in case of I/O error
211: *
212: ******************************************************************************************************************/
213: @Nonnull
214: public ProcessExecutor send (@Nonnull String string)
215: throws IOException;
216:
217: /*******************************************************************************************************************
218: *
219: * Returns the stdout console.
220: *
221: * @return the console
222: *
223: ******************************************************************************************************************/
224: @Nonnull
225: public ConsoleOutput getStdout();
226:
227: /*******************************************************************************************************************
228: *
229: * Returns the stderr console.
230: *
231: * @return the console
232: *
233: ******************************************************************************************************************/
234: @Nonnull
235: public ConsoleOutput getStderr();
236: }
237: