KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > avalon > framework > ValuedEnum


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 JavaDoc;
58
59 /**
60  * Basic enum class for type-safe enums with values. Valued enum items can be compared and ordered
61  * with the provided methods. Should be used as an abstract base. For example:
62  *
63  * <pre>
64  * import org.apache.avalon.framework.ValuedEnum;
65  *
66  * public final class JavaVersion
67  * extends ValuedEnum
68  * {
69  * //standard enums for version of JVM
70  * public static final JavaVersion JAVA1_0 = new JavaVersion( "Java 1.0", 100 );
71  * public static final JavaVersion JAVA1_1 = new JavaVersion( "Java 1.1", 110 );
72  * public static final JavaVersion JAVA1_2 = new JavaVersion( "Java 1.2", 120 );
73  * public static final JavaVersion JAVA1_3 = new JavaVersion( "Java 1.3", 130 );
74  *
75  * private JavaVersion( final String name, final int value )
76  * {
77  * super( name, value );
78  * }
79  * }
80  * </pre>
81  *
82  * The above class could then be used as follows:
83  * <pre>
84  * import org.apache.avalon.framework.context.Context;
85  * import org.apache.avalon.framework.context.Contextualizable;
86  * import org.apache.avalon.framework.context.ContextException;
87  *
88  * public class MyComponent implements Contextualizable
89  * {
90  * JavaVersion requiredVer = JavaVersion.JAVA1_2;
91  *
92  * public void contextualize(Context context)
93  * throws ContextException
94  * {
95  * JavaVersion ver = (JavaVersion)context.get("java.version");
96  * if ( ver.isLessThan( requiredVer ) )
97  * {
98  * throw new RuntimeException( requiredVer.getName()+" or higher required" );
99  * }
100  * }
101  * }
102  * </pre>
103  *
104  * As with <code>Enum</code>, the {@link #ValuedEnum(String, int, Map)} constructor can be used to
105  * populate a <code>Map</code>, from which further functionality can be derived.
106  *
107  * <p>
108  * <em>NOTE:</em> between 4.0 and 4.1, the constructors' access has been changed
109  * from <code>public</code> to <code>protected</code>. This is to prevent users
110  * of the Enum breaking type-safety by defining new Enum items. All Enum items
111  * should be defined in the Enum class, as shown above.
112  * </p>
113  *
114  * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
115  * @version CVS $Revision: 1.19 $ $Date: 2003/02/11 15:58:37 $
116  */
117 public abstract class ValuedEnum
118     extends Enum JavaDoc
119 {
120     /**
121      * The value contained in enum.
122      */
123     private final int m_value;
124
125     /**
126      * Constructor for enum item.
127      *
128      * <p>
129      * <em>Note:</em> access changed from <code>public</code> to
130      * <code>protected</code> after 4.0. See class description.
131      * </p>
132      *
133      *
134      * @param name the name of enum item.
135      * @param value the value of enum item.
136      */
137     protected ValuedEnum( final String JavaDoc name, final int value )
138     {
139         this( name, value, null );
140     }
141
142     /**
143      * Constructor for enum item so that it gets added to Map at creation.
144      * Adding to a map is useful for implementing find...() style methods.
145      *
146      * </p>
147      * <em>Note:</em> access changed from <code>public</code> to
148      * <code>protected</code> after 4.0. See class description.
149      * </p>
150      *
151      * @param name the name of enum item.
152      * @param value the value of enum item.
153      * @param map the <code>Map</code> to add enum item to.
154      */
155     protected ValuedEnum( final String JavaDoc name, final int value, final Map JavaDoc map )
156     {
157         super( name, map );
158         m_value = value;
159     }
160
161     /**
162      * Get value of enum item.
163      *
164      * @return the enum item's value.
165      */
166     public final int getValue()
167     {
168         return m_value;
169     }
170
171     /**
172      * Test if enum item is equal in value to other enum.
173      *
174      * @param other the other enum
175      * @return true if equal
176      */
177     public final boolean isEqualTo( final ValuedEnum other )
178     {
179         return m_value == other.m_value;
180     }
181
182     /**
183      * Test if enum item is greater than in value to other enum.
184      *
185      * @param other the other enum
186      * @return true if greater than
187      */
188     public final boolean isGreaterThan( final ValuedEnum other )
189     {
190         return m_value > other.m_value;
191     }
192
193     /**
194      * Test if enum item is greater than or equal in value to other enum.
195      *
196      * @param other the other enum
197      * @return true if greater than or equal
198      */
199     public final boolean isGreaterThanOrEqual( final ValuedEnum other )
200     {
201         return m_value >= other.m_value;
202     }
203
204     /**
205      * Test if enum item is less than in value to other enum.
206      *
207      * @param other the other enum
208      * @return true if less than
209      */
210     public final boolean isLessThan( final ValuedEnum other )
211     {
212         return m_value < other.m_value;
213     }
214
215     /**
216      * Test if enum item is less than or equal in value to other enum.
217      *
218      * @param other the other enum
219      * @return true if less than or equal
220      */
221     public final boolean isLessThanOrEqual( final ValuedEnum other )
222     {
223         return m_value <= other.m_value;
224     }
225
226     /**
227      * Override toString method to produce human readable description.
228      *
229      * @return String in the form <code>type[name=value]</code>, eg.:
230      * <code>JavaVersion[Java 1.0=100]</code>.
231      */
232     public String JavaDoc toString()
233     {
234         return getClass().getName() + "[" + getName() + "=" + m_value + "]";
235     }
236 }
237
238
Popular Tags