Enum


1   /* ====================================================================
2    * The Apache Software License, Version 1.1
3    *
4    * Copyright (c) 1997-2003 The Apache Software Foundation. All rights
5    * reserved.
6    *
7    * Redistribution and use in source and binary forms, with or without
8    * modification, are permitted provided that the following conditions
9    * are met:
10   *
11   * 1. Redistributions of source code must retain the above copyright
12   *    notice, this list of conditions and the following disclaimer.
13   *
14   * 2. Redistributions in binary form must reproduce the above copyright
15   *    notice, this list of conditions and the following disclaimer in
16   *    the documentation and/or other materials provided with the
17   *    distribution.
18   *
19   * 3. The end-user documentation included with the redistribution,
20   *    if any, must include the following acknowledgment:
21   *    "This product includes software developed by the
22   *    Apache Software Foundation (http://www.apache.org/)."
23   *    Alternately, this acknowledgment may appear in the software
24   *    itself, if and wherever such third-party acknowledgments
25   *    normally appear.
26   *
27   * 4. The names "Jakarta", "Avalon", and "Apache Software Foundation"
28   *    must not be used to endorse or promote products derived from this
29   *    software without prior written permission. For written
30   *    permission, please contact apache@apache.org.
31   *
32   * 5. Products derived from this software may not be called "Apache",
33   *    nor may "Apache" appear in their name, without prior written
34   *    permission of the Apache Software Foundation.
35   *
36   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39   * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
40   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47   * SUCH DAMAGE.
48   * ====================================================================
49   *
50   * This software consists of voluntary contributions made by many
51   * individuals on behalf of the Apache Software Foundation. For more
52   * information on the Apache Software Foundation, please see
53   * <http://www.apache.org/>.
54   */
55  package org.apache.avalon.framework;
56  
57  import java.util.Map  ;
58  
59  /**
60   * Basic enum class for type-safe enums. Should be used as an abstract base. For example:
61   *
62   * <pre>
63   * import org.apache.avalon.framework.Enum;
64   *
65   * public final class Color extends Enum {
66   *   public static final Color RED = new Color( "Red" );
67   *   public static final Color GREEN = new Color( "Green" );
68   *   public static final Color BLUE = new Color( "Blue" );
69   *
70   *   private Color( final String color )
71   *   {
72   *     super( color );
73   *   }
74   * }
75   * </pre>
76   *
77   * If further operations, such as iterating over all items, are required, the
78   * {@link #Enum(String, Map)} constructor can be used to populate a <code>Map</code>, from which
79   * further functionality can be derived:
80   * <pre>
81   * public final class Color extends Enum {
82   *   static final Map map = new HashMap();
83   *
84   *   public static final Color RED = new Color( "Red", map );
85   *   public static final Color GREEN = new Color( "Green", map );
86   *   public static final Color BLUE = new Color( "Blue", map );
87   *
88   *   private Color( final String color, final Map map )
89   *   {
90   *     super( color, map );
91   *   }
92   *
93   *   public static Iterator iterator()
94   *   {
95   *     return map.values().iterator();
96   *   }
97   * }
98   * </pre>
99   *
100  * <p>
101  * <em>NOTE:</em> between 4.0 and 4.1, the constructors' access has been changed
102  * from <code>public</code> to <code>protected</code>. This is to prevent users
103  * of the Enum breaking type-safety by defining new Enum items. All Enum items
104  * should be defined in the Enum class, as shown above.
105  * </p>
106  *
107  *
108  * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
109  * @version CVS $Revision: 1.23 $ $Date: 2003/02/11 15:58:37 $
110  */
111 public abstract class Enum
112 {
113     /**
114      * The string representation of the Enum.
115      */
116     private final String   m_name;
117 
118     /**
119      * Constructor to add a new named item.
120      * <p>
121      * <em>Note:</em> access changed from <code>public</code> to
122      * <code>protected</code> after 4.0. See class description.
123      * </p>
124      *
125      * @param name Name of the item.
126      */
127     protected Enum( final String   name )
128     {
129         this( name, null );
130     }
131 
132     /**
133      * Constructor to add a new named item.
134      * <p>
135      * <em>Note:</em> access changed from <code>public</code> to
136      * <code>protected</code> after 4.0. See class description.
137      * </p>
138      *
139      * @param name Name of the item.
140      * @param map A <code>Map</code>, to which will be added a pointer to the newly constructed
141      * object.
142      */
143     protected Enum( final String   name, final Map   map )
144     {
145         m_name = name;
146         if( null != map )
147         {
148             map.put( name, this );
149         }
150     }
151 
152     /**
153      * Tests for equality. Two Enum:s are considered equal
154      * if they have the same class names and the same names.
155      * Identity is tested for first, so this method runs fast.
156      * The method is also declared final - I (LSutic) did this to
157      * allow the JIT to inline it easily.
158      * 
159      * @param other the other object
160      * @return the equality status
161      */
162     public final boolean equals( final Object   other )
163     {
164         if( null == other )
165         {
166             return false;
167         }
168         else
169         {
170             return other == this 
171                 || ( other.getClass().getName().equals( this.getClass().getName() ) 
172                 && m_name.equals( ( (Enum  )other ).m_name ) );
173         }
174     }
175 
176     /**
177      * Returns a hash code value for the object.
178      *
179      * @return a hash code value for this object
180      */
181     public int hashCode()
182     {
183         return m_name.hashCode();
184     }
185 
186     /**
187      * Retrieve the name of this Enum item, set in the constructor.
188      * @return the name <code>String</code> of this Enum item
189      */
190     public final String   getName()
191     {
192         return m_name;
193     }
194 
195     /**
196      * Human readable description of this Enum item. For use when debugging.
197      * @return String in the form <code>type[name]</code>, eg.:
198      * <code>Color[Red]</code>.
199      */
200     public String   toString()
201     {
202         return getClass().getName() + "[" + m_name + "]";
203     }
204 }
205
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags