diff --git a/.travis.yml b/.travis.yml index 2ed039b1..d957beeb 100644 --- a/.travis.yml +++ b/.travis.yml @@ -18,7 +18,7 @@ jdk: - oraclejdk8 script: - - sbt ++$TRAVIS_SCALA_VERSION test + - sbt ++$TRAVIS_SCALA_VERSION test doc # Remove to avoid unnecessary cache updates - find $HOME/.sbt -name "*.lock" -delete diff --git a/build.sbt b/build.sbt index 989917eb..7753e76d 100644 --- a/build.sbt +++ b/build.sbt @@ -7,7 +7,7 @@ import com.typesafe.sbt.SbtPgp.PgpKeys.{ useGpg, publishSigned, publishLocalSign // Release tags should follow: http://semver.org/ SbtGit.versionWithGit -SbtGit.git.baseVersion := "1.1.0" +SbtGit.git.baseVersion := "1.3.0" organization in GlobalScope := "com.typesafe" diff --git a/config/build.sbt b/config/build.sbt index 3d67abac..a77df75a 100644 --- a/config/build.sbt +++ b/config/build.sbt @@ -4,6 +4,7 @@ import de.johoop.jacoco4sbt.JacocoPlugin.jacoco import com.typesafe.sbt.SbtScalariform import com.typesafe.sbt.SbtScalariform.ScalariformKeys import scalariform.formatter.preferences._ +import com.etsy.sbt.Checkstyle._ SbtScalariform.scalariformSettings @@ -25,6 +26,46 @@ libraryDependencies += "com.novocode" % "junit-interface" % "0.11" % "test" externalResolvers += "Scala Tools Snapshots" at "http://scala-tools.org/repo-snapshots/" +checkstyleSettings + +CheckstyleTasks.checkstyleConfig := baseDirectory.value / "checkstyle-config.xml" + +CheckstyleTasks.checkstyle in Compile := { + val log = streams.value.log + (CheckstyleTasks.checkstyle in Compile).value + val resultFile = (target in Compile).value / "checkstyle-report.xml" + val results = scala.xml.XML.loadFile(resultFile) + val errorFiles = results \\ "checkstyle" \\ "file" + + def errorFromXml(node: scala.xml.NodeSeq): (String, String, String) = { + val line: String = (node \ "@line" text) + val msg: String = (node \ "@message" text) + val source: String = (node \ "@source" text) + (line, msg, source) + } + def errorsFromXml(fileNode: scala.xml.NodeSeq): Seq[(String, String, String, String)] = { + val name: String = (fileNode \ "@name" text) + val errors = (fileNode \\ "error") map { e => errorFromXml(e) } + errors map { case (line, error, source) => (name, line, error, source) } + } + + val errors = errorFiles flatMap { f => errorsFromXml(f) } + + if (errors.nonEmpty) { + for (e <- errors) { + log.error(s"${e._1}:${e._2}: ${e._3} (from ${e._4})") + } + throw new RuntimeException(s"Checkstyle failed with ${errors.size} errors") + } + log.info("No errors from checkstyle") +} + +// add checkstyle as a dependency of doc +doc in Compile := { + (CheckstyleTasks.checkstyle in Compile).value + (doc in Compile).value +} + findbugsSettings findbugsReportType := Some(ReportType.Html) findbugsReportName := Some("findbugs.html") @@ -39,6 +80,12 @@ javacOptions in (Compile, compile) ++= Seq("-source", "1.6", "-target", "1.8", " // we have to run tests in serial. parallelExecution in Test := false -sources in (Compile, doc) ~= (_.filter(_.getParentFile.getName != "impl")) +javacOptions in (Compile, doc) ++= Seq("-group", s"Public API (version ${version.value})", "com.typesafe.config", + "-group", "Internal Implementation - Not ABI Stable", "com.typesafe.config.impl") + +javadocSourceBaseUrl := { + for (gitHead <- com.typesafe.sbt.SbtGit.GitKeys.gitHeadCommit.value) + yield s"https://github.com/typesafehub/config/blob/$gitHead/config/src/main/java" +} javaVersionPrefix in javaVersionCheck := Some("1.8") diff --git a/config/checkstyle-config.xml b/config/checkstyle-config.xml new file mode 100644 index 00000000..b5b71d2b --- /dev/null +++ b/config/checkstyle-config.xml @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + + + + + diff --git a/config/checkstyle-suppressions.xml b/config/checkstyle-suppressions.xml new file mode 100644 index 00000000..21fb8e51 --- /dev/null +++ b/config/checkstyle-suppressions.xml @@ -0,0 +1,13 @@ + + + + + + + + diff --git a/config/src/main/java/com/typesafe/config/Config.java b/config/src/main/java/com/typesafe/config/Config.java index 72b85d95..4e68148a 100644 --- a/config/src/main/java/com/typesafe/config/Config.java +++ b/config/src/main/java/com/typesafe/config/Config.java @@ -723,24 +723,154 @@ public interface Config extends ConfigMergeable { */ ConfigList getList(String path); + /** + * Gets a list value with boolean elements. Throws if the + * path is unset or null or not a list or contains values not + * convertible to boolean. + * + * @param path + * the path to the list value. + * @return the list at the path + * @throws ConfigException.Missing + * if value is absent or null + * @throws ConfigException.WrongType + * if value is not convertible to a list of booleans + */ List getBooleanList(String path); + /** + * Gets a list value with number elements. Throws if the + * path is unset or null or not a list or contains values not + * convertible to number. + * + * @param path + * the path to the list value. + * @return the list at the path + * @throws ConfigException.Missing + * if value is absent or null + * @throws ConfigException.WrongType + * if value is not convertible to a list of numbers + */ List getNumberList(String path); + /** + * Gets a list value with int elements. Throws if the + * path is unset or null or not a list or contains values not + * convertible to int. + * + * @param path + * the path to the list value. + * @return the list at the path + * @throws ConfigException.Missing + * if value is absent or null + * @throws ConfigException.WrongType + * if value is not convertible to a list of ints + */ List getIntList(String path); + /** + * Gets a list value with long elements. Throws if the + * path is unset or null or not a list or contains values not + * convertible to long. + * + * @param path + * the path to the list value. + * @return the list at the path + * @throws ConfigException.Missing + * if value is absent or null + * @throws ConfigException.WrongType + * if value is not convertible to a list of longs + */ List getLongList(String path); + /** + * Gets a list value with double elements. Throws if the + * path is unset or null or not a list or contains values not + * convertible to double. + * + * @param path + * the path to the list value. + * @return the list at the path + * @throws ConfigException.Missing + * if value is absent or null + * @throws ConfigException.WrongType + * if value is not convertible to a list of doubles + */ List getDoubleList(String path); + /** + * Gets a list value with string elements. Throws if the + * path is unset or null or not a list or contains values not + * convertible to string. + * + * @param path + * the path to the list value. + * @return the list at the path + * @throws ConfigException.Missing + * if value is absent or null + * @throws ConfigException.WrongType + * if value is not convertible to a list of strings + */ List getStringList(String path); + /** + * Gets a list value with object elements. Throws if the + * path is unset or null or not a list or contains values not + * convertible to ConfigObject. + * + * @param path + * the path to the list value. + * @return the list at the path + * @throws ConfigException.Missing + * if value is absent or null + * @throws ConfigException.WrongType + * if value is not convertible to a list of objects + */ List getObjectList(String path); + /** + * Gets a list value with Config elements. + * Throws if the path is unset or null or not a list or + * contains values not convertible to Config. + * + * @param path + * the path to the list value. + * @return the list at the path + * @throws ConfigException.Missing + * if value is absent or null + * @throws ConfigException.WrongType + * if value is not convertible to a list of configs + */ List getConfigList(String path); + /** + * Gets a list value with any kind of elements. Throws if the + * path is unset or null or not a list. Each element is + * "unwrapped" (see {@link ConfigValue#unwrapped()}). + * + * @param path + * the path to the list value. + * @return the list at the path + * @throws ConfigException.Missing + * if value is absent or null + * @throws ConfigException.WrongType + * if value is not convertible to a list + */ List getAnyRefList(String path); + /** + * Gets a list value with elements representing a size in + * bytes. Throws if the path is unset or null or not a list + * or contains values not convertible to memory sizes. + * + * @param path + * the path to the list value. + * @return the list at the path + * @throws ConfigException.Missing + * if value is absent or null + * @throws ConfigException.WrongType + * if value is not convertible to a list of memory sizes + */ List getBytesList(String path); /** @@ -751,23 +881,31 @@ public interface Config extends ConfigMergeable { * @param path * a path expression * @return list of memory sizes + * @throws ConfigException.Missing + * if value is absent or null + * @throws ConfigException.WrongType + * if value is not convertible to a list of memory sizes */ List getMemorySizeList(String path); /** * @deprecated As of release 1.1, replaced by {@link #getDurationList(String, TimeUnit)} + * @param path the path + * @return list of millisecond values */ @Deprecated List getMillisecondsList(String path); /** * @deprecated As of release 1.1, replaced by {@link #getDurationList(String, TimeUnit)} + * @param path the path + * @return list of nanosecond values */ @Deprecated List getNanosecondsList(String path); /** * Gets a list, converting each value in the list to a duration, using the * same rules as {@link #getDuration(String, TimeUnit)}. - * + * * @since 1.2.0 * @param path * a path expression diff --git a/config/src/main/java/com/typesafe/config/ConfigException.java b/config/src/main/java/com/typesafe/config/ConfigException.java index 79742b34..f5b7a719 100644 --- a/config/src/main/java/com/typesafe/config/ConfigException.java +++ b/config/src/main/java/com/typesafe/config/ConfigException.java @@ -322,7 +322,10 @@ public abstract class ConfigException extends RuntimeException implements Serial this.problem = problem; } - /** Returns the config setting causing the problem. */ + /** + * Returns the config setting causing the problem. + * @return the path of the problem setting + */ public String path() { return path; } @@ -330,12 +333,16 @@ public abstract class ConfigException extends RuntimeException implements Serial /** * Returns where the problem occurred (origin may include info on the * file, line number, etc.). + * @return the origin of the problem setting */ public ConfigOrigin origin() { return origin; } - /** Returns a description of the problem. */ + /** + * Returns a description of the problem. + * @return description of the problem + */ public String problem() { return problem; } diff --git a/config/src/main/java/com/typesafe/config/ConfigFactory.java b/config/src/main/java/com/typesafe/config/ConfigFactory.java index 74ad47dc..eae89afe 100644 --- a/config/src/main/java/com/typesafe/config/ConfigFactory.java +++ b/config/src/main/java/com/typesafe/config/ConfigFactory.java @@ -86,8 +86,8 @@ public final class ConfigFactory { * {@link #defaultReference(ClassLoader)} and to load only the overrides use * {@link #defaultOverrides(ClassLoader)}. * - * @param loader - * @param resourceBasename + * @param loader class loader to look for resources in + * @param resourceBasename basename (no .conf/.json/.properties suffix) * @return configuration for an application relative to given class loader */ public static Config load(ClassLoader loader, String resourceBasename) { @@ -167,6 +167,16 @@ public final class ConfigFactory { return load(checkedContextClassLoader("load"), config); } + /** + * Like {@link #load(Config)} but allows you to specify + * the class loader for looking up resources. + * + * @param loader + * the class loader to use to find resources + * @param config + * the application's portion of the configuration + * @return resolved configuration with overrides and fallbacks added + */ public static Config load(ClassLoader loader, Config config) { return load(loader, config, ConfigResolveOptions.defaults()); } @@ -269,7 +279,7 @@ public final class ConfigFactory { } /** - * Like {@link #load()} but allows specifying parse options + * Like {@link #load()} but allows specifying parse options. * * @param parseOptions * Options for parsing resources @@ -299,7 +309,7 @@ public final class ConfigFactory { /** * Like {@link #load()} but allows specifying a class loader other than the - * thread's current context class loader, and parse options + * thread's current context class loader and also specify parse options. * * @param loader * class loader for finding resources (overrides any loader in parseOptions) @@ -313,7 +323,7 @@ public final class ConfigFactory { /** * Like {@link #load()} but allows specifying a class loader other than the - * thread's current context class loader, and resolve options + * thread's current context class loader and also specify resolve options. * * @param loader * class loader for finding resources @@ -328,7 +338,7 @@ public final class ConfigFactory { /** * Like {@link #load()} but allows specifying a class loader other than the - * thread's current context class loader, parse options, and resolve options + * thread's current context class loader, parse options, and resolve options. * * @param loader * class loader for finding resources (overrides any loader in parseOptions) @@ -396,7 +406,7 @@ public final class ConfigFactory { * Like {@link #defaultReference()} but allows you to specify a class loader * to use rather than the current context class loader. * - * @param loader + * @param loader class loader to look for resources in * @return the default reference config for this class loader */ public static Config defaultReference(ClassLoader loader) { @@ -426,7 +436,7 @@ public final class ConfigFactory { * Like {@link #defaultOverrides()} but allows you to specify a class loader * to use rather than the current context class loader. * - * @param loader + * @param loader class loader to look for resources in * @return the default override configuration */ public static Config defaultOverrides(ClassLoader loader) { @@ -490,7 +500,7 @@ public final class ConfigFactory { * * @since 1.3.0 * - * @param loader + * @param loader class loader to look for resources in * @return the default application configuration */ public static Config defaultApplication(ClassLoader loader) { @@ -502,7 +512,7 @@ public final class ConfigFactory { * * @since 1.3.0 * - * @param parseOptions the options + * @param options the options * @return the default application configuration */ public static Config defaultApplication(ConfigParseOptions options) { @@ -620,6 +630,7 @@ public final class ConfigFactory { * @param properties * a Java Properties object * @param options + * the parse options * @return the parsed configuration */ public static Config parseProperties(Properties properties, @@ -627,22 +638,79 @@ public final class ConfigFactory { return Parseable.newProperties(properties, options).parse().toConfig(); } + /** + * Like {@link parseProperties(Properties, ConfigParseOptions)} but uses default + * parse options. + * @param properties + * a Java Properties object + * @return the parsed configuration + */ public static Config parseProperties(Properties properties) { return parseProperties(properties, ConfigParseOptions.defaults()); } + /** + * Parses a Reader into a Config instance. Does not call + * {@link Config#resolve} or merge the parsed stream with any + * other configuration; this method parses a single stream and + * does nothing else. It does process "include" statements in + * the parsed stream, and may end up doing other IO due to those + * statements. + * + * @param reader + * the reader to parse + * @param options + * parse options to control how the reader is interpreted + * @return the parsed configuration + * @throws ConfigException on IO or parse errors + */ public static Config parseReader(Reader reader, ConfigParseOptions options) { return Parseable.newReader(reader, options).parse().toConfig(); } + /** + * Parses a reader into a Config instance as with + * {@link #parseReader(Reader,ConfigParseOptions)} but always uses the + * default parse options. + * + * @param reader + * the reader to parse + * @return the parsed configuration + * @throws ConfigException on IO or parse errors + */ public static Config parseReader(Reader reader) { return parseReader(reader, ConfigParseOptions.defaults()); } + /** + * Parses a URL into a Config instance. Does not call + * {@link Config#resolve} or merge the parsed stream with any + * other configuration; this method parses a single stream and + * does nothing else. It does process "include" statements in + * the parsed stream, and may end up doing other IO due to those + * statements. + * + * @param url + * the url to parse + * @param options + * parse options to control how the url is interpreted + * @return the parsed configuration + * @throws ConfigException on IO or parse errors + */ public static Config parseURL(URL url, ConfigParseOptions options) { return Parseable.newURL(url, options).parse().toConfig(); } + /** + * Parses a url into a Config instance as with + * {@link #parseURL(URL,ConfigParseOptions)} but always uses the + * default parse options. + * + * @param url + * the url to parse + * @return the parsed configuration + * @throws ConfigException on IO or parse errors + */ public static Config parseURL(URL url) { return parseURL(url, ConfigParseOptions.defaults()); } @@ -765,6 +833,19 @@ public final class ConfigFactory { .toConfig(); } + /** + * Like {@link #parseResources(Class,String,ConfigParseOptions)} but always uses + * default parse options. + * + * @param klass + * klass.getClassLoader() will be used to load + * resources, and non-absolute resource names will have this + * class's package added + * @param resource + * resource to look up, relative to klass's package + * or absolute starting with a "/" + * @return the parsed configuration + */ public static Config parseResources(Class klass, String resource) { return parseResources(klass, resource, ConfigParseOptions.defaults()); } @@ -805,6 +886,19 @@ public final class ConfigFactory { options).toConfig(); } + /** + * Like {@link #parseResourcesAnySyntax(Class,String,ConfigParseOptions)} + * but always uses default parse options. + * + * @param klass + * klass.getClassLoader() will be used to load + * resources, and non-absolute resource names will have this + * class's package added + * @param resourceBasename + * a resource name as in {@link java.lang.Class#getResource}, + * with or without extension + * @return the parsed configuration + */ public static Config parseResourcesAnySyntax(Class klass, String resourceBasename) { return parseResourcesAnySyntax(klass, resourceBasename, ConfigParseOptions.defaults()); } @@ -836,6 +930,16 @@ public final class ConfigFactory { return parseResources(resource, options.setClassLoader(loader)); } + /** + * Like {@link #parseResources(ClassLoader,String,ConfigParseOptions)} but always uses + * default parse options. + * + * @param loader + * will be used to load resources + * @param resource + * resource to look up in the loader + * @return the parsed configuration + */ public static Config parseResources(ClassLoader loader, String resource) { return parseResources(loader, resource, ConfigParseOptions.defaults()); } @@ -869,6 +973,18 @@ public final class ConfigFactory { .toConfig(); } + /** + * Like {@link #parseResourcesAnySyntax(ClassLoader,String,ConfigParseOptions)} but always uses + * default parse options. + * + * @param loader + * will be used to load resources + * @param resourceBasename + * a resource name as in + * {@link java.lang.ClassLoader#getResource}, with or without + * extension + * @return the parsed configuration + */ public static Config parseResourcesAnySyntax(ClassLoader loader, String resourceBasename) { return parseResourcesAnySyntax(loader, resourceBasename, ConfigParseOptions.defaults()); } @@ -877,6 +993,9 @@ public final class ConfigFactory { * Like {@link #parseResources(ClassLoader,String,ConfigParseOptions)} but * uses thread's current context class loader if none is set in the * ConfigParseOptions. + * @param resource the resource name + * @param options parse options + * @return the parsed configuration */ public static Config parseResources(String resource, ConfigParseOptions options) { ConfigParseOptions withLoader = ensureClassLoader(options, "parseResources"); @@ -886,6 +1005,8 @@ public final class ConfigFactory { /** * Like {@link #parseResources(ClassLoader,String)} but uses thread's * current context class loader. + * @param resource the resource name + * @return the parsed configuration */ public static Config parseResources(String resource) { return parseResources(resource, ConfigParseOptions.defaults()); @@ -895,6 +1016,9 @@ public final class ConfigFactory { * Like * {@link #parseResourcesAnySyntax(ClassLoader,String,ConfigParseOptions)} * but uses thread's current context class loader. + * @param resourceBasename the resource basename (no file type suffix) + * @param options parse options + * @return the parsed configuration */ public static Config parseResourcesAnySyntax(String resourceBasename, ConfigParseOptions options) { return ConfigImpl.parseResourcesAnySyntax(resourceBasename, options).toConfig(); @@ -903,15 +1027,31 @@ public final class ConfigFactory { /** * Like {@link #parseResourcesAnySyntax(ClassLoader,String)} but uses * thread's current context class loader. + * @param resourceBasename the resource basename (no file type suffix) + * @return the parsed configuration */ public static Config parseResourcesAnySyntax(String resourceBasename) { return parseResourcesAnySyntax(resourceBasename, ConfigParseOptions.defaults()); } + /** + * Parses a string (which should be valid HOCON or JSON by default, or + * the syntax specified in the options otherwise). + * + * @param s string to parse + * @param options parse options + * @return the parsed configuration + */ public static Config parseString(String s, ConfigParseOptions options) { return Parseable.newString(s, options).parse().toConfig(); } + /** + * Parses a string (which should be valid HOCON or JSON). + * + * @param s string to parse + * @return the parsed configuration + */ public static Config parseString(String s) { return parseString(s, ConfigParseOptions.defaults()); } @@ -932,7 +1072,7 @@ public final class ConfigFactory { * object of "b". The caller of this method should ensure that doesn't * happen. * - * @param values + * @param values map from paths to plain Java objects * @param originDescription * description of what this map represents, like a filename, or * "default settings" (origin description is used in error @@ -948,7 +1088,7 @@ public final class ConfigFactory { * See the other overload of {@link #parseMap(Map, String)} for details, * this one just uses a default origin description. * - * @param values + * @param values map from paths to plain Java values * @return the map converted to a {@code Config} */ public static Config parseMap(Map values) { diff --git a/config/src/main/java/com/typesafe/config/ConfigIncluder.java b/config/src/main/java/com/typesafe/config/ConfigIncluder.java index a08f9059..f0c44059 100644 --- a/config/src/main/java/com/typesafe/config/ConfigIncluder.java +++ b/config/src/main/java/com/typesafe/config/ConfigIncluder.java @@ -23,7 +23,7 @@ public interface ConfigIncluder { * the fallback is the same one you already have. The same fallback may be * added repeatedly. * - * @param fallback + * @param fallback the previous includer for chaining * @return a new includer */ ConfigIncluder withFallback(ConfigIncluder fallback); diff --git a/config/src/main/java/com/typesafe/config/ConfigMemorySize.java b/config/src/main/java/com/typesafe/config/ConfigMemorySize.java index cc9aed47..322b2c82 100644 --- a/config/src/main/java/com/typesafe/config/ConfigMemorySize.java +++ b/config/src/main/java/com/typesafe/config/ConfigMemorySize.java @@ -23,6 +23,8 @@ public final class ConfigMemorySize { * Constructs a ConfigMemorySize representing the given * number of bytes. * @since 1.3.0 + * @param bytes a number of bytes + * @return an instance representing the number of bytes */ public static ConfigMemorySize ofBytes(long bytes) { return new ConfigMemorySize(bytes); @@ -31,6 +33,7 @@ public final class ConfigMemorySize { /** * Gets the size in bytes. * @since 1.3.0 + * @return how many bytes */ public long toBytes() { return bytes; diff --git a/config/src/main/java/com/typesafe/config/ConfigOrigin.java b/config/src/main/java/com/typesafe/config/ConfigOrigin.java index bc23898f..fc14f459 100644 --- a/config/src/main/java/com/typesafe/config/ConfigOrigin.java +++ b/config/src/main/java/com/typesafe/config/ConfigOrigin.java @@ -79,17 +79,17 @@ public interface ConfigOrigin { * none */ public List comments(); - + /** * Returns a {@code ConfigOrigin} based on this one, but with the given * comments. Does not modify this instance or any {@code ConfigValue}s with - * this origin (since they are immutable). To set the returned origin to a + * this origin (since they are immutable). To set the returned origin to a * {@code ConfigValue}, use {@link ConfigValue#withOrigin}. - * + * *

