001: /*
002: * Janino - An embedded Java[TM] compiler
003: *
004: * Copyright (c) 2006, Arno Unkrig
005: * All rights reserved.
006: *
007: * Redistribution and use in source and binary forms, with or without
008: * modification, are permitted provided that the following conditions
009: * are met:
010: *
011: * 1. Redistributions of source code must retain the above copyright
012: * notice, this list of conditions and the following disclaimer.
013: * 2. Redistributions in binary form must reproduce the above
014: * copyright notice, this list of conditions and the following
015: * disclaimer in the documentation and/or other materials
016: * provided with the distribution.
017: * 3. The name of the author may not be used to endorse or promote
018: * products derived from this software without specific prior
019: * written permission.
020: *
021: * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
022: * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
023: * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
024: * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
025: * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
026: * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
027: * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
028: * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
029: * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
030: * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
031: * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
032: */
033:
034: package org.codehaus.janino.util.enumerator;
035:
036: import java.util.*;
037:
038: /**
039: * A class that represents an enumerated value. Its main features are its {@link #toString()} and
040: * {@link #fromString(String, Class)} method, which map names to values and vice versa.
041: * <p>
042: * To use this class, derive from it and define one or more
043: * <code>public static final</code> fields, as follows:
044: * <pre>
045: * public final class Suit extends Enumerator {
046: *
047: * // Exactly N instances of "Suit" exist to represent the N possible values.
048: * public static final Suit CLUBS = new Suit("clubs");
049: * public static final Suit DIAMONDS = new Suit("diamonds");
050: * public static final Suit HEARTS = new Suit("hearts");
051: * public static final Suit SPADES = new Suit("spades");
052: *
053: * // Optional, if you want to use EumeratorSet arithmetics.
054: * public static final EnumeratorSet NONE = new EnumeratorSet(Suit.class ).setName("none");
055: * public static final EnumeratorSet ALL = new EnumeratorSet(Suit.class, true).setName("all");
056: *
057: * // These MUST be declared exactly like this:
058: * private Suit(String name) { super(name); }
059: * public static Suit fromString(String name) throws EnumeratorFormatException {
060: * return (Suit) Enumerator.fromString(name, Suit.class);
061: * }
062: * }
063: * </pre>
064: *
065: * @see <a href="http://java.sun.com/developer/Books/effectivejava/Chapter5.pdf">Effective Java, Item 21</a>
066: * @see org.codehaus.janino.util.enumerator.EnumeratorSet
067: */
068: public abstract class Enumerator {
069: /*package*/final String name;
070:
071: /**
072: * Class enumeratorClass => Map: String name => Enumerator
073: */
074: private static final Map instances = Collections
075: .synchronizedMap(new HashMap());
076:
077: /**
078: * Initialize the enumerator to the given value.
079: */
080: protected Enumerator(String name) {
081: if (name == null)
082: throw new NullPointerException();
083: this .name = name;
084:
085: Enumerator.getInstances(this .getClass()).put(name, this );
086: }
087:
088: /**
089: * Equality is reference identity.
090: */
091: public final boolean equals(Object that) {
092: return this == that;
093: }
094:
095: /**
096: * Enforce {@link Object}'s notion of {@link Object#hashCode()}.
097: */
098: public final int hashCode() {
099: return super .hashCode();
100: }
101:
102: /**
103: * Returns a mapping of name to Enumerator for the given enumeratorClass.
104: */
105: /*package*/static Map getInstances(Class enumeratorClass) {
106: Map m = (Map) Enumerator.instances.get(enumeratorClass);
107: if (m != null)
108: return m;
109:
110: // The map need not be synchronized because it is modified only during initialization
111: // of the Enumerator.
112: m = new HashMap();
113: Enumerator.instances.put(enumeratorClass, m);
114: return m;
115: }
116:
117: /**
118: * Initialize an {@link Enumerator} from a string.
119: * <p>
120: * The given string is converted into a value by looking at all instances of the given type
121: * created so far.
122: * <p>
123: * Derived classes should invoke this method as follows:<pre>
124: * public class Suit extends Enumerator {
125: * ...
126: * public static Suit fromString(String name) throws EnumeratorFormatException {
127: * return (Suit) Enumerator.fromString(name, Suit.class);
128: * }
129: * }</pre>
130: *
131: * @throws EnumeratorFormatException if the string cannot be identified
132: */
133: protected static final Enumerator fromString(String name,
134: Class enumeratorClass) throws EnumeratorFormatException {
135: Enumerator value = (Enumerator) Enumerator.getInstances(
136: enumeratorClass).get(name);
137: if (value == null)
138: throw new EnumeratorFormatException(name);
139: return value;
140: }
141:
142: /**
143: * Returns the <code>name</code> passed to {@link #Enumerator(String)}.
144: */
145: public String toString() {
146: return this.name;
147: }
148: }
|