PageRenderTime 187ms CodeModel.GetById 81ms app.highlight 62ms RepoModel.GetById 38ms app.codeStats 0ms

/lib/docs/enum/docs/Enum.htm

http://mp-rechnungs-und-kundenverwaltung.googlecode.com/
HTML | 386 lines | 324 code | 62 blank | 0 comment | 0 complexity | eea41c392264c004df2ab13daa063969 MD5 | raw file
  1<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
  2<html>
  3<head>
  4   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  5   <meta name="GENERATOR" content="Mozilla/4.75 [en] (Windows NT 5.0; U) [Netscape]">
  6   <meta name="Author" content="Dmitri Plotnikov">
  7   <title>HCO Database Design</title>
  8</head>
  9<body text="#000000" bgcolor="#FFFFEF" link="#0000EE" vlink="#551A8B" alink="#FF0000">
 10<img SRC="images/plotnix_logo.gif" NOSAVE height=68 width=216>
 11<h1>
 12Enum<br>
 13<font size=+2>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; An Amazing Enum Implementation
 14for Java</font></h1>
 15Unlike its ancestors (C and C++)&nbsp; Java does not support the notion
 16of an <b>enum</b>, which is a data type all values of which are explicitly
 17enumerated in the type definition.
 18<p>That said, an object-oriented implementation of the concept of enum
 19in Java can be much more powerful than C-style <b>enum</b>.
 20<p>The Enum framework (in reality, the whole framework is a single class)
 21proves that by providing extensive functionality that includes:
 22<blockquote>&nbsp;
 23<table>
 24<tr>
 25<td VALIGN=TOP WIDTH="30"><img SRC="images/star.gif" NOSAVE BORDER=0 height=15 width=17></td>
 26
 27<td>Either an integer or string value or both for each constant</td>
 28</tr>
 29
 30<tr>
 31<td VALIGN=TOP><img SRC="images/star.gif" NOSAVE BORDER=0 height=15 width=17></td>
 32
 33<td VALIGN=TOP>A human-readable description that can be easily internationalized.&nbsp;
 34An enum type is automatically associated with .properties files containing
 35labels of enums in specific languages.</td>
 36</tr>
 37
 38<tr>
 39<td VALIGN=TOP><img SRC="images/star.gif" NOSAVE BORDER=0 height=15 width=17></td>
 40
 41<td>All constants of an Enum can be loaded from a .properties file.</td>
 42</tr>
 43</table>
 44</blockquote>
 45Every Enum type is represented by a separate class extending the Enum abstract
 46class (see <a href="api/com/plotnix/enum/Enum.html">API</a>)
 47<br>&nbsp;
 48<h2>
 49Basic Enum</h2>
 50The easiest way to define an Enum type is to declare a class that extends
 51Enum and a separate instance of that class as a public static field of
 52the class itself.
 53<blockquote><tt><font color="#003399">public class Color extends Enum</font></tt>
 54<br><tt><font color="#003399">{</font></tt>
 55<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp; public static Color RED
 56= new Color();</font></tt>
 57<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp; public static Color GREEN
 58= new Color();</font></tt>
 59<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp; public static Color BLUE
 60= new Color();</font></tt>
 61<br><tt><font color="#003399">}</font></tt></blockquote>
 62This class is accompanied by a <tt>Color.properties</tt> file that is located
 63in the same package as the <tt>Color</tt> class:
 64<blockquote><tt><font color="#009900">RED=Red</font></tt>
 65<br><tt><font color="#009900">GREEN=Green</font></tt>
 66<br><tt><font color="#009900">BLUE=Blue</font></tt></blockquote>
 67Italian names of colors are in <tt>Color_it_IT.properties</tt> file:
 68<blockquote><tt><font color="#009900">RED=Rosso</font></tt>
 69<br><tt><font color="#009900">GREEN=Verde</font></tt>
 70<br><tt><font color="#009900">BLUE=Azzurro</font></tt></blockquote>
 71The following table contains values returned by various methods of Color:
 72<blockquote>&nbsp;
 73<table BORDER COLS=4 WIDTH="500" >
 74<tr>
 75<td>&nbsp;</td>
 76
 77<td><b><tt>Color.RED</tt></b></td>
 78
 79<td><b><tt>Color.GREEN</tt></b></td>
 80
 81<td><b><tt>Color.BLUE</tt></b></td>
 82</tr>
 83
 84<tr>
 85<td><b><tt>intValue()</tt></b></td>
 86
 87<td><tt><font color="#660000">0</font></tt></td>
 88
 89<td><tt><font color="#660000">1</font></tt></td>
 90
 91<td><tt><font color="#660000">2</font></tt></td>
 92</tr>
 93
 94<tr>
 95<td><b><tt>stringValue()</tt></b></td>
 96
 97<td><tt><font color="#660000">"RED"</font></tt></td>
 98
 99<td><tt><font color="#660000">"GREEN"</font></tt></td>