* Note that when the given comments are equal to the comments on this object, * a new instance may not be created and {@code this} is returned directly. - * + * * @param comments the comments used on the returned origin * @return the ConfigOrigin with the given comments */ @@ -97,17 +97,17 @@ public interface ConfigOrigin { /** * Returns a {@code ConfigOrigin} based on this one, but with the given - * line number. This origin must be a FILE, URL or RESOURCE. Does not modify + * line number. This origin must be a FILE, URL or RESOURCE. Does not modify * this instance or any {@code ConfigValue}s with this origin (since they are * immutable). To set the returned origin to a {@code ConfigValue}, use - * {@link ConfigValue#withOrigin}. - * + * {@link ConfigValue#withOrigin}. + * *

* Note that when the given lineNumber are equal to the lineNumber on this * object, a new instance may not be created and {@code this} is returned * directly. - * - * @param comments the comments used on the returned origin + * + * @param lineNumber the new line number * @return the created ConfigOrigin */ public ConfigOrigin withLineNumber(int lineNumber); diff --git a/config/src/main/java/com/typesafe/config/ConfigOriginFactory.java b/config/src/main/java/com/typesafe/config/ConfigOriginFactory.java index 86004f6e..9a9a0413 100644 --- a/config/src/main/java/com/typesafe/config/ConfigOriginFactory.java +++ b/config/src/main/java/com/typesafe/config/ConfigOriginFactory.java @@ -15,43 +15,43 @@ import com.typesafe.config.impl.ConfigImpl; public final class ConfigOriginFactory { private ConfigOriginFactory() { } - + /** * Returns the default origin for values when no other information is * provided. This is the origin used in {@link ConfigValueFactory * #fromAnyRef(Object)}. - * + * * @return the default origin */ public static ConfigOrigin newSimple() { return newSimple(null); } - + /** - * Returns a origin with the given description. - * + * Returns an origin with the given description. + * * @param description brief description of what the origin is - * @return + * @return a new origin */ public static ConfigOrigin newSimple(String description) { return ConfigImpl.newSimpleOrigin(description); } - + /** * Creates a file origin with the given filename. - * + * * @param filename the filename of this origin - * @return + * @return a new origin */ public static ConfigOrigin newFile(String filename) { return ConfigImpl.newFileOrigin(filename); } - + /** * Creates a url origin with the given URL object. - * + * * @param url the url of this origin - * @return + * @return a new origin */ public static ConfigOrigin newURL(URL url) { return ConfigImpl.newURLOrigin(url); diff --git a/config/src/main/java/com/typesafe/config/ConfigParseOptions.java b/config/src/main/java/com/typesafe/config/ConfigParseOptions.java index 6b793204..e1c1a770 100644 --- a/config/src/main/java/com/typesafe/config/ConfigParseOptions.java +++ b/config/src/main/java/com/typesafe/config/ConfigParseOptions.java @@ -36,6 +36,12 @@ public final class ConfigParseOptions { this.classLoader = classLoader; } + /** + * Gets an instance of ConfigParseOptions with all fields + * set to the default values. Start with this instance and make any + * changes you need. + * @return the default parse options + */ public static ConfigParseOptions defaults() { return new ConfigParseOptions(null, null, true, null, null); } @@ -56,6 +62,10 @@ public final class ConfigParseOptions { this.includer, this.classLoader); } + /** + * Gets the current syntax option, which may be null for "any". + * @return the current syntax or null + */ public ConfigSyntax getSyntax() { return syntax; } @@ -67,7 +77,7 @@ public final class ConfigParseOptions { * library to come up with something automatically. This description is the * basis for the {@link ConfigOrigin} of the parsed values. * - * @param originDescription + * @param originDescription description to put in the {@link ConfigOrigin} * @return options with the origin description set */ public ConfigParseOptions setOriginDescription(String originDescription) { @@ -82,6 +92,10 @@ public final class ConfigParseOptions { this.includer, this.classLoader); } + /** + * Gets the current origin description, which may be null for "automatic". + * @return the current origin description or null + */ public String getOriginDescription() { return originDescription; } @@ -99,7 +113,7 @@ public final class ConfigParseOptions { * a file) is missing. Set to true to just return an empty document in that * case. * - * @param allowMissing + * @param allowMissing true to silently ignore missing item * @return options with the "allow missing" flag set */ public ConfigParseOptions setAllowMissing(boolean allowMissing) { @@ -110,14 +124,19 @@ public final class ConfigParseOptions { this.includer, this.classLoader); } + /** + * Gets the current "allow missing" flag. + * @return whether we allow missing files + */ public boolean getAllowMissing() { return allowMissing; } /** - * Set a ConfigIncluder which customizes how includes are handled. + * Set a {@link ConfigIncluder} which customizes how includes are handled. + * null means to use the default includer. * - * @param includer + * @param includer the includer to use or null for default * @return new version of the parse options with different includer */ public ConfigParseOptions setIncluder(ConfigIncluder includer) { @@ -128,7 +147,18 @@ public final class ConfigParseOptions { includer, this.classLoader); } + /** + * Prepends a {@link ConfigIncluder} which customizes how + * includes are handled. To prepend your includer, the + * library calls {@link ConfigIncluder#withFallback} on your + * includer to append the existing includer to it. + * + * @param includer the includer to prepend (may not be null) + * @return new version of the parse options with different includer + */ public ConfigParseOptions prependIncluder(ConfigIncluder includer) { + if (includer == null) + throw new NullPointerException("null includer passed to prependIncluder"); if (this.includer == includer) return this; else if (this.includer != null) @@ -137,7 +167,17 @@ public final class ConfigParseOptions { return setIncluder(includer); } + /** + * Appends a {@link ConfigIncluder} which customizes how + * includes are handled. To append, the library calls {@link + * ConfigIncluder#withFallback} on the existing includer. + * + * @param includer the includer to append (may not be null) + * @return new version of the parse options with different includer + */ public ConfigParseOptions appendIncluder(ConfigIncluder includer) { + if (includer == null) + throw new NullPointerException("null includer passed to appendIncluder"); if (this.includer == includer) return this; else if (this.includer != null) @@ -146,6 +186,10 @@ public final class ConfigParseOptions { return setIncluder(includer); } + /** + * Gets the current includer (will be null for the default includer). + * @return current includer or null + */ public ConfigIncluder getIncluder() { return includer; } diff --git a/config/src/main/java/com/typesafe/config/ConfigParseable.java b/config/src/main/java/com/typesafe/config/ConfigParseable.java index 8c190855..b63801a8 100644 --- a/config/src/main/java/com/typesafe/config/ConfigParseable.java +++ b/config/src/main/java/com/typesafe/config/ConfigParseable.java @@ -24,12 +24,14 @@ public interface ConfigParseable { * @param options * parse options, should be based on the ones from * {@link ConfigParseable#options options()} + * @return the parsed object */ ConfigObject parse(ConfigParseOptions options); /** * Returns a {@link ConfigOrigin} describing the origin of the parseable * item. + * @return the origin of the parseable item */ ConfigOrigin origin(); @@ -37,6 +39,7 @@ public interface ConfigParseable { * Get the initial options, which can be modified then passed to parse(). * These options will have the right description, includer, and other * parameters already set up. + * @return the initial options */ ConfigParseOptions options(); } diff --git a/config/src/main/java/com/typesafe/config/ConfigValue.java b/config/src/main/java/com/typesafe/config/ConfigValue.java index 795454cd..59c0525f 100644 --- a/config/src/main/java/com/typesafe/config/ConfigValue.java +++ b/config/src/main/java/com/typesafe/config/ConfigValue.java @@ -40,6 +40,7 @@ public interface ConfigValue extends ConfigMergeable { * {@code List}, or {@code null}, matching the {@link #valueType()} * of this {@code ConfigValue}. If the value is a {@link ConfigObject} or * {@link ConfigList}, it is recursively unwrapped. + * @return a plain Java value corresponding to this ConfigValue */ Object unwrapped(); diff --git a/config/src/main/java/com/typesafe/config/ConfigValueFactory.java b/config/src/main/java/com/typesafe/config/ConfigValueFactory.java index d1f82e87..38abd0f4 100644 --- a/config/src/main/java/com/typesafe/config/ConfigValueFactory.java +++ b/config/src/main/java/com/typesafe/config/ConfigValueFactory.java @@ -91,8 +91,8 @@ public final class ConfigValueFactory { * See also {@link ConfigFactory#parseMap(Map,String)} which interprets the * keys in the map as path expressions. * - * @param values - * @param originDescription + * @param values map from keys to plain Java values + * @param originDescription description to use in {@link ConfigOrigin} of created values * @return a new {@link ConfigObject} value */ public static ConfigObject fromMap(Map values, @@ -104,9 +104,9 @@ public final class ConfigValueFactory { * See the {@link #fromAnyRef(Object,String)} documentation for details. * This is a typesafe wrapper that only works on {@link java.lang.Iterable} * and returns {@link ConfigList} rather than {@link ConfigValue}. - * - * @param values - * @param originDescription + * + * @param values list of plain Java values + * @param originDescription description to use in {@link ConfigOrigin} of created values * @return a new {@link ConfigList} value */ public static ConfigList fromIterable(Iterable values, @@ -118,7 +118,7 @@ public final class ConfigValueFactory { * See the other overload {@link #fromAnyRef(Object,String)} for details, * this one just uses a default origin description. * - * @param object + * @param object a plain Java value * @return a new {@link ConfigValue} */ public static ConfigValue fromAnyRef(Object object) { @@ -133,7 +133,7 @@ public final class ConfigValueFactory { * See also {@link ConfigFactory#parseMap(Map)} which interprets the keys in * the map as path expressions. * - * @param values + * @param values map from keys to plain Java values * @return a new {@link ConfigObject} */ public static ConfigObject fromMap(Map values) { @@ -144,7 +144,7 @@ public final class ConfigValueFactory { * See the other overload of {@link #fromIterable(Iterable, String)} for * details, this one just uses a default origin description. * - * @param values + * @param values list of plain Java values * @return a new {@link ConfigList} */ public static ConfigList fromIterable(Iterable values) { diff --git a/config/src/main/java/com/typesafe/config/impl/ConfigBeanImpl.java b/config/src/main/java/com/typesafe/config/impl/ConfigBeanImpl.java index f23b946a..17178b87 100644 --- a/config/src/main/java/com/typesafe/config/impl/ConfigBeanImpl.java +++ b/config/src/main/java/com/typesafe/config/impl/ConfigBeanImpl.java @@ -23,11 +23,19 @@ import com.typesafe.config.ConfigMemorySize; import com.typesafe.config.ConfigValue; import com.typesafe.config.ConfigValueType; +/** + * Internal implementation detail, not ABI stable, do not touch. + * For use only by the {@link com.typesafe.config} package. + */ public class ConfigBeanImpl { /** * This is public ONLY for use by the "config" package, DO NOT USE this ABI * may change. + * @param type of the bean + * @param config config to use + * @param clazz class of the bean + * @return the bean instance */ public static T createInternal(Config config, Class clazz) { if (((SimpleConfig)config).root().resolveStatus() != ResolveStatus.RESOLVED) diff --git a/config/src/main/java/com/typesafe/config/impl/ConfigImpl.java b/config/src/main/java/com/typesafe/config/impl/ConfigImpl.java index 6c3fc5a4..e441204a 100644 --- a/config/src/main/java/com/typesafe/config/impl/ConfigImpl.java +++ b/config/src/main/java/com/typesafe/config/impl/ConfigImpl.java @@ -27,7 +27,10 @@ import com.typesafe.config.ConfigParseable; import com.typesafe.config.ConfigValue; import com.typesafe.config.impl.SimpleIncluder.NameSource; -/** This is public but is only supposed to be used by the "config" package */ +/** + * Internal implementation detail, not ABI stable, do not touch. + * For use only by the {@link com.typesafe.config} package. + */ public class ConfigImpl { private static class LoaderCache { @@ -78,7 +81,6 @@ public class ConfigImpl { static final LoaderCache cache = new LoaderCache(); } - /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */ public static Config computeCachedConfig(ClassLoader loader, String key, Callable updater) { LoaderCache cache; @@ -118,21 +120,18 @@ public class ConfigImpl { } }; - /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */ public static ConfigObject parseResourcesAnySyntax(Class klass, String resourceBasename, ConfigParseOptions baseOptions) { NameSource source = new ClasspathNameSourceWithClass(klass); return SimpleIncluder.fromBasename(source, resourceBasename, baseOptions); } - /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */ public static ConfigObject parseResourcesAnySyntax(String resourceBasename, ConfigParseOptions baseOptions) { NameSource source = new ClasspathNameSource(); return SimpleIncluder.fromBasename(source, resourceBasename, baseOptions); } - /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */ public static ConfigObject parseFileAnySyntax(File basename, ConfigParseOptions baseOptions) { NameSource source = new FileNameSource(); return SimpleIncluder.fromBasename(source, basename.getPath(), baseOptions); @@ -144,7 +143,6 @@ public class ConfigImpl { return emptyObject(origin); } - /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */ public static Config emptyConfig(String originDescription) { return emptyObject(originDescription).toConfig(); } @@ -191,13 +189,11 @@ public class ConfigImpl { return SimpleConfigOrigin.newSimple(originDescription); } - /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */ public static ConfigValue fromAnyRef(Object object, String originDescription) { ConfigOrigin origin = valueOrigin(originDescription); return fromAnyRef(object, origin, FromMapMode.KEYS_ARE_KEYS); } - /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */ public static ConfigObject fromPathMap( Map pathMap, String originDescription) { ConfigOrigin origin = valueOrigin(originDescription); @@ -328,12 +324,10 @@ public class ConfigImpl { } } - /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */ public static Config systemPropertiesAsConfig() { return systemPropertiesAsConfigObject().toConfig(); } - /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */ public static void reloadSystemPropertiesConfig() { // ConfigFactory.invalidateCaches() relies on this having the side // effect that it drops all caches @@ -365,12 +359,10 @@ public class ConfigImpl { } } - /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */ public static Config envVariablesAsConfig() { return envVariablesAsConfigObject().toConfig(); } - /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */ public static Config defaultReference(final ClassLoader loader) { return computeCachedConfig(loader, "defaultReference", new Callable() { @Override @@ -427,7 +419,6 @@ public class ConfigImpl { } } - /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */ public static boolean traceLoadsEnabled() { try { return DebugHolder.traceLoadsEnabled(); @@ -470,8 +461,7 @@ public class ConfigImpl { else return new ConfigException.NotResolved(newMessage, original); } - - /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */ + public static ConfigOrigin newSimpleOrigin(String description) { if (description == null) { return defaultValueOrigin; @@ -480,14 +470,11 @@ public class ConfigImpl { } } - /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */ public static ConfigOrigin newFileOrigin(String filename) { return SimpleConfigOrigin.newFile(filename); } - - /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */ + public static ConfigOrigin newURLOrigin(URL url) { return SimpleConfigOrigin.newURL(url); } - } diff --git a/config/src/main/java/com/typesafe/config/impl/ConfigImplUtil.java b/config/src/main/java/com/typesafe/config/impl/ConfigImplUtil.java index 5592f959..257c2c41 100644 --- a/config/src/main/java/com/typesafe/config/impl/ConfigImplUtil.java +++ b/config/src/main/java/com/typesafe/config/impl/ConfigImplUtil.java @@ -16,8 +16,10 @@ import java.util.List; import com.typesafe.config.ConfigException; import com.typesafe.config.ConfigOrigin; - -/** This is public just for the "config" package to use, don't touch it */ +/** + * Internal implementation detail, not ABI stable, do not touch. + * For use only by the {@link com.typesafe.config} package. + */ final public class ConfigImplUtil { static boolean equalsHandlingNull(Object a, Object b) { if (a == null && b != null) @@ -30,10 +32,6 @@ final public class ConfigImplUtil { return a.equals(b); } - /** - * This is public ONLY for use by the "config" package, DO NOT USE this ABI - * may change. - */ public static String renderJsonString(String s) { StringBuilder sb = new StringBuilder(); sb.append('"'); @@ -117,7 +115,6 @@ final public class ConfigImplUtil { } } - /** This is public just for the "config" package to use, don't touch it! */ public static String unicodeTrim(String s) { // this is dumb because it looks like there aren't any whitespace // characters that need surrogate encoding. But, points for @@ -166,7 +163,7 @@ final public class ConfigImplUtil { return s.substring(start, end); } - /** This is public just for the "config" package to use, don't touch it! */ + public static ConfigException extractInitializerError(ExceptionInInitializerError e) { Throwable cause = e.getCause(); if (cause != null && cause instanceof ConfigException) { @@ -192,26 +189,14 @@ final public class ConfigImplUtil { } } - /** - * This is public ONLY for use by the "config" package, DO NOT USE this ABI - * may change. You can use the version in ConfigUtil instead. - */ public static String joinPath(String... elements) { return (new Path(elements)).render(); } - /** - * This is public ONLY for use by the "config" package, DO NOT USE this ABI - * may change. You can use the version in ConfigUtil instead. - */ public static String joinPath(List elements) { return joinPath(elements.toArray(new String[0])); } - /** - * This is public ONLY for use by the "config" package, DO NOT USE this ABI - * may change. You can use the version in ConfigUtil instead. - */ public static List splitPath(String path) { Path p = Path.newPath(path); List elements = new ArrayList(); diff --git a/config/src/main/java/com/typesafe/config/impl/Parseable.java b/config/src/main/java/com/typesafe/config/impl/Parseable.java index e5e03d15..684d8f95 100644 --- a/config/src/main/java/com/typesafe/config/impl/Parseable.java +++ b/config/src/main/java/com/typesafe/config/impl/Parseable.java @@ -35,18 +35,22 @@ import com.typesafe.config.ConfigSyntax; import com.typesafe.config.ConfigValue; /** - * This is public but it's only for use by the config package; DO NOT TOUCH. The - * point of this class is to avoid "propagating" each overload on - * "thing which can be parsed" through multiple interfaces. Most interfaces can - * have just one overload that takes a Parseable. Also it's used as an abstract - * "resource handle" in the ConfigIncluder interface. + * Internal implementation detail, not ABI stable, do not touch. + * For use only by the {@link com.typesafe.config} package. + * The point of this class is to avoid "propagating" each + * overload on "thing which can be parsed" through multiple + * interfaces. Most interfaces can have just one overload that + * takes a Parseable. Also it's used as an abstract "resource + * handle" in the ConfigIncluder interface. */ public abstract class Parseable implements ConfigParseable { private ConfigIncludeContext includeContext; private ConfigParseOptions initialOptions; private ConfigOrigin initialOrigin; - + /** + * Internal implementation detail, not ABI stable, do not touch. + */ protected interface Relativizer { ConfigParseable relativeTo(String filename); } @@ -383,10 +387,8 @@ public abstract class Parseable implements ConfigParseable { } } - /** - * note that we will never close this reader; you have to do it when parsing - * is complete. - */ + // note that we will never close this reader; you have to do it when parsing + // is complete. public static Parseable newReader(Reader reader, ConfigParseOptions options) { return new ParseableReader(doNotClose(reader), options); diff --git a/config/src/main/java/com/typesafe/config/impl/package.html b/config/src/main/java/com/typesafe/config/impl/package.html new file mode 100644 index 00000000..4df65c25 --- /dev/null +++ b/config/src/main/java/com/typesafe/config/impl/package.html @@ -0,0 +1,25 @@ + + + + + + + + +

+Internal implementation details that can change ABI at any time. +

+ +

+Please check out the {@link com.typesafe.config.Config public API} instead, unless +you're interested in browsing implementation details. None of the ABI +under impl has any guarantees; it will change whenever someone +feels like changing it. If you feel you need access to something +in impl, please +file a feature request. +

+ + + diff --git a/project/linksource.scala b/project/linksource.scala new file mode 100644 index 00000000..01c3226d --- /dev/null +++ b/project/linksource.scala @@ -0,0 +1,63 @@ +import sbt._ +import Keys._ +import plugins.JvmPlugin + +object LinkSourcePlugin extends AutoPlugin { + + object autoImport { + lazy val javadocSourceBaseUrl = settingKey[Option[String]]("base URL (no trailing slash) for source code") + } + + import autoImport._ + + override def trigger = allRequirements + override def requires = JvmPlugin + override lazy val projectSettings = Seq( + javadocSourceBaseUrl := None, + javacOptions in (Compile, doc) := { + val old = (javacOptions in doc).value + if (old.contains("-linksource")) + old + else + "-linksource" +: old + }, + (doc in Compile) := { + val result = (doc in Compile).value + + val dir = (target in doc in Compile).value + + javadocSourceBaseUrl.value.foreach { url => + rewriteSourceLinks(dir, url, streams.value.log) + } + + result + } + ) + + + private def rewriteSourceLinks(dir: File, sourceBaseUrl: String, log: Logger): Unit = { + // Convert to + // "https://github.com/typesafehub/config/blob/v1.2.1/config/src/main/java/com/typesafe/config/Config.java#L165" + // in all .html files found underneath dir + val origRegex = "href=\".*src-html/([^\"]+)\"".r + def listFiles(d: File): Seq[File] = IO.listFiles(d).toSeq.flatMap { f => + if (f.isDirectory) + listFiles(f) + else + Seq(f) + } + val htmlFiles = listFiles(dir).filter(_.getName.endsWith(".html")) + for (f <- htmlFiles) { + val content = IO.read(f) + val changed = origRegex.replaceAllIn(content, { m: scala.util.matching.Regex.Match => + val oldFileLine = m.group(1) + val fileLine = oldFileLine.replace("line.", "L").replace(".html", ".java") + s""" href="$sourceBaseUrl/$fileLine" target="_blank" """ + }) + if (content != changed) { + log.info(s"Replacing source links in $f") + IO.write(f, changed) + } + } + } +} diff --git a/project/plugins.sbt b/project/plugins.sbt index 7a8b4f52..b71a6a39 100644 --- a/project/plugins.sbt +++ b/project/plugins.sbt @@ -4,6 +4,8 @@ addSbtPlugin("com.typesafe.sbt" % "sbt-pgp" % "0.8.1") addSbtPlugin("com.typesafe.sbt" % "sbt-osgi" % "0.6.0") addSbtPlugin("com.typesafe.sbt" % "sbt-scalariform" % "1.2.1") +addSbtPlugin("com.etsy" % "sbt-checkstyle-plugin" % "0.4.1") + resolvers += "jgit-repo" at "http://download.eclipse.org/jgit/maven" addSbtPlugin("com.typesafe.sbt" % "sbt-git" % "0.6.2") addSbtPlugin("com.typesafe.sbt" % "sbt-javaversioncheck" % "0.1.0")