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
045   /** Explicitly set to <jk>true</jk>. */
046   TRUE,
047
048   /** Explicitly set to <jk>false</jk>. */
049   FALSE,
050
051   /** Not set - should inherit from parent or use default value. */
052   UNSET;
053
054   /**
055    * Converts this TriState to a boolean value.
056    *
057    * <p>
058    * If this is {@link #UNSET}, returns the provided default value.
059    *
060    * @param defaultValue The default value to use if this is {@link #UNSET}.
061    * @return <jk>true</jk> if this is {@link #TRUE}, <jk>false</jk> if this is {@link #FALSE},
062    *    or the provided default if this is {@link #UNSET}.
063    */
064   public boolean toBoolean(boolean defaultValue) {
065      return this == UNSET ? defaultValue : (this == TRUE);
066   }
067
068   /**
069    * Converts a boolean to a TriState.
070    *
071    * @param value The boolean value.
072    * @return {@link #TRUE} if <jk>true</jk>, {@link #FALSE} if <jk>false</jk>.
073    */
074   public static TriState fromBoolean(boolean value) {
075      return value ? TRUE : FALSE;
076   }
077}
078