You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jmeter.apache.org by fs...@apache.org on 2014/12/28 18:31:21 UTC
svn commit: r1648229 - in /jmeter/trunk/src/jorphan/org/apache/jorphan:
collections/Data.java collections/HashTree.java
collections/SearchByClass.java exec/KeyToolUtils.java
exec/SystemCommand.java logging/LoggingManager.java util/Converter.java
Author: fschumacher
Date: Sun Dec 28 17:31:20 2014
New Revision: 1648229
URL: http://svn.apache.org/r1648229
Log:
Bug 57193: Add param and return tags to javadoc
Bugzilla Id: 57193
Modified:
jmeter/trunk/src/jorphan/org/apache/jorphan/collections/Data.java
jmeter/trunk/src/jorphan/org/apache/jorphan/collections/HashTree.java
jmeter/trunk/src/jorphan/org/apache/jorphan/collections/SearchByClass.java
jmeter/trunk/src/jorphan/org/apache/jorphan/exec/KeyToolUtils.java
jmeter/trunk/src/jorphan/org/apache/jorphan/exec/SystemCommand.java
jmeter/trunk/src/jorphan/org/apache/jorphan/logging/LoggingManager.java
jmeter/trunk/src/jorphan/org/apache/jorphan/util/Converter.java
Modified: jmeter/trunk/src/jorphan/org/apache/jorphan/collections/Data.java
URL: http://svn.apache.org/viewvc/jmeter/trunk/src/jorphan/org/apache/jorphan/collections/Data.java?rev=1648229&r1=1648228&r2=1648229&view=diff
==============================================================================
--- jmeter/trunk/src/jorphan/org/apache/jorphan/collections/Data.java (original)
+++ jmeter/trunk/src/jorphan/org/apache/jorphan/collections/Data.java Sun Dec 28 17:31:20 2014
@@ -364,7 +364,7 @@ public class Data implements Serializabl
* @param rs
* ResultSet passed in from a database query
* @return a Data object
- * @throws java.sql.SQLException
+ * @throws java.sql.SQLException when database access errors occur
*/
public static Data getDataFromResultSet(ResultSet rs) throws SQLException {
ResultSetMetaData meta = rs.getMetaData();
@@ -566,6 +566,11 @@ public class Data implements Serializabl
/**
* Sets the data for every row in the column.
+ *
+ * @param colName
+ * name of the column
+ * @param value
+ * value to be set
*/
public void setColumnData(String colName, Object value) {
List<Object> list = this.getColumnAsObjectArray(colName);
Modified: jmeter/trunk/src/jorphan/org/apache/jorphan/collections/HashTree.java
URL: http://svn.apache.org/viewvc/jmeter/trunk/src/jorphan/org/apache/jorphan/collections/HashTree.java?rev=1648229&r1=1648228&r2=1648229&view=diff
==============================================================================
--- jmeter/trunk/src/jorphan/org/apache/jorphan/collections/HashTree.java (original)
+++ jmeter/trunk/src/jorphan/org/apache/jorphan/collections/HashTree.java Sun Dec 28 17:31:20 2014
@@ -76,6 +76,7 @@ public class HashTree implements Seriali
* Creates a new HashTree and adds the given object as a top-level node.
*
* @param key
+ * name of the new top-level node
*/
public HashTree(Object key) {
this(new HashMap<Object, HashTree>(), key);
@@ -191,7 +192,7 @@ public class HashTree implements Seriali
* Adds all the nodes and branches of the given tree to this tree. Is like
* merging two trees. Duplicates are ignored.
*
- * @param newTree
+ * @param newTree the tree to be added
*/
public void add(HashTree newTree) {
for (Object item : newTree.list()) {
@@ -216,6 +217,9 @@ public class HashTree implements Seriali
/**
* Creates a new HashTree and adds all the objects in the given array as
* top-level nodes in the tree.
+ *
+ * @param keys
+ * array with names for the new top-level nodes
*/
public HashTree(Object[] keys) {
data = new HashMap<Object, HashTree>();
@@ -397,10 +401,13 @@ public class HashTree implements Seriali
}
/**
- * Adds an key into the HashTree at the current level.
+ * Adds an key into the HashTree at the current level. If a HashTree exists
+ * for the key already, no new tree will be added
*
* @param key
* key to be added to HashTree
+ * @return newly generated tree, if no tree was found for the given key;
+ * existing key otherwise
*/
public HashTree add(Object key) {
if (!data.containsKey(key)) {
@@ -443,6 +450,7 @@ public class HashTree implements Seriali
* key to be added
* @param value
* value to be added as a key in the secondary node
+ * @return HashTree for which <code>value</code> is the key
*/
public HashTree add(Object key, Object value) {
return add(key).add(value);
@@ -544,6 +552,7 @@ public class HashTree implements Seriali
* a list of objects representing a path
* @param value
* Object to add as a node to bottom-most node
+ * @return HashTree for which <code>value</code> is the key
*/
public HashTree add(Collection<?> treePath, Object value) {
HashTree tree = addTreePath(treePath);
@@ -580,6 +589,7 @@ public class HashTree implements Seriali
*
* @param key
* Key used to find appropriate HashTree()
+ * @return the HashTree for <code>key</code>
*/
public HashTree getTree(Object key) {
return data.get(key);
@@ -762,6 +772,9 @@ public class HashTree implements Seriali
/**
* Finds the given current key, and replaces it with the given new key. Any
* tree structure found under the original key is moved to the new key.
+ *
+ * @param currentKey name of the key to be replaced
+ * @param newKey name of the new key
*/
public void replaceKey(Object currentKey, Object newKey) {
HashTree tree = getTree(currentKey);
@@ -817,7 +830,7 @@ public class HashTree implements Seriali
}
/**
- * Recurses down into the HashTree stucture using each subsequent key in the
+ * Recurses down into the HashTree structure using each subsequent key in the
* treePath argument, and returns an array of keys of the HashTree object at
* the end of the recursion. If the HashTree represented a file system, this
* would be like getting a list of all the files in a directory specified by
@@ -939,6 +952,8 @@ public class HashTree implements Seriali
* implementation will be given notification of each node visited.
*
* @see HashTreeTraverser
+ * @param visitor
+ * the visitor that wants to traverse the tree
*/
public void traverse(HashTreeTraverser visitor) {
for (Object item : list()) {
Modified: jmeter/trunk/src/jorphan/org/apache/jorphan/collections/SearchByClass.java
URL: http://svn.apache.org/viewvc/jmeter/trunk/src/jorphan/org/apache/jorphan/collections/SearchByClass.java?rev=1648229&r1=1648228&r2=1648229&view=diff
==============================================================================
--- jmeter/trunk/src/jorphan/org/apache/jorphan/collections/SearchByClass.java (original)
+++ jmeter/trunk/src/jorphan/org/apache/jorphan/collections/SearchByClass.java Sun Dec 28 17:31:20 2014
@@ -27,8 +27,8 @@ import java.util.Map;
/**
* Useful for finding all nodes in the tree that represent objects of a
* particular type. For instance, if your tree contains all strings, and a few
- * StringBuilder objects, you can use the SearchByClass traverser to find all the
- * StringBuilder objects in your tree.
+ * StringBuilder objects, you can use the SearchByClass traverser to find all
+ * the StringBuilder objects in your tree.
* <p>
* Usage is simple. Given a {@link HashTree} object "tree", and a SearchByClass
* object:
@@ -40,9 +40,9 @@ import java.util.Map;
* tree.traverse(searcher);
* Iterator iter = searcher.getSearchResults().iterator();
* while (iter.hasNext()) {
- * StringBuilder foundNode = (StringBuilder) iter.next();
- * HashTree subTreeOfFoundNode = searcher.getSubTree(foundNode);
- * // .... do something with node and subTree...
+ * StringBuilder foundNode = (StringBuilder) iter.next();
+ * HashTree subTreeOfFoundNode = searcher.getSubTree(foundNode);
+ * // .... do something with node and subTree...
* }
* </pre>
*
@@ -50,6 +50,8 @@ import java.util.Map;
* @see HashTreeTraverser
*
* @version $Revision$
+ * @param <T>
+ * Class that should be searched for
*/
public class SearchByClass<T> implements HashTreeTraverser {
private final List<T> objectsOfClass = new LinkedList<T>();
@@ -63,6 +65,7 @@ public class SearchByClass<T> implements
* for.
*
* @param searchClass
+ * class to be searched for
*/
public SearchByClass(Class<T> searchClass) {
this.searchClass = searchClass;
Modified: jmeter/trunk/src/jorphan/org/apache/jorphan/exec/KeyToolUtils.java
URL: http://svn.apache.org/viewvc/jmeter/trunk/src/jorphan/org/apache/jorphan/exec/KeyToolUtils.java?rev=1648229&r1=1648228&r2=1648229&view=diff
==============================================================================
--- jmeter/trunk/src/jorphan/org/apache/jorphan/exec/KeyToolUtils.java (original)
+++ jmeter/trunk/src/jorphan/org/apache/jorphan/exec/KeyToolUtils.java Sun Dec 28 17:31:20 2014
@@ -54,7 +54,7 @@ public class KeyToolUtils {
/**
* Where to find the keytool application.
- * If null, then keytool cannot be found.
+ * If <code>null</code>, then keytool cannot be found.
*/
private static final String KEYTOOL_PATH;
@@ -133,10 +133,10 @@ public class KeyToolUtils {
* @param alias the alias to use, not null
* @param password the password to use for the store and the key
* @param validity the validity period in days, greater than 0
- * @param dname the dname value, if omitted use "cn=JMeter Proxy (DO NOT TRUST)"
+ * @param dname the <em>distinguished name</em> value, if omitted use "cn=JMeter Proxy (DO NOT TRUST)"
* @param ext if not null, the extension (-ext) to add (e.g. "bc:c"). This requires Java 7.
*
- * @throws IOException
+ * @throws IOException if keytool was not configured or running keytool application fails
*/
public static void genkeypair(final File keystore, String alias, final String password, int validity, String dname, String ext)
throws IOException {
@@ -209,7 +209,7 @@ public class KeyToolUtils {
* @param password the password for keystore and keys
* @param validity the validity period in days, must be greater than 0
*
- * @throws IOException
+ * @throws IOException if keytool was not configured, running keytool application failed or copying the keys failed
*/
public static void generateProxyCA(File keystore, String password, int validity) throws IOException {
File caCert_crt = new File(ROOT_CACERT_CRT);
@@ -267,7 +267,7 @@ public class KeyToolUtils {
* @param host the host, e.g. jmeter.apache.org or *.apache.org; also used as the alias
* @param validity the validity period for the generated keypair
*
- * @throws IOException
+ * @throws IOException if keytool was not configured or running keytool application failed
*
*/
public static void generateHostCert(File keystore, String password, String host, int validity) throws IOException {
@@ -301,9 +301,14 @@ public class KeyToolUtils {
/**
* List the contents of a keystore
*
- * @param keystore the keystore file
- * @param storePass the keystore password
+ * @param keystore
+ * the keystore file
+ * @param storePass
+ * the keystore password
* @return the output from the command "keytool -list -v"
+ * @throws IOException
+ * if keytool was not configured or running keytool application
+ * failed
*/
public static String list(final File keystore, final String storePass) throws IOException {
final File workingDir = keystore.getParentFile();
@@ -349,14 +354,22 @@ public class KeyToolUtils {
/**
* Helper method to simplify chaining keytool commands.
*
- * @param command the command, not null
- * @param keystore the keystore, not nill
- * @param password the password used for keystore and key, not null
- * @param alias the alias, not null
- * @param input where to source input, may be null
- * @param output where to send output, may be null
- * @param parameters additional parameters to the command, may be null
+ * @param command
+ * the command, not null
+ * @param keystore
+ * the keystore, not nill
+ * @param password
+ * the password used for keystore and key, not null
+ * @param alias
+ * the alias, not null
+ * @param input
+ * where to source input, may be null
+ * @param output
+ * where to send output, may be null
+ * @param parameters
+ * additional parameters to the command, may be null
* @throws IOException
+ * if keytool is not configured or running it failed
*/
private static void keytool(String command, File keystore, String password, String alias,
InputStream input, OutputStream output, String ... parameters)
@@ -388,10 +401,20 @@ public class KeyToolUtils {
}
}
+ /**
+ * @return flag whether {@link KeyToolUtils#KEYTOOL_PATH KEYTOOL_PATH} is
+ * configured (is not <code>null</code>)
+ */
public static boolean haveKeytool() {
return KEYTOOL_PATH != null;
}
+ /**
+ * @return path to keytool binary
+ * @throws IOException
+ * when {@link KeyToolUtils#KEYTOOL_PATH KEYTOOL_PATH} is
+ * <code>null</code>
+ */
private static String getKeyToolPath() throws IOException {
if (KEYTOOL_PATH == null) {
throw new IOException("keytool application cannot be found");
Modified: jmeter/trunk/src/jorphan/org/apache/jorphan/exec/SystemCommand.java
URL: http://svn.apache.org/viewvc/jmeter/trunk/src/jorphan/org/apache/jorphan/exec/SystemCommand.java?rev=1648229&r1=1648228&r2=1648229&view=diff
==============================================================================
--- jmeter/trunk/src/jorphan/org/apache/jorphan/exec/SystemCommand.java (original)
+++ jmeter/trunk/src/jorphan/org/apache/jorphan/exec/SystemCommand.java Sun Dec 28 17:31:20 2014
@@ -118,8 +118,8 @@ public class SystemCommand {
/**
* @param arguments List of strings, not null
* @return return code
- * @throws InterruptedException
- * @throws IOException
+ * @throws InterruptedException when execution was interrupted
+ * @throws IOException when I/O error occurs while execution
*/
public int run(List<String> arguments) throws InterruptedException, IOException {
return run(arguments, stdin, stdout, stderr);
@@ -195,8 +195,8 @@ public class SystemCommand {
* @param arguments1 first command to run
* @param arguments2 second command to run
* @return exit status
- * @throws InterruptedException
- * @throws IOException
+ * @throws InterruptedException when execution gets interrupted
+ * @throws IOException when I/O error occurs while execution
*/
public int run(List<String> arguments1, List<String> arguments2) throws InterruptedException, IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(); // capture the intermediate output
Modified: jmeter/trunk/src/jorphan/org/apache/jorphan/logging/LoggingManager.java
URL: http://svn.apache.org/viewvc/jmeter/trunk/src/jorphan/org/apache/jorphan/logging/LoggingManager.java?rev=1648229&r1=1648228&r2=1648229&view=diff
==============================================================================
--- jmeter/trunk/src/jorphan/org/apache/jorphan/logging/LoggingManager.java (original)
+++ jmeter/trunk/src/jorphan/org/apache/jorphan/logging/LoggingManager.java Sun Dec 28 17:31:20 2014
@@ -26,6 +26,7 @@ import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.Iterator;
import java.util.Properties;
+import java.util.logging.LogManager;
import org.apache.avalon.excalibur.logger.LogKitLoggerManager;
import org.apache.avalon.framework.configuration.Configuration;
@@ -90,6 +91,8 @@ public final class LoggingManager {
* this as the default from "log_file", default "jmeter.log" The default
* priority is set from "log_level", with a default of INFO
*
+ * @param properties
+ * {@link Properties} to be used for initialization
*/
public static void initializeLogging(Properties properties) {
setFormat(properties);
@@ -202,6 +205,11 @@ public final class LoggingManager {
* Handle LOG_PRIORITY.category=priority and LOG_FILE.category=file_name
* properties. If the prefix is detected, then remove it to get the
* category.
+ *
+ * @param appProperties
+ * {@link Properties} that contain the
+ * {@link LoggingManager#LOG_PRIORITY LOG_PRIORITY} and
+ * {@link LoggingManager#LOG_FILE LOG_FILE} prefixed entries
*/
public static void setLoggingLevels(Properties appProperties) {
Iterator<?> props = appProperties.keySet().iterator();
Modified: jmeter/trunk/src/jorphan/org/apache/jorphan/util/Converter.java
URL: http://svn.apache.org/viewvc/jmeter/trunk/src/jorphan/org/apache/jorphan/util/Converter.java?rev=1648229&r1=1648228&r2=1648229&view=diff
==============================================================================
--- jmeter/trunk/src/jorphan/org/apache/jorphan/util/Converter.java (original)
+++ jmeter/trunk/src/jorphan/org/apache/jorphan/util/Converter.java Sun Dec 28 17:31:20 2014
@@ -35,8 +35,11 @@ public class Converter {
* Convert the given value object to an object of the given type
*
* @param value
+ * object to convert
* @param toType
- * @return Object
+ * type to convert object to
+ * @return converted object or original value if no conversion could be
+ * applied
*/
public static Object convert(Object value, Class<?> toType) {
if (value == null) {
@@ -74,11 +77,16 @@ public class Converter {
}
/**
- * Converts the given object to a calendar object. Defaults to the current
- * date if the given object can't be converted.
+ * Converts the given object to a calendar object. Defaults to the
+ * <code>defaultValue</code> if the given object can't be converted.
*
* @param date
- * @return Calendar
+ * object that should be converted to a {@link Calendar}
+ * @param defaultValue
+ * default value that will be returned if <code>date</code> can
+ * not be converted
+ * @return {@link Calendar} representing the given <code>date</code> or
+ * <code>defaultValue</code> if conversion failed
*/
public static Calendar getCalendar(Object date, Calendar defaultValue) {
Calendar cal = new GregorianCalendar();
@@ -115,14 +123,45 @@ public class Converter {
return cal;
}
+ /**
+ * Converts the given object to a calendar object. Defaults to a calendar
+ * using the current time if the given object can't be converted.
+ *
+ * @param o
+ * object that should be converted to a {@link Calendar}
+ * @return {@link Calendar} representing the given <code>o</code> or a new
+ * {@link GregorianCalendar} using the current time if conversion
+ * failed
+ */
public static Calendar getCalendar(Object o) {
return getCalendar(o, new GregorianCalendar());
}
+ /**
+ * Converts the given object to a {@link Date} object. Defaults to the
+ * current time if the given object can't be converted.
+ *
+ * @param date
+ * object that should be converted to a {@link Date}
+ * @return {@link Date} representing the given <code>date</code> or
+ * the current time if conversion failed
+ */
public static Date getDate(Object date) {
return getDate(date, Calendar.getInstance().getTime());
}
+ /**
+ * Converts the given object to a {@link Date} object. Defaults to the
+ * <code>defaultValue</code> if the given object can't be converted.
+ *
+ * @param date
+ * object that should be converted to a {@link Date}
+ * @param defaultValue
+ * default value that will be returned if <code>date</code> can
+ * not be converted
+ * @return {@link Date} representing the given <code>date</code> or
+ * <code>defaultValue</code> if conversion failed
+ */
public static Date getDate(Object date, Date defaultValue) {
Date val = null;
if (date instanceof java.util.Date) {
@@ -156,6 +195,17 @@ public class Converter {
return val;
}
+ /**
+ * Convert object to float, or <code>defaultValue</code> if conversion
+ * failed
+ *
+ * @param o
+ * object to convert
+ * @param defaultValue
+ * default value to use, when conversion failed
+ * @return converted float or <code>defaultValue</code> if conversion
+ * failed
+ */
public static float getFloat(Object o, float defaultValue) {
try {
if (o == null) {
@@ -170,10 +220,30 @@ public class Converter {
}
}
+ /**
+ * Convert object to float, or <code>0</code> if conversion
+ * failed
+ *
+ * @param o
+ * object to convert
+ * @return converted float or <code>0</code> if conversion
+ * failed
+ */
public static float getFloat(Object o) {
return getFloat(o, 0);
}
+ /**
+ * Convert object to double, or <code>defaultValue</code> if conversion
+ * failed
+ *
+ * @param o
+ * object to convert
+ * @param defaultValue
+ * default value to use, when conversion failed
+ * @return converted double or <code>defaultValue</code> if conversion
+ * failed
+ */
public static double getDouble(Object o, double defaultValue) {
try {
if (o == null) {
@@ -188,14 +258,43 @@ public class Converter {
}
}
+ /**
+ * Convert object to double, or <code>0</code> if conversion
+ * failed
+ *
+ * @param o
+ * object to convert
+ * @return converted double or <code>0</code> if conversion
+ * failed
+ */
public static double getDouble(Object o) {
return getDouble(o, 0);
}
+ /**
+ * Convert object to boolean, or <code>false</code> if conversion
+ * failed
+ *
+ * @param o
+ * object to convert
+ * @return converted boolean or <code>false</code> if conversion
+ * failed
+ */
public static boolean getBoolean(Object o) {
return getBoolean(o, false);
}
+ /**
+ * Convert object to boolean, or <code>defaultValue</code> if conversion
+ * failed
+ *
+ * @param o
+ * object to convert
+ * @param defaultValue
+ * default value to use, when conversion failed
+ * @return converted boolean or <code>defaultValue</code> if conversion
+ * failed
+ */
public static boolean getBoolean(Object o, boolean defaultValue) {
if (o == null) {
return defaultValue;
@@ -206,12 +305,14 @@ public class Converter {
}
/**
- * Convert object to integer, return defaultValue if object is not
- * convertible or is null.
+ * Convert object to integer, return <code>defaultValue</code> if object is not
+ * convertible or is <code>null</code>.
*
* @param o
+ * object to convert
* @param defaultValue
- * @return int
+ * default value to be used when no conversion can be done
+ * @return converted int or default value if conversion failed
*/
public static int getInt(Object o, int defaultValue) {
try {
@@ -227,10 +328,28 @@ public class Converter {
}
}
+ /**
+ * Convert object to char, or ' ' if no conversion can
+ * be applied
+ *
+ * @param o
+ * object to convert
+ * @return converted char or ' ' if conversion failed
+ */
public static char getChar(Object o) {
return getChar(o, ' ');
}
+ /**
+ * Convert object to char, or <code>defaultValue</code> if no conversion can
+ * be applied
+ *
+ * @param o
+ * object to convert
+ * @param defaultValue
+ * default value to use, when conversion failed
+ * @return converted char or <code>defaultValue</code> if conversion failed
+ */
public static char getChar(Object o, char defaultValue) {
try {
if (o == null) {
@@ -255,23 +374,27 @@ public class Converter {
}
/**
- * Converts object to an integer, defaults to 0 if object is not convertible
- * or is null.
+ * Converts object to an integer, defaults to <code>0</code> if object is
+ * not convertible or is <code>null</code>.
*
* @param o
- * @return int
+ * object to convert
+ * @return converted int, or <code>0</code> if conversion failed
*/
public static int getInt(Object o) {
return getInt(o, 0);
}
/**
- * Converts object to a long, return defaultValue if object is not
- * convertible or is null.
+ * Converts object to a long, return <code>defaultValue</code> if object is
+ * not convertible or is <code>null</code>.
*
* @param o
+ * object to convert
* @param defaultValue
- * @return long
+ * default value to use, when conversion failed
+ * @return converted long or <code>defaultValue</code> when conversion
+ * failed
*/
public static long getLong(Object o, long defaultValue) {
try {
@@ -288,16 +411,28 @@ public class Converter {
}
/**
- * Converts object to a long, defaults to 0 if object is not convertible or
- * is null
+ * Converts object to a long, defaults to <code>0</code> if object is not
+ * convertible or is <code>null</code>
*
* @param o
- * @return long
+ * object to convert
+ * @return converted long or <code>0</code> if conversion failed
*/
public static long getLong(Object o) {
return getLong(o, 0);
}
+ /**
+ * Format a date using a given pattern
+ *
+ * @param date
+ * date to format
+ * @param pattern
+ * pattern to use for formatting
+ * @return formatted date, or empty string if date was <code>null</code>
+ * @throws IllegalArgumentException
+ * when <code>pattern</code> is invalid
+ */
public static String formatDate(Date date, String pattern) {
if (date == null) {
return "";
@@ -306,6 +441,17 @@ public class Converter {
return format.format(date);
}
+ /**
+ * Format a date using a given pattern
+ *
+ * @param date
+ * date to format
+ * @param pattern
+ * pattern to use for formatting
+ * @return formatted date, or empty string if date was <code>null</code>
+ * @throws IllegalArgumentException
+ * when <code>pattern</code> is invalid
+ */
public static String formatDate(java.sql.Date date, String pattern) {
if (date == null) {
return "";
@@ -314,14 +460,47 @@ public class Converter {
return format.format(date);
}
+ /**
+ * Format a date using a given pattern
+ *
+ * @param date
+ * date to format
+ * @param pattern
+ * pattern to use for formatting
+ * @return formatted date, or empty string if date was <code>null</code>
+ * @throws IllegalArgumentException
+ * when <code>pattern</code> is invalid
+ */
public static String formatDate(String date, String pattern) {
return formatDate(getCalendar(date, null), pattern);
}
+ /**
+ * Format a date using a given pattern
+ *
+ * @param date
+ * date to format
+ * @param pattern
+ * pattern to use for formatting
+ * @return formatted date, or empty string if date was <code>null</code>
+ * @throws IllegalArgumentException
+ * when <code>pattern</code> is invalid
+ */
public static String formatDate(Calendar date, String pattern) {
return formatCalendar(date, pattern);
}
+ /**
+ * Format a calendar using a given pattern
+ *
+ * @param date
+ * calendar to format
+ * @param pattern
+ * pattern to use for formatting
+ * @return formatted date, or empty string if date was <code>null</code>
+ * @throws IllegalArgumentException
+ * when <code>pattern</code> is invalid
+ */
public static String formatCalendar(Calendar date, String pattern) {
if (date == null) {
return "";
@@ -331,11 +510,15 @@ public class Converter {
}
/**
- * Converts object to a String, return defaultValue if object is null.
+ * Converts object to a String, return <code>defaultValue</code> if object
+ * is <code>null</code>.
*
* @param o
+ * object to convert
* @param defaultValue
- * @return String
+ * default value to use when conversion failed
+ * @return converted String or <code>defaultValue</code> when conversion
+ * failed
*/
public static String getString(Object o, String defaultValue) {
if (o == null) {
@@ -344,6 +527,15 @@ public class Converter {
return o.toString();
}
+ /**
+ * Replace newlines "\n" with <code>insertion</code>
+ *
+ * @param v
+ * String in which the newlines should be replaced
+ * @param insertion
+ * new string which should be used instead of "\n"
+ * @return new string with newlines replaced by <code>insertion</code>
+ */
public static String insertLineBreaks(String v, String insertion) {
if (v == null) {
return "";
@@ -365,12 +557,22 @@ public class Converter {
* Converts object to a String, defaults to empty string if object is null.
*
* @param o
- * @return String
+ * object to convert
+ * @return converted String or empty string when conversion failed
*/
public static String getString(Object o) {
return getString(o, "");
}
+ /**
+ * Converts an object to a {@link File}
+ *
+ * @param o
+ * object to convert (must be a {@link String} or a {@link File})
+ * @return converted file
+ * @throws IllegalArgumentException
+ * when object can not be converted
+ */
public static File getFile(Object o){
if (o instanceof File) {
return (File) o;