001 package org.bukkit;
002
003 import java.lang.annotation.ElementType;
004 import java.lang.annotation.Retention;
005 import java.lang.annotation.RetentionPolicy;
006 import java.lang.annotation.Target;
007 import java.util.Map;
008
009 import com.google.common.collect.ImmutableMap;
010
011 /**
012 * This designates the warning state for a specific item.
013 * <p>
014 * When the server settings dictate 'default' warnings, warnings are printed
015 * if the {@link #value()} is true.
016 */
017 @Target({ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.TYPE})
018 @Retention(RetentionPolicy.RUNTIME)
019 public @interface Warning {
020
021 /**
022 * This represents the states that server verbose for warnings may be.
023 */
024 public enum WarningState {
025
026 /**
027 * Indicates all warnings should be printed for deprecated items.
028 */
029 ON,
030 /**
031 * Indicates no warnings should be printed for deprecated items.
032 */
033 OFF,
034 /**
035 * Indicates each warning would default to the configured {@link
036 * Warning} annotation, or always if annotation not found.
037 */
038 DEFAULT;
039
040 private static final Map<String, WarningState> values = ImmutableMap.<String,WarningState>builder()
041 .put("off", OFF)
042 .put("false", OFF)
043 .put("f", OFF)
044 .put("no", OFF)
045 .put("n", OFF)
046 .put("on", ON)
047 .put("true", ON)
048 .put("t", ON)
049 .put("yes", ON)
050 .put("y", ON)
051 .put("", DEFAULT)
052 .put("d", DEFAULT)
053 .put("default", DEFAULT)
054 .build();
055
056 /**
057 * This method checks the provided warning should be printed for this
058 * state
059 *
060 * @param warning The warning annotation added to a deprecated item
061 * @return <ul>
062 * <li>ON is always True
063 * <li>OFF is always false
064 * <li>DEFAULT is false if and only if annotation is not null and
065 * specifies false for {@link Warning#value()}, true otherwise.
066 * </ul>
067 */
068 public boolean printFor(Warning warning) {
069 if (this == DEFAULT) {
070 return warning == null || warning.value();
071 }
072 return this == ON;
073 }
074
075 /**
076 * This method returns the corresponding warning state for the given
077 * string value.
078 *
079 * @param value The string value to check
080 * @return {@link #DEFAULT} if not found, or the respective
081 * WarningState
082 */
083 public static WarningState value(final String value) {
084 if (value == null) {
085 return DEFAULT;
086 }
087 WarningState state = values.get(value.toLowerCase());
088 if (state == null) {
089 return DEFAULT;
090 }
091 return state;
092 }
093 }
094
095 /**
096 * This sets if the deprecation warnings when registering events gets
097 * printed when the setting is in the default state.
098 *
099 * @return false normally, or true to encourage warning printout
100 */
101 boolean value() default false;
102
103 /**
104 * This can provide detailed information on why the event is deprecated.
105 *
106 * @return The reason an event is deprecated
107 */
108 String reason() default "";
109 }