title: What is the most misleading method in the Java Base API?
body: <p>I was recently trying to convert a string literal into a <code>boolean</code>, when the method <a href="http://java.sun.com/javase/6/docs/api/java/lang/Boolean.html#getBoolean%28java.lang.String%29" rel="noreferrer"><code>boolean Boolean.getBoolean(String name)</code></a> popped out of the auto-complete window. There was also another method (<a href="http://java.sun.com/javase/6/docs/api/java/lang/Boolean.html#parseBoolean%28java.lang.String%29" rel="noreferrer"><code>boolean Boolean.parseBoolean(String s)</code></a>) appearing right after, which led me to search to find out what were the differences between these two, as they both seemed to do the same.</p>
  
  <p>It turns out that what <code>Boolean.getBoolean(String name)</code> really does is to <strong>check if there exists a <code>System</code> property (!) of the given name and if its value is <code>true</code></strong>. I think this is very misleading, as I'm definitely not expecting that a method of <code>Boolean</code> is actually making a call to <a href="http://java.sun.com/javase/6/docs/api/java/lang/System.html#getProperty%28java.lang.String%29" rel="noreferrer"><code>System.getProperty</code></a>, and just by looking at the method signature, it sure looks (at least to me) like it should be used to parse a <code>String</code> as a <code>boolean</code>. Sure, the javadoc states it clearly, but I still think the method has a misleading name and it is not in the right place. Other primitive type wrappers, such as <code>Integer</code> also have a similar method.</p>
  
  <p>Also, it doesn't seem to be a very useful method to belong in the base API, as I think it's not very common to have something like <code>-Darg=true</code>. Maybe it's a good question for a Java position interview: "What is the output of <code>Boolean.getBoolean("true")</code>?". I believe a more appropriate place for those methods would be in the <a href="http://java.sun.com/javase/6/docs/api/java/lang/System.html" rel="noreferrer"><code>System</code></a> class, e.g., <code>getPropertyAsBoolean</code>; but again, I still think it's unnecessary to have these methods in the base API. It'd make sense to have them in something like the <code>Properties</code> class, where it's very common to do this type of conversions.</p>
  
  <p><strong>What do you think of all this?</strong> Also, if there's another "awkward" method that you're aware of, please post it.</p>
  
  <p><strong>N.B.</strong> I know I can use <code>Boolean.valueOf</code> or <code>Boolean.parseBoolean</code> to convert a string literal into a <code>boolean</code>, but I'm just looking to discuss the API design.</p>