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    }