100
101<td><tt><font color="#660000">"BLUE"</font></tt></td>
102</tr>
103
104<tr>
105<td><b><tt>toString()</tt></b></td>
106
107<td><tt><font color="#660000">"Red"</font></tt></td>
108
109<td><tt><font color="#660000">"Green"</font></tt></td>
110
111<td><tt><font color="#660000">"Blue"</font></tt></td>
112</tr>
113
114<tr>
115<td><b><tt>toString(Locale.ITALY)</tt></b></td>
116
117<td><tt><font color="#660000">"Rosso"</font></tt></td>
118
119<td><tt><font color="#660000">"Verde"</font></tt></td>
120
121<td><tt><font color="#660000">"Azzurro"</font></tt></td>
122</tr>
123</table>
124</blockquote>
125Enum provides the following automation:
126<ul>
127<li>
128Each constant is given a unique, sequencial integer value</li>
129
130<li>
131Each constant's string value is the name of the <tt>public static</tt>
132declaration of the constant</li>
133
134<li>
135String representations of constants are retrieved from the .properties
136file for the specified Locale, using the constant's string value as a property
137key.</li>
138</ul>
139Class Enum has some useful static methods:
140<blockquote><tt><font color="#003399">Color allColors[] = (Color[])Enum.enum(Color.class);</font></tt>
141<blockquote>This method will return all Colors in the order they are declared:
142<tt>Color.RED</tt>,
143<tt>Color.GREEN</tt>,
144<tt>Color.BLUE</tt></blockquote>
145<tt><font color="#003399">Color green = (Color)Enum.enum(Color.class, "GREEN");</font></tt>
146<blockquote>This method will the Color constant by its string value</blockquote>
147<tt><font color="#003399">Color blue = (Color)Enum.enum(Color.class, 2);</font></tt>
148<blockquote>This method will the Color constant by its integer value</blockquote>
149</blockquote>
150Enums can be used as types of properties of JavaBeans:
151<blockquote><tt><font color="#000084">public class Crayon {</font></tt>
152<p><tt><font color="#000084">&nbsp;&nbsp; private Color color;</font></tt>
153<p><tt><font color="#000084">&nbsp;&nbsp; public void setColor(Color color){</font></tt>
154<br><tt><font color="#000084">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; this.color
155= color;</font></tt>
156<br><tt><font color="#000084">&nbsp;&nbsp; }</font></tt>
157<p><tt><font color="#000084">&nbsp;&nbsp; public Color getColor(){</font></tt>
158<br><tt><font color="#000084">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return color;</font></tt>
159<br><tt><font color="#000084">&nbsp;&nbsp; }</font></tt>
160<p><tt><font color="#000084">&nbsp;&nbsp; ...</font></tt>
161<br><tt><font color="#000084">}</font></tt>
162<p><tt><font color="#000084">Crayon crayon = new Crayon();</font></tt>
163<br><tt><font color="#000084">crayon.setColor(Color.GREEN);</font></tt>
164<p><tt><font color="#000084">System.err.println("Questo pastello &egrave;
165" +</font></tt>
166<br><tt><font color="#000084">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
167crayon.getColor().toString(Locale.ITALY));</font></tt>
168<br>&nbsp;
169<br>&nbsp;</blockquote>
170
171<h2>
172Explicit String Values and Labels</h2>
173String values and/or labels of constants can be specified explicitly:
174<blockquote><tt><font color="#003399">public class Gender extends Enum</font></tt>
175<br><tt><font color="#003399">{</font></tt>
176<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp; public static Gender FEMALE
177= new Gender("F", "Female");</font></tt>
178<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp; public static Gender MALE
179= new Gender("M", "Male");</font></tt>
180<p><tt><font color="#003399">&nbsp;&nbsp;&nbsp; protected Gender(String
181string, String label){</font></tt>
182<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
183super(string, label);</font></tt>
184<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp; }</font></tt>
185<br><tt><font color="#003399">}</font></tt></blockquote>
186Spanish words for genders are in <tt>Gender_es.properties</tt> file:
187<blockquote><tt><font color="#009900">F=Feminino</font></tt>
188<br><tt><font color="#009900">M=Masculino</font></tt></blockquote>
189The default labels are used when the <tt>.properties</tt> file for the
190corresponding locale is missing.
191<p>The following table contains values returned by various methods of Gender:
192<blockquote>&nbsp;
193<table BORDER WIDTH="500" >
194<tr>
195<td WIDTH="300">&nbsp;</td>
196
197<td><b><tt>Gender.FEMALE</tt></b></td>
198
199<td><b><tt>Gender.MALE</tt></b></td>
200</tr>
201
202<tr>
203<td><b><tt>intValue()</tt></b></td>
204
205<td><tt><font color="#660000">0</font></tt></td>
206
207<td><tt><font color="#660000">1</font></tt></td>
208</tr>
209
210<tr>
211<td><b><tt>stringValue()</tt></b></td>
212
213<td><tt><font color="#660000">"F"</font></tt></td>
214
215<td><tt><font color="#660000">"M"</font></tt></td>
216</tr>
217
218<tr>
219<td><b><tt>toString()</tt></b></td>
220
221<td><tt><font color="#660000">"Female"</font></tt></td>
222
223<td><tt><font color="#660000">"Male"</font></tt></td>
224</tr>
225
226<tr>
227<td><b><tt>toString(new Locale("es", "MX"))</tt></b></td>
228
229<td><tt><font color="#660000">"Feminino"</font></tt></td>
230
231<td><tt><font color="#660000">"Masculino"</font></tt></td>
232</tr>
233
234<tr>
235<td><b><tt>toString(Locale.ITALY)</tt></b></td>
236
237<td><tt><font color="#660000">"Female"</font></tt></td>
238
239<td><tt><font color="#660000">"Male"</font></tt></td>
240</tr>
241</table>
242</blockquote>
243
244<h2>
245Explicit Integer Values</h2>
246Integer values of constants can alse be specified explicitly:
247<blockquote><tt><font color="#003399">public class Order extends Enum {</font></tt>
248<p><tt><font color="#003399">&nbsp;&nbsp;&nbsp; public static Order LESS_THAN
249= new Order(-1);</font></tt>
250<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp; public static Order EQUAL_TO
251= new Order(0);</font></tt>
252<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp; public static Order GREATER_THAN
253= new Order(1);</font></tt>
254<p><tt><font color="#003399">&nbsp;&nbsp;&nbsp; protected Order(int integer){</font></tt>
255<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
256super(integer);</font></tt>
257<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp; }</font></tt>
258<br><tt><font color="#003399">}</font></tt></blockquote>
259The following table contains values returned by various methods of <tt>Order</tt>:
260<blockquote>&nbsp;
261<table BORDER COLS=4 WIDTH="500" >
262<tr>
263<td>&nbsp;</td>
264
265<td><b><tt>Order.LESS_THAN</tt></b></td>
266
267<td><b><tt>Color.EQUAL_TO</tt></b></td>
268
269<td><b><tt>Color.GREATER_THAN</tt></b></td>
270</tr>
271
272<tr>
273<td><b><tt>intValue()</tt></b></td>
274
275<td><tt><font color="#660000">-1</font></tt></td>
276
277<td><tt><font color="#660000">0</font></tt></td>
278
279<td><tt><font color="#660000">1</font></tt></td>
280</tr>
281
282<tr>
283<td><b><tt>stringValue()</tt></b></td>
284
285<td><tt><font color="#660000">"LESS_THAN"</font></tt></td>
286
287<td><tt><font color="#660000">"EQUAL_TO"</font></tt></td>
288
289<td><tt><font color="#660000">"GREATER_THAN"</font></tt></td>
290</tr>
291
292<tr>
293<td><b><tt>toString()</tt></b></td>
294
295<td><tt><font color="#660000">"LESS_THAN"</font></tt></td>
296
297<td><tt><font color="#660000">"EQUAL_TO"</font></tt></td>
298
299<td><tt><font color="#660000">"GREATER_THAN"</font></tt></td>
300</tr>
301</table>
302</blockquote>
303
304<br>&nbsp;
305<h2>
306Integer Enums</h2>
307If you need to use an Enum in switch statements, you may want to declare
308integer constants instead of objects of the enum class.&nbsp; The static
309method <tt>Enum.initIntegerEnum</tt> method of Enum should be invoked from
310a static code fragment of the Enum class:
311<blockquote><tt><font color="#003399">public class Employment extends Enum
312{</font></tt>
313<p><tt><font color="#003399">&nbsp;&nbsp;&nbsp; public static final int
314EMPLOYED = 1;</font></tt>
315<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp; public static final int
316SELF_EMPLOYED = 2;</font></tt>
317<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp; public static final int
318UNEMPLOYED = 3;</font></tt>
319<p><tt><font color="#003399">&nbsp;&nbsp;&nbsp; static {</font></tt>
320<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
321// Register all 'public static ints' of this class as Enums</font></tt>
322<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
323initIntegerEnum(Employment.class);</font></tt>
324<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp; }</font></tt>
325<br><tt><font color="#003399">}</font></tt></blockquote>
326String values and labels of the constants can be acquired using the following
327calls:
328<blockquote><tt><font color="#003399">Enum employed = Enum.enum(Employment.class,
329Employment.EMPLOYED);</font></tt>
330<br><tt><font color="#003399">String string = employed.stringValue();</font></tt>
331<br><tt><font color="#003399">String label = employed.toString();</font></tt></blockquote>
332In this case both the string value and the label will be "EMPLOYED". Just
333like any Enum, such integer Enum can be internationalized - the public
334static int field names function as keys in the .properties file.
335<br>&nbsp;
336<h2>
337Loading Enums from a Files</h2>
338If it is preferred to keep constant definitions in a file and not define
339individual constants for each value, that can also be done:
340<blockquote><tt><font color="#003399">public class Flower extends Enum</font></tt>
341<br><tt><font color="#003399">{</font></tt>
342<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp; static {</font></tt>
343<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
344// Load all Enums of this class from Flower.properties</font></tt>
345<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
346loadEnum(Flower.class);</font></tt>
347<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp; }</font></tt>
348<p><tt><font color="#003399">&nbsp;&nbsp;&nbsp; // Define any of the Flower
349constants individually</font></tt>
350<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp; public static Flower ROSE
351= enum("rose");</font></tt>
352<p><tt><font color="#003399">&nbsp;&nbsp;&nbsp; /**</font></tt>
353<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp;&nbsp; * Convenience method
354that finds a Flower object by its name.</font></tt>
355<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp;&nbsp; */</font></tt>
356<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp; public static Flower enum(String
357name){</font></tt>
358<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
359return (Flower)enum(Flower.class, name);</font></tt>
360<br><tt><font color="#003399">&nbsp;&nbsp;&nbsp; }</font></tt>
361<br><tt><font color="#003399">}</font></tt></blockquote>
362The Flower.properties file:
363<blockquote><tt><font color="#009900">rose=Rosa</font></tt>
364<br><tt><font color="#009900">daisy=Chrysanthemum leucanthemum</font></tt>
365<br><tt><font color="#009900">violet=Viola</font></tt>
366<br><tt><font color="#009900">forget-me-not=Myosotis</font></tt></blockquote>
367An integer Enum can be loaded the same way, except instead of the loadEnum
368method the loadIntegerEnum method should be called.&nbsp; Property names
369in the .properties file should then be numeric.
370<p>Note: if you are using one of the load... methods, do not allocate any
371additional constants, find the loaded once like we did in the Flower class.
372<br>&nbsp;
373<h2>
374Download</h2>
375The class is <i>freely</i> available under the PLOTNIX license.
376<p><a href="api/com/plotnix/enum/Enum.html">JavaDoc</a>
377<br>&nbsp;
378<p><b><font size=+2>Enjoy!</font></b>
379<p>
380<hr WIDTH="100%">
381<center><i><font size=-1>Copyright &copy; 2001, PLOTNIX, Inc</font></i></center>
382
383<p><font size=-2>Java, JavaSoft, are trademarks or registered trademarks
384of Sun Microsystems, Inc.</font>
385</body>
386</html>