github-repos/config
1
0
Fork 0
mirror of https://github.com/lightbend/config.git synced 2025-01-15 23:01:05 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #276 from typesafehub/javadoc

Browse Source 
Various javadoc fixes
This commit is contained in:
Havoc Pennington 2015-03-06 20:32:57 -05:00
commit 4b2fc5c6cb
23 changed files with 590 additions and 101 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.travis.yml
View File

@ -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

2
build.sbt
View File

@ -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"

49
config/build.sbt
View File

@ -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")

21
config/checkstyle-config.xml Normal file
View File

@ -0,0 +1,21 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module PUBLIC
"-//Puppy Crawl//DTD Check Configuration 1.3//EN"
"http://www.puppycrawl.com/dtds/configuration_1_3.dtd">
<module name="Checker">
<module name="SuppressionFilter">
<property name="file" value="config/checkstyle-suppressions.xml"/>
</module>
<module name="TreeWalker">
<module name="JavadocType">
<property name="scope" value="public"/>
</module>
<module name="JavadocMethod">
<property name="scope" value="public"/>
</module>
<module name="JavadocStyle">
<property name="scope" value="public"/>
</module>
</module>
</module>

13
config/checkstyle-suppressions.xml Normal file
View File

@ -0,0 +1,13 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE suppressions PUBLIC "-//Puppy Crawl//DTD Suppressions 1.1//EN"
"http://www.puppycrawl.com/dtds/suppressions_1_1.dtd">
<suppressions>
<!-- don't care about javadoc coverage of methods in impl -->
<suppress checks="JavadocMethod"
files="com[\\/]typesafe[\\/]config[\\/]impl[\\/]"/>
<!-- ConfigException has a bunch of constructors that are
self-evident and would clutter the heck out of the file
to document -->
<suppress checks="JavadocMethod"
files="com[\\/]typesafe[\\/]config[\\/]ConfigException.java"/>
</suppressions>

138
config/src/main/java/com/typesafe/config/Config.java
View File

@ -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<Boolean> 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<Number> 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<Integer> 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<Long> 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<Double> 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<String> 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 <code>ConfigObject</code>.
*
* @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<? extends ConfigObject> getObjectList(String path);
/**
* Gets a list value with <code>Config</code> elements.
* Throws if the path is unset or null or not a list or
* contains values not convertible to <code>Config</code>.
*
* @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<? extends Config> 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<? extends Object> 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<Long> getBytesList(String path);
/**
@ -751,16 +881,24 @@ 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<ConfigMemorySize> 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<Long> 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<Long> getNanosecondsList(String path);

11
config/src/main/java/com/typesafe/config/ConfigException.java
View File

@ -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;
}

164
config/src/main/java/com/typesafe/config/ConfigFactory.java
View File

@ -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
* <code>klass.getClassLoader()</code> 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 <code>klass</code>'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
* <code>klass.getClassLoader()</code> 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<String, ? extends Object> values) {

2
config/src/main/java/com/typesafe/config/ConfigIncluder.java
View File

@ -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);

3
config/src/main/java/com/typesafe/config/ConfigMemorySize.java
View File

@ -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;

2
config/src/main/java/com/typesafe/config/ConfigOrigin.java
View File

@ -107,7 +107,7 @@ public interface ConfigOrigin {
* 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);

8
config/src/main/java/com/typesafe/config/ConfigOriginFactory.java
View File

@ -28,10 +28,10 @@ public final class ConfigOriginFactory {
}
/**
* 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);
@ -41,7 +41,7 @@ public final class ConfigOriginFactory {
* 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);
@ -51,7 +51,7 @@ public final class ConfigOriginFactory {
* 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);

52
config/src/main/java/com/typesafe/config/ConfigParseOptions.java
View File

@ -36,6 +36,12 @@ public final class ConfigParseOptions {
this.classLoader = classLoader;
}
/**
* Gets an instance of <code>ConfigParseOptions</code> 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;
}

3
config/src/main/java/com/typesafe/config/ConfigParseable.java
View File

@ -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();
}

1
config/src/main/java/com/typesafe/config/ConfigValue.java
View File

@ -40,6 +40,7 @@ public interface ConfigValue extends ConfigMergeable {
* {@code List<Object>}, 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();

14
config/src/main/java/com/typesafe/config/ConfigValueFactory.java
View File

@ -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<String, ? extends Object> values,
@ -105,8 +105,8 @@ public final class ConfigValueFactory {
* 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<? extends Object> 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<String, ? extends Object> 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<? extends Object> values) {

8
config/src/main/java/com/typesafe/config/impl/ConfigBeanImpl.java
View File

@ -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 <T> type of the bean
* @param config config to use
* @param clazz class of the bean
* @return the bean instance
*/
public static <T> T createInternal(Config config, Class<T> clazz) {
if (((SimpleConfig)config).root().resolveStatus() != ResolveStatus.RESOLVED)

21
config/src/main/java/com/typesafe/config/impl/ConfigImpl.java
View File

@ -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<Config> 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<String, ? extends Object> 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<Config>() {
@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();
@ -471,7 +462,6 @@ public class ConfigImpl {
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);
}
}

25
config/src/main/java/com/typesafe/config/impl/ConfigImplUtil.java
View File

@ -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<String> 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<String> splitPath(String path) {
Path p = Path.newPath(path);
List<String> elements = new ArrayList<String>();

22
config/src/main/java/com/typesafe/config/impl/Parseable.java
View File

@ -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);

25
config/src/main/java/com/typesafe/config/impl/package.html Normal file
View File

@ -0,0 +1,25 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
Copyright (C) 2011 Typesafe Inc. <http://typesafe.com>
-->
</head>
<body bgcolor="white">
<p>
Internal implementation details that can change ABI at any time.
</p>
<p>
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 <code>impl</code> has any guarantees; it will change whenever someone
feels like changing it. If you feel you need access to something
in <code>impl</code>, <a href="https://github.com/typesafehub/config/issues">please
file a feature request</a>.
</p>
</body>
</html>

63
project/linksource.scala Normal file
View File

@ -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 <a href="../../../src-html/com/typesafe/config/Config.html#line.165"> 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)
}
}
}
}

2
project/plugins.sbt
View File

@ -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")