Java Boolean's getBoolean: Useful Albeit Imperfect

The Boolean.getBoolean(String) method is a static method that can be useful now and then. It's very easy to confuse this method as one that somehow returns the appropriate Boolean based on the provided String (such as what Boolean.valueOf(String) and Boolean.parseBoolean(String) do), but the Javadoc documentation for this method explains what it really does: the Boolean.getBoolean(String) method "Returns true if and only if the system property named by the argument exists and is equal to the string 'true'."

The Boolean.getBoolean(String) method provides developers with a method for determining if a particular property is set to "true." It only returns "true" if the property is defined and the value it is defined to is some form of "true" where the case of "true" does not matter. The case of the property name itself is case sensitive, but its value ("true", "TRUE", "trUE", "TRue", etc.) is case insensitive.

The following Java code demonstrates Boolean.getBoolean(String) in action.

DemonstrateBooleanGetBoolean.java

package dustin.examples;

import static java.lang.System.out;

/**
* Demonstrate the usefulness of Boolean.getBoolean(String) despite its naming
* issue.
*/
public class DemonstrateBooleanGetBoolean
{
  /**
   * Main function for executing examples demonstrating use and effects of
   * Boolean.getBoolean(String).
   */
  public static void main(final String[] arguments)
  {
     final String basicPropertyName = "i.am.here";
     final String basicUppercasePropertyName = basicPropertyName.toUpperCase();
     final String wereHereProperty = "were.here.property";
     final String wasHereProperty = "was.here.property";

     out.println(basicPropertyName + " is " + Boolean.getBoolean(basicPropertyName));
     out.println(basicUppercasePropertyName + " is " + Boolean.getBoolean(basicUppercasePropertyName));

     out.println(wereHereProperty + " is " + Boolean.getBoolean(wereHereProperty));
     out.println(wasHereProperty + " is " + Boolean.getBoolean(wasHereProperty));
    
     if (Boolean.getBoolean("i.am.set"))
     {
        System.out.println("I'm set!!!");
     }
     else
     {
        System.out.println("I'm NOT set!!!");
     }
  }
}

By executing the above class with properties specified via the Java application launcher's -D option, the nuances of Boolean.getBoolean(String) are demonstrated. The results contained in the next screen snapshot indicate that Boolean.getBoolean(String) does indeed return true when a particular property name is specified and is defined with a String value of "true" with any case for the four letters making up "true." On the other hand, changing the case of the property name does affect the results of Boolean.getBoolean(String). In other words, while "true" and "TRUE" are the same from a property value perspective, "i.am.here" and "I.AM.HERE" are completely different property names from a property name perspective.



There are several uses for the Boolean.getBoolean(String) method including conditional runtime logic based on whether a parameter is set or not. The blog post Please use Boolean.getBoolean(SOME_FLAG_KEY) covers this use in more detail.

Although this method is highly useful, there is no question that it not as well named as it might have been. Several blog posts express Java developers' disappointment with this API naming choice and hosting class for the static method: I Fell in the Trap of Boolean.getBoolean() [October 2007], Java API Pitfalls: Boolean.getBoolean(String) [October 2005], Some Fun with Boolean.getBoolean(String) [July 2009], Boolean.getBoolean not what you think it is [October 2003], and Ever Been Busted by Boolean.getBoolean(String) [this month!].

Conclusion

I find Boolean.getBoolean(String) to be a highly useful method at times, but I also agree with other Java developers cited above that it is not one of the better API decisions. As several others have suggested, it seems like it might have fit better in the java.lang.System class and I would have preferred a method name such as "isPropertyTrue(String)". That being said, once one is aware of this subtlety and the distinction between Boolean.getBoolean(String) and Boolean.valueOf(String) (or Boolean.parseBoolean(String), available since J2SE 5), both methods can be applied appropriately and be highly valuable in certain situations.