1 /***
2 * Enumeration.java
3 *
4 * This file is part of the creme library.
5 * The creme library intends to ease the development effort of large
6 * applications by providing easy to use support classes.
7 *
8 * Copyright (C) 2002 Denis Bregeon
9 *
10 * This library is free software; you can redistribute it and/or
11 * modify it under the terms of the GNU Lesser General Public
12 * License as published by the Free Software Foundation; either
13 * version 2.1 of the License, or (at your option) any later version.
14 *
15 * This library is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 * Lesser General Public License for more details.
19 *
20 * You should have received a copy of the GNU Lesser General Public
21 * License along with this library; if not, write to the Free Software
22 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
23 *
24 * contact information: dbregeon@sourceforge.net
25 */
26 package org.jcreme.enumerations;
27
28 import java.io.Serializable;
29 import java.security.InvalidParameterException;
30 import java.util.Hashtable;
31
32 /***
33 * This is the base class for enumerated types.
34 *
35 * It presents an id (Integer) that may be used to different purpose and a name
36 * (String) that enables to handle inputs and outputs of the values. Both are
37 * unique for an Enumeration subclass instances.
38 *
39 * To ensure this uniqueness, subclasses must enable access to two hashtables.
40 * One links the names to the enumerated values, the other links the id to the
41 * enumerated value.
42 *
43 * @author $Author: dbregeon $
44 * @version $Revision: 1.3 $
45 */
46 public abstract class Enumeration implements Serializable, Comparable {
47 static final long serialVersionUID = 8763822295346411162L;
48
49 /***
50 * The name of this enumerated value.
51 */
52 private final String name;
53
54 /***
55 * Creates new Enumeration
56 *
57 * @param name
58 * the name of this enumerated value. It cannot be null.
59 * @throws InvalidParameterException
60 * if one of the parameters is null.
61 */
62 protected Enumeration(String name) throws InvalidParameterException {
63 if (name == null) {
64 throw new InvalidParameterException(
65 "The Name parameter can not be Null.");
66 }
67 this.name = name;
68
69 getFromName().put(name, this);
70 }
71
72 /***
73 * @return the name of the enumerated value.
74 */
75 public String getName() {
76 return this.name;
77 }
78
79 /***
80 * @return a String representation (actually the name).
81 */
82 public String toString() {
83 return getName();
84 }
85
86 /***
87 * This method enables to compare two enmerated values. The purpose of this
88 * method is to enable to sort the values in alphabetical order when
89 * displayed.
90 *
91 * @param o
92 * the object to compare. It must be an Enumeration instance.
93 * @return the result of the toString results comparison.
94 * @throws ClassCastException
95 * if the parameter is not an Enumeration instance.
96 */
97 public int compareTo(final Object o) {
98 int result = -2;
99 if (o != null) {
100 if (!(o instanceof Enumeration)) {
101 throw new ClassCastException("Objects of type "
102 + o.getClass().getName()
103 + " cannot be compared to objects of type Enumeration.");
104 }
105 result = this.getName().compareTo(((Enumeration) o).getName());
106 }
107 return result;
108 }
109
110 /***
111 * This method is for internal use only.
112 *
113 * @return the Hashtable that links the enumerated values names with the
114 * actual enumerated value.
115 */
116 protected abstract Hashtable getFromName();
117
118 /***
119 * This method enables to retrieve all the possible values of an Enumeration
120 * class. This method should be overriden in the subclasses to have the
121 * desired result. The method in this class returns an empty array.
122 *
123 * @return the values for this class.
124 */
125 public static Enumeration[] getValues() {
126 return new Enumeration[0];
127 }
128
129 /***
130 * This method enables to ensure the uniqueness of an Enumeration value.
131 * This method is called on a newly created Enumeration whenever an
132 * Enumeration is received on an ObjectStream. The unique value in the VM is
133 * then returned. If no value already exists, a new one is created. Priority
134 * is given to the name to retrieve the existing value.
135 *
136 * @return the value associated with the transmitted value.
137 *
138 */
139 protected Object readResolve() {
140 Object result = null;
141 if (this.name != null) {
142 result = getFromName().get(this.name);
143
144
145 if (result == null) {
146 getFromName().put(this.name, this);
147 result = this;
148 }
149 }
150 return result;
151 }
152 }