1 /*
2 * This file is part of hyphenType. hyphenType is free software: you can
3 * redistribute it and/or modify it under the terms of the GNU General Public
4 * License as published by the Free Software Foundation, either version 3 of the
5 * License, or (at your option) any later version. hyphenType is distributed in
6 * the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the
7 * implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
8 * the GNU General Public License for more details. You should have received a
9 * copy of the GNU General Public License along with hyphenType. If not, see
10 * <http://www.gnu.org/licenses/>.
11 */
12 package org.hyphenType.exit;
13
14 import java.lang.annotation.ElementType;
15 import java.lang.annotation.Retention;
16 import java.lang.annotation.RetentionPolicy;
17 import java.lang.annotation.Target;
18 import java.util.Formatter;
19
20 import org.hyphenType.datastructure.Options;
21 import org.hyphenType.unittesting.NonExceptionalExit;
22
23 /**
24 * A message to decorate the exit status constants for the <strong>final
25 * users</strong>.
26 *
27 * @author akira
28 */
29 @Retention(RetentionPolicy.RUNTIME)
30 @Target(ElementType.FIELD)
31 public @interface ExitStatusConstant {
32
33 /**
34 * The description that will appear in the documentation for the end user.
35 */
36 String userDescription();
37
38 /**
39 * Message to the end user of the application when a problem happens. The
40 * value of this variable may refer to replacements using the standard of
41 * {@link Formatter#format(String, Object...)}. The values of replacement
42 * objects ({0}, {1}, etc.) depends on how the JVM or environment is going
43 * to exit:<br/>
44 * <ol>
45 * <li>Explicit call to {@link Options#exit(Enum, Object...)} - The values
46 * of {0}, {1}, etc will be set to be the values of the array (second
47 * argument).</li>
48 * <li>Explicit call to {@link Options#exit(int, Object...))} - Idem to the
49 * above.</li>
50 * <li>Explicit call to {@link Options#exit(Throwable)} - {0} will be set to
51 * be {@link Throwable#getLocalizedMessage()} and {1} will be the string
52 * printed by calling {@link Throwable#printStackTrace()}.</li>
53 * <li>When this exit status constant catches an exception - Exit status
54 * constants may catch exceptions listed in the property
55 * {@link ExitStatusConstant#catches()}. When an exception is caught by an
56 * exit status constant, {0} and {1} will be treated as in the above: {0}
57 * will be set to be {@link Throwable#getLocalizedMessage()} and {1} will be
58 * the string printed by calling {@link Throwable#printStackTrace()}</li>
59 * </ol>
60 * In the two last cases, if {@link Throwable#getLocalizedMessage()} is
61 * null, it will be replaced by the empty string. This is to avoid the end
62 * user receiving a message such as: "Program terminated. Error message:
63 * null".
64 */
65 String message();
66
67 /**
68 * The list of throwable classes that will be caught by the exit status
69 * constant decorated by this annotation. This list is used to implement a
70 * visitor design pattern that traps exceptions or errors from a main
71 * method. When an uncaught exception comes from a main class, hyphenType
72 * will search for one exit status constant that catches it. If an exit
73 * status constant catches the throwable, the method
74 * {@link StatusCode#beforeExit(ExitStatusHelper)} is called on this exit
75 * status constant and the throwable is accessible to the exit status
76 * constant via the method {@link ExitStatusHelper#getThrowable()}.<br/>
77 * <br/>
78 * It is important to notice that the {@link NonExceptionalExit} cannot
79 * be trapped by any exit status constant, since the
80 * {@link NonExceptionalExit} exception has a special meaning in
81 * hyphenType. For more details about the {@link NonExceptionalExit}
82 * exception, refer to the documentation of this class.
83 *
84 * @see NonExceptionalExit
85 */
86 Class<? extends Throwable>[] catches() default {};
87 }