HHH-2761 : null and empty string consistency in PropertiesHelper (javadocs)

git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@12889 1b8cb986-b30d-0410-93ca-fae66ebed9b2

core/src/main/java/org/hibernate/util/PropertiesHelper.java

@@ -7,16 +7,48 @@ import java.util.Properties;
 import java.util.StringTokenizer;
 import java.util.Iterator;
 
+/**
+ * Collection of helper methods for dealing with {@link java.util.Properties}
+ * objects.
+ *
+ * @author Gavin King
+ * @author Steve Ebersole
+ */
 public final class PropertiesHelper {
 
 	private static final String PLACEHOLDER_START = "${";
 
+	/**
+	 * Disallow instantiation
+	 */
+	private PropertiesHelper() {
+	}
+
+	/**
+	 * Get a property value as a string.
+	 *
+	 * @see #extractPropertyValue(String, java.util.Properties)
+	 *
+	 * @param propertyName The name of the property for which to retrieve value
+	 * @param properties The properties object
+	 * @param defaultValue The default property value to use.
+	 * @return The property value; may be null.
+	 */
 	public static String getString(String propertyName, Properties properties, String defaultValue) {
 		String value = extractPropertyValue( propertyName, properties );
 		return value == null ? defaultValue : value;
 	}
 
-	private static String extractPropertyValue(String propertyName, Properties properties) {
+	/**
+	 * Extract a property value by name from the given properties object.
+	 * <p/>
+	 * Both <tt>null</tt> and <tt>empty string</tt> are viewed as the same, and return null.
+	 *
+	 * @param propertyName The name of the property for which to extract value
+	 * @param properties The properties object
+	 * @return The property value; may be null.
+	 */
+	public static String extractPropertyValue(String propertyName, Properties properties) {
 		String value = properties.getProperty( propertyName );
 		if ( value == null ) {
 			return null;
@@ -28,25 +60,85 @@ public final class PropertiesHelper {
 		return value;
 	}
 
-	public static boolean getBoolean(String property, Properties properties) {
+	/**
-		return getBoolean( property, properties, false );
+	 * Get a property value as a boolean.  Shorthand for calling
+	 * {@link #getBoolean(String, java.util.Properties, boolean)} with <tt>false</tt>
+	 * as the default value.
+	 *
+	 * @param propertyName The name of the property for which to retrieve value
+	 * @param properties The properties object
+	 * @return The property value.
+	 */
+	public static boolean getBoolean(String propertyName, Properties properties) {
+		return getBoolean( propertyName, properties, false );
 	}
 
+	/**
+	 * Get a property value as a boolean.
+	 * <p/>
+	 * First, the string value is extracted, and then {@link Boolean#valueOf(String)} is
+	 * used to determine the correct boolean value.
+	 *
+	 * @see #extractPropertyValue(String, java.util.Properties)
+	 *
+	 * @param propertyName The name of the property for which to retrieve value
+	 * @param properties The properties object
+	 * @param defaultValue The default property value to use.
+	 * @return The property value.
+	 */
 	public static boolean getBoolean(String propertyName, Properties properties, boolean defaultValue) {
 		String value = extractPropertyValue( propertyName, properties );
 		return value == null ? defaultValue : Boolean.valueOf( value ).booleanValue();
 	}
 
+	/**
+	 * Get a property value as an int.
+	 * <p/>
+	 * First, the string value is extracted, and then {@link Integer#parseInt(String)} is
+	 * used to determine the correct int value for any non-null property values.
+	 *
+	 * @see #extractPropertyValue(String, java.util.Properties)
+	 *
+	 * @param propertyName The name of the property for which to retrieve value
+	 * @param properties The properties object
+	 * @param defaultValue The default property value to use.
+	 * @return The property value.
+	 */
 	public static int getInt(String propertyName, Properties properties, int defaultValue) {
 		String value = extractPropertyValue( propertyName, properties );
 		return value == null ? defaultValue : Integer.parseInt( value );
 	}
 
+	/**
+	 * Get a property value as an Integer.
+	 * <p/>
+	 * First, the string value is extracted, and then {@link Integer#valueOf(String)} is
+	 * used to determine the correct boolean value for any non-null property values.
+	 *
+	 * @see #extractPropertyValue(String, java.util.Properties)
+	 *
+	 * @param propertyName The name of the property for which to retrieve value
+	 * @param properties The properties object
+	 * @return The property value; may be null.
+	 */
 	public static Integer getInteger(String propertyName, Properties properties) {
 		String value = extractPropertyValue( propertyName, properties );
 		return value == null ? null : Integer.valueOf( value );
 	}
 
+	/**
+	 * Constructs a map from a property value.
+	 * <p/>
+	 * The exact behavior here is largely dependant upon what is passed in as
+	 * the delimiter.
+	 *
+	 * @see #extractPropertyValue(String, java.util.Properties)
+	 *
+	 * @param propertyName The name of the property for which to retrieve value
+	 * @param delim The string defining tokens used as both entry and key/value delimiters.
+	 * @param properties The properties object
+	 * @return The resulting map; never null, though perhaps empty.
+	 */
 	public static Map toMap(String propertyName, String delim, Properties properties) {
 		Map map = new HashMap();
 		String value = extractPropertyValue( propertyName, properties );
@@ -59,11 +151,32 @@ public final class PropertiesHelper {
 		return map;
 	}
 
+	/**
+	 * Get a property value as a string array.
+	 *
+	 * @see #extractPropertyValue(String, java.util.Properties)
+	 * @see #toStringArray(String, String)
+	 *
+	 * @param propertyName The name of the property for which to retrieve value
+	 * @param delim The delimiter used to separate individual array elements.
+	 * @param properties The properties object
+	 * @return The array; never null, though may be empty.
+	 */
 	public static String[] toStringArray(String propertyName, String delim, Properties properties) {
 		return toStringArray( extractPropertyValue( propertyName, properties ), delim );
 	}
 
+	/**
+	 * Convert a string to an array of strings.  The assumption is that
+	 * the individual array elements are delimited in the source stringForm
+	 * param by the delim param.
+	 *
+	 * @param stringForm The string form of the string array.
+	 * @param delim The delimiter used to separate individual array elements.
+	 * @return The array; never null, though may be empty.
+	 */
 	public static String[] toStringArray(String stringForm, String delim) {
+		// todo : move to StringHelper?
 		if ( stringForm != null ) {
 			return StringHelper.split( delim, stringForm );
 		}
@@ -87,6 +200,11 @@ public final class PropertiesHelper {
 		return clone;
 	}
 
+	/**
+	 * Handles interpolation processing for all entries in a properties object.
+	 *
+	 * @param properties The properties object.
+	 */
 	public static void resolvePlaceHolders(Properties properties) {
 		Iterator itr = properties.entrySet().iterator();
 		while ( itr.hasNext() ) {
@@ -106,6 +224,12 @@ public final class PropertiesHelper {
 		}
 	}
 
+	/**
+	 * Handles interpolation processing for a single property.
+	 *
+	 * @param property The property value to be processed for interpolation.
+	 * @return The (possibly) interpolated property value.
+	 */
 	public static String resolvePlaceHolder(String property) {
 		if ( property.indexOf( PLACEHOLDER_START ) < 0 ) {
 			return property;
@@ -150,8 +274,4 @@ public final class PropertiesHelper {
 			return null;
 		}
 	}
-
-
-	private PropertiesHelper() {
-	}
 }