1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121 | package Torello.Java;
/**
* A Java {@code 'enum'} that is used in several locations in the {@code Java-HTML JAR} Library
* to allow an end-user to request the quantity of text being produced by a tool or application.
* The {@link Verbose} flag / constant is designed to request the maximum amount of information
* when running a tool, while the {@link Silent} constant may be used to ask that no textual
* output be sent to Standard-Output
*
* <BR /><BR />Primarily for convenience and ease-of-use, each of the four constants in this
* {@code enum} are assigned an integer depicting the verbosity. When deciding whether or not
* to print a message to the user using this {@code enum}, using the {@link #level} integer is
* usually a more exedient coding-solution.
*
* <BR /><BR >The following example should help elucidate using the {@link #level} field. Note
* that in this particular example, the settings for {@link #Quiet} and for {@link #Silent} are
* simply not being used. In this example, keep in mind that the programmer may simply include
* a message for the {@link #Quiet} setting someplace else in the code, entirely!
*
* <DIV CLASS=EXAMPLE>{@code
* // This is an extremely verbose way of coding!
* switch (verbosity)
* {
* case Silent:
* case Quiet: break;
* case Normal:
* case Verbose: System.out.println("Starting New Program Section");
* }
*
* // From a programming-analysis perspective alone, this is a lot more succint
* if (verbosity.level >= 2) System.out.println("Starting New Program Section");
* }</DIV>
*/
public enum Verbosity
{
/**
* Indicates a user-request that an application or program should not produce any output, other
* than error-output. In the <B>{@code Java-HTML JAR}</B> Library, error output is rarely
* abbreviated or eliminated.
*
* <BR /><BR />This constant is assigned "Level 0", and the {@link #level} constant-field will
* always be zero.
*/
Silent(0),
/**
* Indicates a user-request for an application or program to run producing the minimum amount
* of text-output possible. Error output may (or may not) be shunted, as per the capricious
* whims of the software guys.
*
* <BR /><BR />This constant is assigned "Level 1", and the {@link #level} constant-field will
* always be one.
*/
Quiet(1),
/**
* The {@code enum}-constant should be used to indicate that the default output-text be sent to
* Standard-Output and Error-Output.
*
* <BR /><BR />This constant is assigned "Level 2", and the {@link #level} constant-field will
* always be two.
*/
Normal(2),
/**
* If a programmer can produce additional information about the state of a program as it runs,
* then the {@code 'Verbose'} constant / flag may be used to indicate a user-request as such.
*
* <BR /><BR />This constant is assigned "Level 3", and the {@link #level} constant-field will
* always be three.
*/
Verbose(3);
/**
* There are quite a number of situations where an integer is easier for doing the comparisons
* an actual instance of {@code 'Verbosity'}. Each of the four constants of this {@code enum}
* have their own, ordered, {@code 'level'} setting (which is a number between {@code '0'} and
* {@code '3'}).
*/
public final int level;
private Verbosity(int level) { this.level = level; }
/**
* Retrieves the Enum-Constant associated with the integer parameter {@code 'verbosityLevel'}.
*
* @param verbosityLevel This must be a value between {@code '0'} and {@code '3'}, or an
* IllegalArgumentException will throw.
*
* <BR /><BR />This is used to indicate which of the four constants are to be returned by this
* method.
*
* <BR /><BR /><TABLE CLASS=JDBriefTable>
* <TR><TH>Constant</TH> <TH>Integer Level</TH> </TR>
* <TR><TD>{@link #Silent}</TD> <TD>{@code 0}</TD> </TR>
* <TR><TD>{@link #Quiet}</TD> <TD>{@code 1}</TD> </TR>
* <TR><TD>{@link #Normal}</TD> <TD>{@code 2}</TD> </TR>
* <TR><TD>{@link #Verbose}</TD> <TD>{@code 3}</TD> </TR>
* </TABLE>
*
* @return The Enum-Constant associated with the input {@code 'verbosityLevel'}
*
* @throws IllegalArgumentException If an integer-value other than the above four possible
* values is provided as input.
*/
public static Verbosity get(int verbosityLevel)
{
if ((verbosityLevel < 0) || (verbosityLevel > 3)) throw new IllegalArgumentException
("verbosityLevel=" + verbosityLevel + ", but this value must be between 0 and 3.");
switch (verbosityLevel)
{
case 0: return Silent;
case 1: return Quiet;
case 2: return Normal;
case 3: return Verbose;
default: throw new UnreachableError();
}
}
}
|