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;