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 */
017package org.apache.juneau.commons.lang;
018
019/**
020 * Three-state enumeration for boolean-like values that can be explicitly set or unset.
021 *
022 * <p>
023 * This enum is useful in scenarios where you need to distinguish between:
024 * <ul>
025 *    <li>A value that is explicitly set to <jk>true</jk></li>
026 *    <li>A value that is explicitly set to <jk>false</jk></li>
027 *    <li>A value that is not set (should inherit from a parent/default)</li>
028 * </ul>
029 *
030 * <h5 class='section'>Example:</h5>
031 * <p class='bjava'>
032 *    <jc>// In an annotation</jc>
033 *    <jk>public @interface</jk> MyConfig {
034 *       TriState <jsm>enabled</jsm>() <jk>default</jk> TriState.<jsf>UNSET</jsf>;
035 *    }
036 *
037 *    <jc>// Usage</jc>
038 *    <ja>@MyConfig</ja>(enabled = TriState.<jsf>TRUE</jsf>)  <jc>// Explicitly enabled</jc>
039 *    <ja>@MyConfig</ja>(enabled = TriState.<jsf>FALSE</jsf>) <jc>// Explicitly disabled</jc>
040 *    <ja>@MyConfig</ja>                                    <jc>// Not set, inherits default</jc>
041 * </p>
042 */
043public enum TriState {
044   /** Explicitly set to <jk>true</jk>. */
045   TRUE,
046
047   /** Explicitly set to <jk>false</jk>. */
048   FALSE,
049
050   /** Not set - should inherit from parent or use default value. */
051   UNSET;
052
053   /**
054    * Converts this TriState to a boolean value.
055    *
056    * <p>
057    * If this is {@link #UNSET}, returns the provided default value.
058    *
059    * @param defaultValue The default value to use if this is {@link #UNSET}.
060    * @return <jk>true</jk> if this is {@link #TRUE}, <jk>false</jk> if this is {@link #FALSE},
061    *    or the provided default if this is {@link #UNSET}.
062    */
063   public boolean toBoolean(boolean defaultValue) {
064      return this == UNSET ? defaultValue : (this == TRUE);
065   }
066
067   /**
068    * Converts a boolean to a TriState.
069    *
070    * @param value The boolean value.
071    * @return {@link #TRUE} if <jk>true</jk>, {@link #FALSE} if <jk>false</jk>.
072    */
073   public static TriState fromBoolean(boolean value) {
074      return value ? TRUE : FALSE;
075   }
076}
077