001/* 002 * Copyright (C) 2011 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except 005 * in compliance with the License. You may obtain a copy of the License at 006 * 007 * http://www.apache.org/licenses/LICENSE-2.0 008 * 009 * Unless required by applicable law or agreed to in writing, software distributed under the License 010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 011 * or implied. See the License for the specific language governing permissions and limitations under 012 * the License. 013 */ 014 015package com.google.common.base; 016 017import static com.google.common.base.Preconditions.checkNotNull; 018 019import com.google.common.annotations.GwtCompatible; 020import com.google.common.annotations.GwtIncompatible; 021import java.io.Serializable; 022import java.lang.ref.WeakReference; 023import java.lang.reflect.Field; 024import java.util.EnumSet; 025import java.util.HashMap; 026import java.util.Map; 027import java.util.WeakHashMap; 028import org.checkerframework.checker.nullness.qual.Nullable; 029 030/** 031 * Utility methods for working with {@link Enum} instances. 032 * 033 * @author Steve McKay 034 * @since 9.0 035 */ 036@GwtCompatible(emulated = true) 037public final class Enums { 038 039 private Enums() {} 040 041 /** 042 * Returns the {@link Field} in which {@code enumValue} is defined. For example, to get the {@code 043 * Description} annotation on the {@code GOLF} constant of enum {@code Sport}, use {@code 044 * Enums.getField(Sport.GOLF).getAnnotation(Description.class)}. 045 * 046 * @since 12.0 047 */ 048 @GwtIncompatible // reflection 049 public static Field getField(Enum<?> enumValue) { 050 Class<?> clazz = enumValue.getDeclaringClass(); 051 try { 052 return clazz.getDeclaredField(enumValue.name()); 053 } catch (NoSuchFieldException impossible) { 054 throw new AssertionError(impossible); 055 } 056 } 057 058 /** 059 * Returns an optional enum constant for the given type, using {@link Enum#valueOf}. If the 060 * constant does not exist, {@link Optional#absent} is returned. A common use case is for parsing 061 * user input or falling back to a default enum constant. For example, {@code 062 * Enums.getIfPresent(Country.class, countryInput).or(Country.DEFAULT);} 063 * 064 * @since 12.0 065 */ 066 public static <T extends Enum<T>> Optional<T> getIfPresent(Class<T> enumClass, String value) { 067 checkNotNull(enumClass); 068 checkNotNull(value); 069 return Platform.getEnumIfPresent(enumClass, value); 070 } 071 072 @GwtIncompatible // java.lang.ref.WeakReference 073 private static final Map<Class<? extends Enum<?>>, Map<String, WeakReference<? extends Enum<?>>>> 074 enumConstantCache = new WeakHashMap<>(); 075 076 @GwtIncompatible // java.lang.ref.WeakReference 077 private static <T extends Enum<T>> Map<String, WeakReference<? extends Enum<?>>> populateCache( 078 Class<T> enumClass) { 079 Map<String, WeakReference<? extends Enum<?>>> result = new HashMap<>(); 080 for (T enumInstance : EnumSet.allOf(enumClass)) { 081 result.put(enumInstance.name(), new WeakReference<Enum<?>>(enumInstance)); 082 } 083 enumConstantCache.put(enumClass, result); 084 return result; 085 } 086 087 @GwtIncompatible // java.lang.ref.WeakReference 088 static <T extends Enum<T>> Map<String, WeakReference<? extends Enum<?>>> getEnumConstants( 089 Class<T> enumClass) { 090 synchronized (enumConstantCache) { 091 Map<String, WeakReference<? extends Enum<?>>> constants = enumConstantCache.get(enumClass); 092 if (constants == null) { 093 constants = populateCache(enumClass); 094 } 095 return constants; 096 } 097 } 098 099 /** 100 * Returns a converter that converts between strings and {@code enum} values of type {@code 101 * enumClass} using {@link Enum#valueOf(Class, String)} and {@link Enum#name()}. The converter 102 * will throw an {@code IllegalArgumentException} if the argument is not the name of any enum 103 * constant in the specified enum. 104 * 105 * @since 16.0 106 */ 107 public static <T extends Enum<T>> Converter<String, T> stringConverter(final Class<T> enumClass) { 108 return new StringConverter<T>(enumClass); 109 } 110 111 private static final class StringConverter<T extends Enum<T>> extends Converter<String, T> 112 implements Serializable { 113 114 private final Class<T> enumClass; 115 116 StringConverter(Class<T> enumClass) { 117 this.enumClass = checkNotNull(enumClass); 118 } 119 120 @Override 121 protected T doForward(String value) { 122 return Enum.valueOf(enumClass, value); 123 } 124 125 @Override 126 protected String doBackward(T enumValue) { 127 return enumValue.name(); 128 } 129 130 @Override 131 public boolean equals(@Nullable Object object) { 132 if (object instanceof StringConverter) { 133 StringConverter<?> that = (StringConverter<?>) object; 134 return this.enumClass.equals(that.enumClass); 135 } 136 return false; 137 } 138 139 @Override 140 public int hashCode() { 141 return enumClass.hashCode(); 142 } 143 144 @Override 145 public String toString() { 146 return "Enums.stringConverter(" + enumClass.getName() + ".class)"; 147 } 148 149 private static final long serialVersionUID = 0L; 150 } 151}