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