001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     * 
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     * 
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.commons.lang.enums;
018    
019    import java.util.Iterator;
020    import java.util.List;
021    import java.util.Map;
022    
023    /**
024     * <p>Utility class for accessing and manipulating {@link Enum}s.</p>
025     *
026     * @see Enum
027     * @see ValuedEnum
028     * @author Apache Software Foundation
029     * @author Gary Gregory
030     * @since 2.1 (class existed in enum package from v1.0)
031     * @version $Id: EnumUtils.java 905636 2010-02-02 14:03:32Z niallp $
032     */
033    public class EnumUtils {
034    
035        /**
036         * Public constructor. This class should not normally be instantiated.
037         * @since 2.0
038         */
039        public EnumUtils() {
040          super();
041        }
042    
043        /**
044         * <p>Gets an <code>Enum</code> object by class and name.</p>
045         * 
046         * @param enumClass  the class of the <code>Enum</code> to get
047         * @param name  the name of the Enum to get, may be <code>null</code>
048         * @return the enum object
049         * @throws IllegalArgumentException if the enum class is <code>null</code>
050         */
051        public static Enum getEnum(Class enumClass, String name) {
052            return Enum.getEnum(enumClass, name);
053        }
054    
055        /**
056         * <p>Gets a <code>ValuedEnum</code> object by class and value.</p>
057         * 
058         * @param enumClass  the class of the <code>Enum</code> to get
059         * @param value  the value of the <code>Enum</code> to get
060         * @return the enum object, or null if the enum does not exist
061         * @throws IllegalArgumentException if the enum class is <code>null</code>
062         */
063        public static ValuedEnum getEnum(Class enumClass, int value) {
064            return (ValuedEnum) ValuedEnum.getEnum(enumClass, value);
065        }
066    
067        /**
068         * <p>Gets the <code>Map</code> of <code>Enum</code> objects by
069         * name using the <code>Enum</code> class.</p>
070         *
071         * <p>If the requested class has no enum objects an empty
072         * <code>Map</code> is returned. The <code>Map</code> is unmodifiable.</p>
073         * 
074         * @param enumClass  the class of the <code>Enum</code> to get
075         * @return the enum object Map
076         * @throws IllegalArgumentException if the enum class is <code>null</code>
077         * @throws IllegalArgumentException if the enum class is not a subclass
078         *  of <code>Enum</code>
079         */
080        public static Map getEnumMap(Class enumClass) {
081            return Enum.getEnumMap(enumClass);
082        }
083    
084        /**
085         * <p>Gets the <code>List</code> of <code>Enum</code> objects using
086         * the <code>Enum</code> class.</p>
087         *
088         * <p>The list is in the order that the objects were created
089         * (source code order).</p>
090         *
091         * <p>If the requested class has no enum objects an empty
092         * <code>List</code> is returned. The <code>List</code> is unmodifiable.</p>
093         * 
094         * @param enumClass  the class of the Enum to get
095         * @return the enum object Map
096         * @throws IllegalArgumentException if the enum class is <code>null</code>
097         * @throws IllegalArgumentException if the enum class is not a subclass
098         *  of <code>Enum</code>
099         */
100        public static List getEnumList(Class enumClass) {
101            return Enum.getEnumList(enumClass);
102        }
103    
104        /**
105         * <p>Gets an <code>Iterator</code> over the <code>Enum</code> objects
106         * in an <code>Enum</code> class.</p>
107         *
108         * <p>The iterator is in the order that the objects were created
109         * (source code order).</p>
110         *
111         * <p>If the requested class has no enum objects an empty
112         * <code>Iterator</code> is returned. The <code>Iterator</code>
113         * is unmodifiable.</p>
114         * 
115         * @param enumClass  the class of the <code>Enum</code> to get
116         * @return an <code>Iterator</code> of the <code>Enum</code> objects
117         * @throws IllegalArgumentException if the enum class is <code>null</code>
118         * @throws IllegalArgumentException if the enum class is not a subclass of <code>Enum</code>
119         */
120        public static Iterator iterator(Class enumClass) {
121            return Enum.getEnumList(enumClass).iterator();
122        }
123        
124    }