1 /*
2 JavaProgram.java
3 Creation date : 3/06/2010
4 Copyright © Benjamin Croizet (graffity2199@yahoo.fr)
5
6 This program is free software; you can redistribute it and/or
7 modify it under the terms of the GNU General Public License
8 or GNU Lesser General Public License as published by the
9 Free Software Foundation; either version 3 of the License,
10 or (at your option) any later version.
11
12 This program is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
16
17 You should have received copies of the GNU General Public License
18 and GNU Lesser General Public License along with this program;
19 if not, write to the Free Software Foundation, Inc.,
20 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
21 http://www.fsf.org/licensing/licenses/gpl.html
22 http://www.gnu.org/licenses/lgpl.html
23 */
24
25 package net.sourceforge.plantumldependency.commoncli.program;
26
27 import java.io.Serializable;
28 import java.net.URL;
29 import java.util.List;
30 import java.util.Set;
31
32 import net.sourceforge.plantumldependency.common.clone.DeepCloneable;
33 import net.sourceforge.plantumldependency.commoncli.command.CommandLine;
34 import net.sourceforge.plantumldependency.commoncli.exception.CommandLineException;
35 import net.sourceforge.plantumldependency.commoncli.option.Option;
36 import net.sourceforge.plantumldependency.commoncli.option.execution.ExecutableOption;
37 import net.sourceforge.plantumldependency.commoncli.option.status.OptionStatus;
38 import net.sourceforge.plantumldependency.commoncli.program.execution.JavaProgramExecution;
39 import net.sourceforge.plantumldependency.commoncli.program.version.ProgramVersion;
40
41 /**
42 * The interface which describes a Java program, its name, its authors, its license and all data
43 * which can be useful.
44 *
45 * @author Benjamin Croizet (<a href="mailto:graffity2199@yahoo.fr>graffity2199@yahoo.fr</a>)
46 * @since 1.3.0
47 * @version 1.3.0
48 */
49 public interface JavaProgram extends Comparable < JavaProgram >, Serializable, DeepCloneable < JavaProgram > {
50
51 /**
52 * Adds a program command line example.
53 *
54 * @param exampleCommandLine
55 * the {@link CommandLine} instance which shows a program command line usage, mustn't
56 * be <code>null</code> and must be valid.
57 * @throws CommandLineException
58 * if an example command line can't be correctly parsed and isn't a valid example.
59 * @since 1.3.0
60 */
61 void addExampleCommandLine(CommandLine exampleCommandLine) throws CommandLineException;
62
63 /**
64 * Adds a program known bug or limitation.
65 *
66 * @param bugOrLimitationDescription
67 * the {@link String} describing the program known bug or limitation, mustn't be
68 * <code>null</code> nor empty.
69 * @throws CommandLineException
70 * if an example command line can't be correctly parsed and isn't a valid example.
71 * @since 1.3.0
72 */
73 void addKnownBugOrLimitation(String bugOrLimitationDescription) throws CommandLineException;
74
75 /**
76 * Adds an option to the program.
77 *
78 * @param option
79 * the {@link Option} instance to add, mustn't be <code>null</code>.
80 * @throws CommandLineException
81 * if the program already has the option, if the option name is duplicated or if the
82 * priority is duplicated.
83 * @since 1.3.0
84 */
85 void addOption(Option option) throws CommandLineException;
86
87 /**
88 * Gets all executable options supported by the program.
89 *
90 * @return the {@link Set} of all {@link ExecutableOption} supported by the program.
91 * @since 1.3.0
92 */
93 Set < ExecutableOption > getAllExecutableOptions();
94
95 /**
96 * Gets all executable options supported by the program of the following status.
97 *
98 * @param status
99 * the option status, telling if the executable options to look for are active,
100 * inactive or hidden, mustn't be <code>null</code>.
101 * @return the {@link Set} of all {@link ExecutableOption} supported by the program.
102 * @since 1.3.0
103 */
104 Set < ExecutableOption > getAllExecutableOptions(OptionStatus status);
105
106 /**
107 * Gets all executable options supported by the program of any status contained in the list.
108 *
109 * @param statusSet
110 * the option status set, telling if the executable options look for are active,
111 * inactive or hidden, mustn't be <code>null</code>.
112 * @return the {@link Set} of all {@link ExecutableOption} supported by the program.
113 * @since 1.3.0
114 */
115 Set < ExecutableOption > getAllExecutableOptions(Set < OptionStatus > statusSet);
116
117 /**
118 * Gets all mandatory options.
119 *
120 * @return the {@link Set} of all mandatory {@link Option}.
121 * @since 1.3.0
122 */
123 Set < Option > getAllMandatoryOptions();
124
125 /**
126 * Gets all optional options which are considered active, meaning that they can be taken in the
127 * command line.
128 *
129 * @return the {@link Set} of all optional {@link Option}.
130 * @since 1.3.0
131 */
132 Set < Option > getAllOptionalActiveOptions();
133
134 /**
135 * Gets all options supported by the program.
136 *
137 * @return the {@link Set} of all {@link Option} supported by the program.
138 * @since 1.3.0
139 */
140 Set < Option > getAllOptions();
141
142 /**
143 * Gets all options supported by the program of the following status.
144 *
145 * @param status
146 * the option status, telling if the executable options to look for are active,
147 * inactive or hidden, mustn't be <code>null</code>.
148 * @return the {@link Set} of all {@link Option} supported by the program.
149 * @since 1.3.0
150 */
151 Set < Option > getAllOptions(OptionStatus status);
152
153 /**
154 * Gets all options supported by the program of any status contained in the list.
155 *
156 * @param statusSet
157 * the option status set, telling if the executable options look for are active,
158 * inactive or hidden, mustn't be <code>null</code>.
159 * @return the {@link Set} of all {@link Option} supported by the program.
160 * @since 1.3.0
161 */
162 Set < Option > getAllOptions(Set < OptionStatus > statusSet);
163
164 /**
165 * Gets the list of program authors.
166 * <p>
167 * For instance it can be :<br>
168 * - <i>Linus Torvalds</i><br>
169 * - <i>Elizabeth II</i>
170 * </p>
171 *
172 * @return the {@link List} of all program authors as {@link String}.
173 * @since 1.3.0
174 */
175 List < String > getAuthors();
176
177 /**
178 * Gets the program full usage. It is composed of the program title description, the command
179 * synopsis, the mandatory active options, active optional options and examples.
180 * <p>
181 * For instance it can be :<br>
182 * <i>PlantUML Dependency - reverse engineering java source files to generate PlantUML
183 * description (http://plantuml.sourceforge.net}<br>
184 * Usage: <br>
185 * java -jar plantuml-dependency.jar -o FILE [OPTIONS]<br>
186 * <br>
187 * where mandatory options are:<br>
188 * -o, --output FILE<br>
189 * To output file path where to generate the PlantUML description. If not specified, the default
190 * is plantuml-DATE.txt<br>
191 * FILE specifies a valid file path, not a directory. It can be absolute or relative.<br>
192 * <br>
193 * where optional options are:<br>
194 * -about, --author, --authors<br>
195 * To display information about PlantUML Dependency and its authors.<br>
196 * <br>
197 * Examples:<br>
198 * java -jar plantuml-dependency.jar -h</i>
199 * </p>
200 *
201 * @return the program full usage description as a {@link StringBuilder}, i.e. all explanation
202 * about how the program works and what it does.
203 * @since 1.3.0
204 */
205 StringBuilder getFullUsage();
206
207 /**
208 * Gets the program description used in the full usage description. It is a single line
209 * description explaining what the program does.
210 * <p>
211 * For instance it can be :<br>
212 * - <i>reverse engineering java source files to generate PlantUML description</i><br>
213 * - <i>copy files and directories</i>
214 * </p>
215 *
216 * @return the program description as a {@link StringBuilder} used in the full usage
217 * description.
218 * @since 1.3.0
219 */
220 StringBuilder getFullUsageDescription();
221
222 /**
223 * Gets the program examples description used in the full usage description.
224 * <p>
225 * For instance it can be :<br>
226 * - <i>java -jar plantuml-dependency.jar -h</i><br>
227 * - <i>java -jar plantuml-dependency.jar -o plantuml.txt -i *Test.java</i>
228 * </p>
229 *
230 * @return the program description as a {@link StringBuilder} used in the full usage
231 * description.
232 * @since 1.3.0
233 */
234 StringBuilder getFullUsageExamples();
235
236 /**
237 * Gets the program Jar name.
238 * <p>
239 * For instance it can be :<br>
240 * - <i>Azureus2.jar</i><br>
241 * - <i>plantuml.jar</i>
242 * </p>
243 *
244 * @return the program jar name.
245 * @since 1.3.0
246 */
247 String getJarName();
248
249 /**
250 * Gets the program known bugs or limitations description used in the full usage description.
251 * <p>
252 * For instance it can be :<br>
253 * - <i>Doesn't work with dates prior to 1900</i><br>
254 * - <i>Doesn't manage the UTF-8 encoding</i>
255 * </p>
256 *
257 * @return the program known bugs or limitations description as a {@link StringBuilder} used in
258 * the full usage description.
259 * @since 1.3.0
260 */
261 StringBuilder getKnownBugsOrLimitations();
262
263 /**
264 * Gets the list of program licenses.
265 * <p>
266 * For instance it can be :<br>
267 * - <i>GPL v3</i><br>
268 * - <i>Apache License</i>
269 * </p>
270 *
271 * @return the {@link List} of all program licenses as {@link String}.
272 * @since 1.3.0
273 */
274 List < String > getLicenseNames();
275
276 /**
277 * Gets the program main usage. It is composed of the program title description and the command
278 * synopsis. Only active options are shown.
279 * <p>
280 * For instance it can be :<br>
281 * <i>PlantUML Dependency - reverse engineering java source files to generate PlantUML
282 * description (http://plantuml.sourceforge.net}<br>
283 * <br>
284 * Usage: <br>
285 * java -jar plantuml-dependency.jar -o FILE [OPTIONS]</i>
286 * </p>
287 *
288 * @return the program main usage description as a {@link StringBuilder}, i.e. the program
289 * description and command synopsis.
290 * @since 1.3.0
291 */
292 StringBuilder getMainUsage();
293
294 /**
295 * Gets the program name.
296 * <p>
297 * For instance it can be :<br>
298 * - <i>Azureus</i><br>
299 * - <i>PlantUML</i>
300 * </p>
301 *
302 * @return the program name.
303 * @since 1.3.0
304 */
305 String getName();
306
307 /**
308 * Gets the program URL.
309 * <p>
310 * For instance it can be :<br>
311 * - <i><a href="http://azureus.sourceforge.net">http://azureus.sourceforge.net</a></i><br>
312 * - <i><a href="http://plantuml.sourceforge.net">http://plantuml.sourceforge.net</a></i>
313 * </p>
314 *
315 * @return the program website URL.
316 * @since 1.3.0
317 */
318 URL getUrl();
319
320 /**
321 * Gets the program version.
322 *
323 * @return the {@link ProgramVersion} instance.
324 * @since 1.3.0
325 */
326 ProgramVersion getVersion();
327
328 /**
329 * Gets the program execution following the command line.
330 *
331 * @param commandLine
332 * the {@link CommandLine} instance to parse and to get the execution from, mustn't
333 * be <code>null</code>.
334 * @return the {@link JavaProgramExecution} instance following the passed command line in order
335 * to execute the program.
336 * @throws CommandLineException
337 * if any error occurs while reading and parsing the command line.
338 * @since 1.3.0
339 */
340 JavaProgramExecution parseCommandLine(final CommandLine commandLine) throws CommandLineException;
341 }