diff --git a/src/main/java/com/typesafe/config/Config.java b/src/main/java/com/typesafe/config/Config.java
index 8a32501f..56ebeb93 100644
--- a/src/main/java/com/typesafe/config/Config.java
+++ b/src/main/java/com/typesafe/config/Config.java
@@ -4,11 +4,33 @@ import java.util.concurrent.TimeUnit;
import com.typesafe.config.impl.ConfigImpl;
+/**
+ * This class holds some global static methods for the config package.
+ */
public final class Config {
+ /**
+ * Loads a configuration object.
+ *
+ * @param configConfig
+ * configuration for the configuration.
+ * @return a configuration object
+ */
public static ConfigObject load(ConfigConfig configConfig) {
return ConfigImpl.loadConfig(configConfig);
}
+ /**
+ * Loads a configuration for the given root path. The root path should be a
+ * short word that scopes the package being configured; typically it's the
+ * package name or something similar. System properties overriding values in
+ * the configuration will have to be prefixed with the root path. The root
+ * path may have periods in it if you like but other punctuation or
+ * whitespace will probably cause you headaches. Example root paths: "akka",
+ * "sbt", "jsoup", "heroku", "mongo", etc.
+ * @param rootPath
+ * the configuration "domain"
+ * @return configuration object for the requested root path
+ */
public static ConfigObject load(String rootPath) {
return ConfigImpl.loadConfig(new ConfigConfig(rootPath));
}
diff --git a/src/main/java/com/typesafe/config/ConfigConfig.java b/src/main/java/com/typesafe/config/ConfigConfig.java
index 02bc712a..cff7119f 100644
--- a/src/main/java/com/typesafe/config/ConfigConfig.java
+++ b/src/main/java/com/typesafe/config/ConfigConfig.java
@@ -7,10 +7,22 @@ public final class ConfigConfig {
private String rootPath;
+ /**
+ * Creates a new configuration configuration.
+ *
+ * @param rootPath
+ * the root path as described in Config.load() docs
+ */
public ConfigConfig(String rootPath) {
this.rootPath = rootPath;
}
+ /**
+ * Get the configured root path. This method would be used by code
+ * implementing a configuration backend; don't worry about it.
+ *
+ * @return the root path
+ */
public String rootPath() {
return rootPath;
}
diff --git a/src/main/java/com/typesafe/config/ConfigException.java b/src/main/java/com/typesafe/config/ConfigException.java
index 316d0ee4..33dd56d6 100644
--- a/src/main/java/com/typesafe/config/ConfigException.java
+++ b/src/main/java/com/typesafe/config/ConfigException.java
@@ -1,5 +1,8 @@
package com.typesafe.config;
+/**
+ * All exceptions thrown by the library are subclasses of ConfigException.
+ */
public class ConfigException extends RuntimeException {
private static final long serialVersionUID = 1L;
@@ -20,6 +23,11 @@ public class ConfigException extends RuntimeException {
this(message, null);
}
+ /**
+ * Exception indicating that the type of a value does not match the type you
+ * requested.
+ *
+ */
public static class WrongType extends ConfigException {
private static final long serialVersionUID = 1L;
@@ -89,6 +97,12 @@ public class ConfigException extends RuntimeException {
}
}
+ /**
+ * Exception indicating that a value was messed up, for example you may have
+ * asked for a duration and the value can't be sensibly parsed as a
+ * duration.
+ *
+ */
public static class BadValue extends ConfigException {
private static final long serialVersionUID = 1L;
@@ -149,6 +163,10 @@ public class ConfigException extends RuntimeException {
}
}
+ /**
+ * Exception indicating that there was an IO error.
+ *
+ */
public static class IO extends ConfigException {
private static final long serialVersionUID = 1L;
@@ -161,6 +179,10 @@ public class ConfigException extends RuntimeException {
}
}
+ /**
+ * Exception indicating that there was a parse error.
+ *
+ */
public static class Parse extends ConfigException {
private static final long serialVersionUID = 1L;
diff --git a/src/main/java/com/typesafe/config/ConfigObject.java b/src/main/java/com/typesafe/config/ConfigObject.java
index 1d5caec4..83ab5208 100644
--- a/src/main/java/com/typesafe/config/ConfigObject.java
+++ b/src/main/java/com/typesafe/config/ConfigObject.java
@@ -4,16 +4,26 @@ import java.util.List;
import java.util.Set;
/**
- * A Config is a read-only configuration object, which may have nested child
- * objects. Implementations of Config should be immutable (at least from the
- * perspective of anyone using this interface).
+ * A ConfigObject is a read-only configuration object, which may have nested
+ * child objects. Implementations of ConfigObject should be immutable (at least
+ * from the perspective of anyone using this interface).
*
* The getters all have the same semantics; they throw ConfigException.Missing
* if the value is entirely unset, and ConfigException.WrongType if you ask for
* a type that the value can't be converted to. ConfigException.Null is a
- * subclass of ConfigException.WrongType thrown if the value is null.
- *
- * TODO add OrNull variants of all these getters?
+ * subclass of ConfigException.WrongType thrown if the value is null. The "path"
+ * parameters for all the getters have periods between the key names, so the
+ * path "a.b.c" looks for key c in object b in object a in the root object.
+ *
+ *
+ * TODO If you need to look up a key with a period in its name, there isn't a
+ * way to do it right now.
+ *
+ * TODO add OrNull variants of all these getters? Or better to avoid convenience
+ * API for that?
+ *
+ * TODO should it implement Map<String, ? extends ConfigValue> with the mutators
+ * throwing ?
*/
public interface ConfigObject extends ConfigValue {
@@ -31,8 +41,22 @@ public interface ConfigObject extends ConfigValue {
ConfigObject getObject(String path);
+ /**
+ * Gets the value at the path as an unwrapped Java boxed value (Boolean,
+ * Integer, Long, etc.)
+ */
Object getAny(String path);
+ /**
+ * Gets the value at the path as a ConfigValue.
+ *
+ * TODO conceptually if we want to match a read-only subset of the
+ * Map<String, ? extends ConfigValue> interface, we would need to take a key
+ * instead of a path here and return null instead of throwing an exception.
+ *
+ * @param path
+ * @return
+ */
ConfigValue get(String path);
/** Get value as a size in bytes (parses special strings like "128M") */
diff --git a/src/main/java/com/typesafe/config/ConfigOrigin.java b/src/main/java/com/typesafe/config/ConfigOrigin.java
index 481615f7..39358880 100644
--- a/src/main/java/com/typesafe/config/ConfigOrigin.java
+++ b/src/main/java/com/typesafe/config/ConfigOrigin.java
@@ -1,5 +1,9 @@
package com.typesafe.config;
+/**
+ * ConfigOrigin is used to track the origin (such as filename and line number)
+ * of a ConfigValue or other object. The origin is used in error messages.
+ */
public interface ConfigOrigin {
public String description();
}
diff --git a/src/main/java/com/typesafe/config/ConfigValue.java b/src/main/java/com/typesafe/config/ConfigValue.java
index d420e123..5b3a445a 100644
--- a/src/main/java/com/typesafe/config/ConfigValue.java
+++ b/src/main/java/com/typesafe/config/ConfigValue.java
@@ -2,15 +2,26 @@ package com.typesafe.config;
/**
* Interface implemented by any configuration value. From the perspective of
- * users of this interface, the object should be immutable.
+ * users of this interface, the object is immutable. It is therefore safe to use
+ * from multiple threads.
*/
public interface ConfigValue {
+ /**
+ * The origin of the value, for debugging and error messages.
+ *
+ * @return where the value came from
+ */
ConfigOrigin origin();
+ /**
+ * The type of the value; matches the JSON type schema.
+ *
+ * @return value's type
+ */
ConfigValueType valueType();
/**
- * Returns the config value as a plain Java value, should be a String,
+ * Returns the config value as a plain Java boxed value, should be a String,
* Number, etc. matching the valueType() of the ConfigValue.
*/
Object unwrapped();
diff --git a/src/main/java/com/typesafe/config/ConfigValueType.java b/src/main/java/com/typesafe/config/ConfigValueType.java
index 7ff5e066..1de79169 100644
--- a/src/main/java/com/typesafe/config/ConfigValueType.java
+++ b/src/main/java/com/typesafe/config/ConfigValueType.java
@@ -1,5 +1,8 @@
package com.typesafe.config;
+/**
+ * The type of a configuration value. Value types follow the JSON type schema.
+ */
public enum ConfigValueType {
OBJECT, LIST, NUMBER, BOOLEAN, NULL, STRING
}