1 /*

     2  * Copyright 1994-2006 Sun Microsystems, Inc.  All Rights Reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 package java.lang;

    27 

    28 /**

    29  * The Boolean class wraps a value of the primitive type

    30  * {@code boolean} in an object. An object of type

    31  * {@code Boolean} contains a single field whose type is

    32  * {@code boolean}.

    33  * <p>

    34  * In addition, this class provides many methods for

    35  * converting a {@code boolean} to a {@code String} and a

    36  * {@code String} to a {@code boolean}, as well as other

    37  * constants and methods useful when dealing with a

    38  * {@code boolean}.

    39  *

    40  * @author  Arthur van Hoff

    41  * @since   JDK1.0

    42  */

    43 public final class Boolean implements java.io.Serializable,

    44                                       Comparable<Boolean>

    45 {

    46     /**

    47      * The {@code Boolean} object corresponding to the primitive

    48      * value {@code true}.

    49      */

    50     public static final Boolean TRUE = new Boolean(true);

    51 

    52     /**

    53      * The {@code Boolean} object corresponding to the primitive

    54      * value {@code false}.

    55      */

    56     public static final Boolean FALSE = new Boolean(false);

    57 

    58     /**

    59      * The Class object representing the primitive type boolean.

    60      *

    61      * @since   JDK1.1

    62      */

    63     public static final Class<Boolean> TYPE = Class.getPrimitiveClass("boolean");

    64 

    65     /**

    66      * The value of the Boolean.

    67      *

    68      * @serial

    69      */

    70     private final boolean value;

    71 

    72     /** use serialVersionUID from JDK 1.0.2 for interoperability */

    73     private static final long serialVersionUID = -3665804199014368530L;

    74 

    75     /**

    76      * Allocates a {@code Boolean} object representing the

    77      * {@code value} argument.

    78      *

    79      * <p><b>Note: It is rarely appropriate to use this constructor.

    80      * Unless a <i>new</i> instance is required, the static factory

    81      * {@link #valueOf(boolean)} is generally a better choice. It is

    82      * likely to yield significantly better space and time performance.</b>

    83      *

    84      * @param   value   the value of the {@code Boolean}.

    85      */

    86     public Boolean(boolean value) {

    87         this.value = value;

    88     }

    89 

    90     /**

    91      * Allocates a {@code Boolean} object representing the value

    92      * {@code true} if the string argument is not {@code null}

    93      * and is equal, ignoring case, to the string {@code "true"}.

    94      * Otherwise, allocate a {@code Boolean} object representing the

    95      * value {@code false}. Examples:<p>

    96      * {@code new Boolean("True")} produces a {@code Boolean} object

    97      * that represents {@code true}.<br>

    98      * {@code new Boolean("yes")} produces a {@code Boolean} object

    99      * that represents {@code false}.

   100      *

   101      * @param   s   the string to be converted to a {@code Boolean}.

   102      */

   103     public Boolean(String s) {

   104         this(toBoolean(s));

   105     }

   106 

   107     /**

   108      * Parses the string argument as a boolean.  The {@code boolean}

   109      * returned represents the value {@code true} if the string argument

   110      * is not {@code null} and is equal, ignoring case, to the string

   111      * {@code "true"}. <p>

   112      * Example: {@code Boolean.parseBoolean("True")} returns {@code true}.<br>

   113      * Example: {@code Boolean.parseBoolean("yes")} returns {@code false}.

   114      *

   115      * @param      s   the {@code String} containing the boolean

   116      *                 representation to be parsed

   117      * @return     the boolean represented by the string argument

   118      * @since 1.5

   119      */

   120     public static boolean parseBoolean(String s) {

   121         return toBoolean(s);

   122     }

   123 

   124     /**

   125      * Returns the value of this {@code Boolean} object as a boolean

   126      * primitive.

   127      *

   128      * @return  the primitive {@code boolean} value of this object.

   129      */

   130     public boolean booleanValue() {

   131         return value;

   132     }

   133 

   134     /**

   135      * Returns a {@code Boolean} instance representing the specified

   136      * {@code boolean} value.  If the specified {@code boolean} value

   137      * is {@code true}, this method returns {@code Boolean.TRUE};

   138      * if it is {@code false}, this method returns {@code Boolean.FALSE}.

   139      * If a new {@code Boolean} instance is not required, this method

   140      * should generally be used in preference to the constructor

   141      * {@link #Boolean(boolean)}, as this method is likely to yield

   142      * significantly better space and time performance.

   143      *

   144      * @param  b a boolean value.

   145      * @return a {@code Boolean} instance representing {@code b}.

   146      * @since  1.4

   147      */

   148     public static Boolean valueOf(boolean b) {

   149         return (b ? TRUE : FALSE);

   150     }

   151 

   152     /**

   153      * Returns a {@code Boolean} with a value represented by the

   154      * specified string.  The {@code Boolean} returned represents a

   155      * true value if the string argument is not {@code null}

   156      * and is equal, ignoring case, to the string {@code "true"}.

   157      *

   158      * @param   s   a string.

   159      * @return  the {@code Boolean} value represented by the string.

   160      */

   161     public static Boolean valueOf(String s) {

   162         return toBoolean(s) ? TRUE : FALSE;

   163     }

   164 

   165     /**

   166      * Returns a {@code String} object representing the specified

   167      * boolean.  If the specified boolean is {@code true}, then

   168      * the string {@code "true"} will be returned, otherwise the

   169      * string {@code "false"} will be returned.

   170      *

   171      * @param b the boolean to be converted

   172      * @return the string representation of the specified {@code boolean}

   173      * @since 1.4

   174      */

   175     public static String toString(boolean b) {

   176         return b ? "true" : "false";

   177     }

   178 

   179     /**

   180      * Returns a {@code String} object representing this Boolean's

   181      * value.  If this object represents the value {@code true},

   182      * a string equal to {@code "true"} is returned. Otherwise, a

   183      * string equal to {@code "false"} is returned.

   184      *

   185      * @return  a string representation of this object.

   186      */

   187     public String toString() {

   188         return value ? "true" : "false";

   189     }

   190 

   191     /**

   192      * Returns a hash code for this {@code Boolean} object.

   193      *

   194      * @return  the integer {@code 1231} if this object represents

   195      * {@code true}; returns the integer {@code 1237} if this

   196      * object represents {@code false}.

   197      */

   198     public int hashCode() {

   199         return value ? 1231 : 1237;

   200     }

   201 

   202     /**

   203      * Returns {@code true} if and only if the argument is not

   204      * {@code null} and is a {@code Boolean} object that

   205      * represents the same {@code boolean} value as this object.

   206      *

   207      * @param   obj   the object to compare with.

   208      * @return  {@code true} if the Boolean objects represent the

   209      *          same value; {@code false} otherwise.

   210      */

   211     public boolean equals(Object obj) {

   212         if (obj instanceof Boolean) {

   213             return value == ((Boolean)obj).booleanValue();

   214         }

   215         return false;

   216     }

   217 

   218     /**

   219      * Returns {@code true} if and only if the system property

   220      * named by the argument exists and is equal to the string

   221      * {@code "true"}. (Beginning with version 1.0.2 of the

   222      * Java<small><sup>TM</sup></small> platform, the test of

   223      * this string is case insensitive.) A system property is accessible

   224      * through {@code getProperty}, a method defined by the

   225      * {@code System} class.

   226      * <p>

   227      * If there is no property with the specified name, or if the specified

   228      * name is empty or null, then {@code false} is returned.

   229      *

   230      * @param   name   the system property name.

   231      * @return  the {@code boolean} value of the system property.

   232      * @see     java.lang.System#getProperty(java.lang.String)

   233      * @see     java.lang.System#getProperty(java.lang.String, java.lang.String)

   234      */

   235     public static boolean getBoolean(String name) {

   236         boolean result = false;

   237         try {

   238             result = toBoolean(System.getProperty(name));

   239         } catch (IllegalArgumentException e) {

   240         } catch (NullPointerException e) {

   241         }

   242         return result;

   243     }

   244 

   245     /**

   246      * Compares this {@code Boolean} instance with another.

   247      *

   248      * @param   b the {@code Boolean} instance to be compared

   249      * @return  zero if this object represents the same boolean value as the

   250      *          argument; a positive value if this object represents true

   251      *          and the argument represents false; and a negative value if

   252      *          this object represents false and the argument represents true

   253      * @throws  NullPointerException if the argument is {@code null}

   254      * @see     Comparable

   255      * @since  1.5

   256      */

   257     public int compareTo(Boolean b) {

   258         return (b.value == value ? 0 : (value ? 1 : -1));

   259     }

   260 

   261     private static boolean toBoolean(String name) {

   262         return ((name != null) && name.equalsIgnoreCase("true"));

   263     }

   264 }