flink-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fhue...@apache.org
Subject flink git commit: [FLINK-2654] Add JavaDoc to ParameterTool class
Date Fri, 11 Sep 2015 14:30:35 GMT
Repository: flink
Updated Branches:
  refs/heads/release-0.10.0-milestone-1 84d8767be -> 07a597927


[FLINK-2654] Add JavaDoc to ParameterTool class

This closes #1116


Project: http://git-wip-us.apache.org/repos/asf/flink/repo
Commit: http://git-wip-us.apache.org/repos/asf/flink/commit/07a59792
Tree: http://git-wip-us.apache.org/repos/asf/flink/tree/07a59792
Diff: http://git-wip-us.apache.org/repos/asf/flink/diff/07a59792

Branch: refs/heads/release-0.10.0-milestone-1
Commit: 07a5979275fa988f9bbce1bddc5bda4287bef4c5
Parents: 84d8767
Author: Behrouz Derakhshan <behrouz.derakhshan@gmail.com>
Authored: Thu Sep 10 16:02:51 2015 +0200
Committer: Fabian Hueske <fhueske@apache.org>
Committed: Fri Sep 11 16:30:20 2015 +0200

----------------------------------------------------------------------
 .../flink/api/java/utils/ParameterTool.java     | 119 ++++++++++++++++++-
 1 file changed, 114 insertions(+), 5 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/flink/blob/07a59792/flink-java/src/main/java/org/apache/flink/api/java/utils/ParameterTool.java
----------------------------------------------------------------------
diff --git a/flink-java/src/main/java/org/apache/flink/api/java/utils/ParameterTool.java b/flink-java/src/main/java/org/apache/flink/api/java/utils/ParameterTool.java
index b60a559..09e6442 100644
--- a/flink-java/src/main/java/org/apache/flink/api/java/utils/ParameterTool.java
+++ b/flink-java/src/main/java/org/apache/flink/api/java/utils/ParameterTool.java
@@ -35,6 +35,9 @@ import java.util.HashMap;
 import java.util.Map;
 import java.util.Properties;
 
+/**
+ * This class provides simple utility methods for reading and parsing program arguments from
different sources
+ */
 public class ParameterTool extends ExecutionConfig.GlobalJobParameters implements Serializable,
Cloneable {
 	private static final long serialVersionUID = 1L;
 
@@ -44,6 +47,16 @@ public class ParameterTool extends ExecutionConfig.GlobalJobParameters
implement
 
 	// ------------------ Constructors ------------------------
 
+	/**
+	 * Returns {@link ParameterTool} for the given arguments. The arguments are keys followed
by values.
+	 * Keys have to start with '-' or '--'
+	 * <p>
+	 * <strong>Example arguments:</strong>
+	 * --key1 value1 --key2 value2 -key3 value3
+	 *
+	 * @param args Input array arguments
+	 * @return A {@link ParameterTool}
+	 */
 	public static ParameterTool fromArgs(String[] args) {
 		Map<String, String> map = new HashMap<String, String>(args.length / 2);
 
@@ -124,6 +137,15 @@ public class ParameterTool extends ExecutionConfig.GlobalJobParameters
implement
 		return fromMap(map);
 	}
 
+	/**
+	 * Returns {@link ParameterTool} for the given {@link Properties} file
+	 *
+	 * @param path Path to the properties file
+	 * @return A {@link ParameterTool}
+	 * @throws IOException If the file does not exist
+	 *
+	 * @see Properties
+	 */
 	public static ParameterTool fromPropertiesFile(String path) throws IOException {
 		File propertiesFile = new File(path);
 		if(!propertiesFile.exists()) {
@@ -136,15 +158,36 @@ public class ParameterTool extends ExecutionConfig.GlobalJobParameters
implement
 		return fromMap((Map)props);
 	}
 
+	/**
+	 * Returns {@link ParameterTool} for the given map
+	 *
+	 * @param map A map of arguments. Both Key and Value have to be Strings
+	 * @return A {@link ParameterTool}
+	 */
 	public static ParameterTool fromMap(Map<String, String> map) {
 		Preconditions.checkNotNull(map, "Unable to initialize from empty map");
 		return new ParameterTool(map);
 	}
 
+	/**
+	 * Returns {@link ParameterTool} from the system properties.
+	 * Example on how to pass system properties:
+	 * -Dkey1=value1 -Dkey2=value2
+	 *
+	 * @return A {@link ParameterTool}
+	 */
 	public static ParameterTool fromSystemProperties() {
 		return fromMap((Map) System.getProperties());
 	}
 
+	/**
+	 * Returns {@link ParameterTool} for the arguments parsed by {@link GenericOptionsParser}
+	 *
+	 * @param args Input array arguments. It should be parsable by {@link GenericOptionsParser}
+	 * @return A {@link ParameterTool}
+	 * @throws IOException If arguments cannot be parsed by {@link GenericOptionsParser}
+	 * @see GenericOptionsParser
+	 */
 	public static ParameterTool fromGenericOptionsParser(String[] args) throws IOException {
 		Option[] options = new GenericOptionsParser(args).getCommandLine().getOptions();
 		Map<String, String> map = new HashMap<String, String>();
@@ -166,15 +209,26 @@ public class ParameterTool extends ExecutionConfig.GlobalJobParameters
implement
 
 	// ------------------ Get data from the util ----------------
 
+	/**
+	 * Returns number of parameters in {@link ParameterTool}.
+	 */
 	public int getNumberOfParameters() {
 		return data.size();
 	}
 
+	/**
+	 * Returns the String value for the given key.
+	 * If the key does not exist it will return null.
+	 */
 	public String get(String key) {
 		addToDefaults(key, null);
 		return data.get(key);
 	}
 
+	/**
+	 * Returns the String value for the given key.
+	 * If the key does not exist it will throw a {@link RuntimeException}.
+	 */
 	public String getRequired(String key) {
 		addToDefaults(key, null);
 		String value = get(key);
@@ -185,6 +239,10 @@ public class ParameterTool extends ExecutionConfig.GlobalJobParameters
implement
 	}
 
 
+	/**
+	 * Returns the String value for the given key.
+	 * If the key does not exist it will return the given default value.
+	 */
 	public String get(String key, String defaultValue) {
 		addToDefaults(key, defaultValue);
 		String value = get(key);
@@ -196,7 +254,7 @@ public class ParameterTool extends ExecutionConfig.GlobalJobParameters
implement
 	}
 
 	/**
-	 * Check if value is set
+	 * Check if value is set.
 	 */
 	public boolean has(String value) {
 		addToDefaults(value, null);
@@ -205,12 +263,20 @@ public class ParameterTool extends ExecutionConfig.GlobalJobParameters
implement
 
 	// -------------- Integer
 
+	/**
+	 * Returns the Integer value for the given key.
+	 * The method fails if the key does not exist or the value is not an Integer.
+	 */
 	public int getInt(String key) {
 		addToDefaults(key, null);
 		String value = getRequired(key);
 		return Integer.valueOf(value);
 	}
 
+	/**
+	 * Returns the Integer value for the given key. If the key does not exists it will return
the default value given.
+	 * The method fails if the value is not an Integer.
+	 */
 	public int getInt(String key, int defaultValue) {
 		addToDefaults(key, Integer.toString(defaultValue));
 		String value = get(key);
@@ -222,11 +288,10 @@ public class ParameterTool extends ExecutionConfig.GlobalJobParameters
implement
 	}
 
 	// -------------- LONG
+
 	/**
-	 * Get long value.
-	 * The method fails if the key is not specified.
-	 * @param key Name of the key
-	 * @return
+	 * Returns the Long value for the given key.
+	 * The method fails if the key does not exist.
 	 */
 	public long getLong(String key) {
 		addToDefaults(key, null);
@@ -234,6 +299,10 @@ public class ParameterTool extends ExecutionConfig.GlobalJobParameters
implement
 		return Long.valueOf(value);
 	}
 
+	/**
+	 * Returns the Long value for the given key. If the key does not exists it will return the
default value given.
+	 * The method fails if the value is not a Long.
+	 */
 	public long getLong(String key, long defaultValue) {
 		addToDefaults(key, Long.toString(defaultValue));
 		String value = get(key);
@@ -246,12 +315,20 @@ public class ParameterTool extends ExecutionConfig.GlobalJobParameters
implement
 
 	// -------------- FLOAT
 
+	/**
+	 * Returns the Float value for the given key.
+	 * The method fails if the key does not exist.
+	 */
 	public float getFloat(String key) {
 		addToDefaults(key, null);
 		String value = getRequired(key);
 		return Float.valueOf(value);
 	}
 
+	/**
+	 * Returns the Float value for the given key. If the key does not exists it will return
the default value given.
+	 * The method fails if the value is not a Float.
+	 */
 	public float getFloat(String key, float defaultValue) {
 		addToDefaults(key, Float.toString(defaultValue));
 		String value = get(key);
@@ -264,12 +341,20 @@ public class ParameterTool extends ExecutionConfig.GlobalJobParameters
implement
 
 	// -------------- DOUBLE
 
+	/**
+	 * Returns the Double value for the given key.
+	 * The method fails if the key does not exist.
+	 */
 	public double getDouble(String key) {
 		addToDefaults(key, null);
 		String value = getRequired(key);
 		return Double.valueOf(value);
 	}
 
+	/**
+	 * Returns the Double value for the given key. If the key does not exists it will return
the default value given.
+	 * The method fails if the value is not a Double.
+	 */
 	public double getDouble(String key, double defaultValue) {
 		addToDefaults(key, Double.toString(defaultValue));
 		String value = get(key);
@@ -300,6 +385,11 @@ public class ParameterTool extends ExecutionConfig.GlobalJobParameters
implement
 
 	// ------------------------- Export to different targets -------------------------
 
+	/**
+	 * Returns a {@link Configuration} object from this {@link ParameterTool}
+	 *
+	 * @return A {@link Configuration}
+	 */
 	public Configuration getConfiguration() {
 		Configuration conf = new Configuration();
 		for(Map.Entry<String, String> entry: data.entrySet()) {
@@ -308,6 +398,11 @@ public class ParameterTool extends ExecutionConfig.GlobalJobParameters
implement
 		return conf;
 	}
 
+	/**
+	 * Returns a {@link Properties} object from this {@link ParameterTool}
+	 *
+	 * @return A {@link Properties}
+	 */
 	public Properties getProperties() {
 		Properties props = new Properties();
 		props.putAll(this.data);
@@ -327,6 +422,14 @@ public class ParameterTool extends ExecutionConfig.GlobalJobParameters
implement
 		createPropertiesFile(pathToFile, true);
 	}
 
+	/**
+	 * Create a properties file with all the known parameters (call after the last get*() call).
+	 * Set the default value, if overwrite is true.
+	 *
+	 * @param pathToFile Location of the default properties file.
+	 * @param overwrite Boolean flag indicating whether or not to overwrite the file
+	 * @throws IOException If overwrite is not allowed and the file exists
+	 */
 	public void createPropertiesFile(String pathToFile, boolean overwrite) throws IOException
{
 		File file = new File(pathToFile);
 		if(file.exists()) {
@@ -350,6 +453,12 @@ public class ParameterTool extends ExecutionConfig.GlobalJobParameters
implement
 
 	// ------------------------- Interaction with other ParameterUtils -------------------------
 
+	/**
+	 * Merges two {@link ParameterTool}
+	 *
+	 * @param other Other {@link ParameterTool} object
+	 * @return The Merged {@link ParameterTool}
+	 */
 	public ParameterTool mergeWith(ParameterTool other) {
 		ParameterTool ret = new ParameterTool(this.data);
 		ret.data.putAll(other.data);


Mime
View raw message