Skip to content

Commit

Permalink
Improve Javadoc #82
Browse files Browse the repository at this point in the history
Signed-off-by: Emily Jiang <[email protected]>
  • Loading branch information
Emily-Jiang committed Mar 7, 2017
1 parent 66e2762 commit e12b038
Show file tree
Hide file tree
Showing 6 changed files with 37 additions and 37 deletions.
12 changes: 5 additions & 7 deletions api/src/main/java/org/eclipse/microprofile/config/Config.java
Original file line number Diff line number Diff line change
Expand Up @@ -50,14 +50,14 @@ public interface Config {
* Return the resolved property value with the specified type for the
* specified property name from the underlying {@link ConfigSource ConfigSources}.
*
* If this method gets used very often then consider to locally store the configured value.
* If this method is used frequently consider caching the value.
*
* @param <T>
* the property type
* @param propertyName
* The configuration propertyName.
* @param propertyType
* The type into which the resolve property value should get converted
* The type into which the resolve property value should be converted
* @return the resolved property value as an Optional of the requested type.
* The {@link IllegalArgumentException} will be thrown if the property cannot be converted to the specified type.
*/
Expand All @@ -69,13 +69,11 @@ public interface Config {
*
* @param propertyName
* The configuration propertyName.
* @return The resolved property value as a String-Optional, which will bypass converters.
* @return The resolved property value as a String, which will bypass any converters.
*
* @throws IllegalArgumentException
* is thrown if the propertyName maps to an object that is not a
* String.
*
*/
Optional<String> getString(String propertyName);
String getRawString(String propertyName);

/**
* Return a collection of property names.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
* </p>
*
* <p>
* A {@link Config} contains the configuration for a certain situation. That
* A {@link Config} contains the configuration for a certain situation. This
* might be the configuration found in a certain ClassLoader or even a manually
* created Configuration
* </p>
Expand All @@ -44,7 +44,8 @@
* A 'Configuration' consists of the information collected from the registered {@link ConfigSource ConfigSources}.
* These {@link ConfigSource ConfigSources} get sorted according to
* their <em>ordinal</em> defined via {@link ConfigSource#getOrdinal()}.
* That way it is possible to overwrite configuration with lower importance from outside.
* Thus it is possible to override configuration packaged with an application with configuration
* from outside the application package.
* </p>
*
* <p>
Expand Down Expand Up @@ -110,12 +111,12 @@ public static ConfigBuilder getBuilder() {

/**
* Register a given {@link Config} within the Application (or Module) identified by the given ClassLoader.
* If the ClassLoader is {@code null} then the current Application will be used.
* If the ClassLoader is {@code null} then the current thread's ContextClassLoader will be used.
*
* @param config
* which should get registered
* the config that will be registered
* @param classLoader
* which identifies the Application or Module the given Config should get associated with.
* the Application or Module the given Config will be associated with.
*
* @throws IllegalStateException
* if there is already a Config registered within the Application.
Expand All @@ -127,7 +128,7 @@ public static void setConfig(Config config, ClassLoader classLoader) {

/**
* A {@link Config} normally gets released if the Application it is associated with gets destroyed.
* Invoke this method if you like to destroy the Config prematurely.
* Invoke this method if you would like to destroy the Config prematurely.
*
* If the given Config is associated within an Application then it will be unregistered.
*/
Expand All @@ -142,7 +143,7 @@ public static void releaseConfig(Config config) {
*/
public interface ConfigBuilder {
/**
* Add the default config sources appearing on the builder's classpath
* Add the default config sources that are on the builder's classpath
* including:
* <ol>
* <li>System properties</li>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,10 @@

/**
* This class is not intended to be used by end-users but for
* portable container integration purpose only!
* portable container integration purpose only.
*
* Service provider for ConfigProviderResolver. The implementation registers
* itself via {@link java.util.ServiceLoader} mechanism.
* itself via the {@link java.util.ServiceLoader} mechanism.
*
* @author <a href="mailto:[email protected]">Mark Struberg</a>
* @author <a href="mailto:[email protected]">Romain Manni-Bucau</a>
Expand Down Expand Up @@ -77,12 +77,12 @@ public static ConfigProviderResolver instance() {
if (instance != null) {
return instance;
}

ClassLoader cl = AccessController.doPrivileged(new PrivilegedAction<ClassLoader>() {
@Override
public ClassLoader run() {
public ClassLoader run() {
return Thread.currentThread().getContextClassLoader();
}
}
});
if (cl == null) {
cl = ConfigProviderResolver.class.getClassLoader();
Expand All @@ -91,7 +91,8 @@ public ClassLoader run() {
ConfigProviderResolver newInstance = loadSpi(cl);

if (newInstance == null) {
throw new IllegalStateException("No ConfigProviderResolver implementation found!");
throw new IllegalStateException(
"No ConfigProviderResolver implementation found!");
}

instance = newInstance;
Expand All @@ -110,21 +111,22 @@ private static ConfigProviderResolver loadSpi(ClassLoader cl) {
ConfigProviderResolver instance = loadSpi(cl.getParent());

if (instance == null) {
ServiceLoader<ConfigProviderResolver> sl = ServiceLoader.load(ConfigProviderResolver.class, cl);
ServiceLoader<ConfigProviderResolver> sl = ServiceLoader.load(
ConfigProviderResolver.class, cl);
for (ConfigProviderResolver spi : sl) {
if (instance != null) {
throw new IllegalStateException("Multiple ConfigResolverProvider implementations found: " + spi.getClass().getName()
+ " and " + instance.getClass().getName());
}
else {
throw new IllegalStateException(
"Multiple ConfigResolverProvider implementations found: "
+ spi.getClass().getName() + " and "
+ instance.getClass().getName());
} else {
instance = spi;
}
}
}
return instance;
}


/**
* Set the instance. It is used by OSGi environment while service loader
* pattern is not supported.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,18 +20,18 @@
import java.util.Map;

/**
* <p> Represent a config source, which provides properties. The config source includes: properties, xml, json files or datastore. <p>
* <p> Represent a config source, which provides properties. The config source can encapsulate: properties, xml, json files or datastore data. <p>
* The default config sources:
* <ol>
* <li>System properties (ordinal=400)</li>
* <li>Environment properties (ordinal=300)</li>
* <li>/META-INF/microprofile-config.properties (ordinal=100)</li>
* </ol>
*
* <p>A ConfigSource will get picked up via the
* {@link java.util.ServiceLoader} mechanism and must get registered via
* <p>ConfigSource will get picked up via the
* {@link java.util.ServiceLoader} mechanism and and can be registered via
* META-INF/services/javax.config.spi.ConfigSource</p>
* The other custom config source can be added programmatically via {@link org.eclipse.microprofile.config.ConfigProvider}.
* Other custom config source can be added programmatically via {@link org.eclipse.microprofile.config.ConfigProvider}.
* @author <a href="mailto:[email protected]">Mark Struberg</a>
* @author <a href="mailto:[email protected]">Gerhard Petracek</a>
* @author <a href="mailto:[email protected]">Emily Jiang</a>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,17 +18,16 @@

package org.eclipse.microprofile.config.spi;


/**
* <p>Implement this interfaces to provide multiple ConfigSources.
* This is e.g. needed if there are multiple property files of a given name.</p>
* This is needed if there are multiple property files of a given name.</p>
*
* <p>If a ConfigSource like JNDI only exists once, then there is no need
* to implement it via the ConfigSourceProvider but should directly
* expose a {@link ConfigSource}.</p>
* <p>If a single ConfigSource exists, then there is no need
* to register it using a custom implementation of ConfigSourceProvider, it can be
* registered directly as a {@link ConfigSource}.</p>
*
* <p>A ConfigSourceProvider will get picked up via the
* {@link java.util.ServiceLoader} mechanism and must get registered via
* {@link java.util.ServiceLoader} mechanism and can be registered via
* META-INF/services/javax.config.spi.ConfigSourceProvider</p>
*
* @author <a href="mailto:[email protected]">Mark Struberg</a>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
* <p>A Converter can specify a {@link javax.annotation.Priority}.
* If no priority is explicitly assigned, the value of 100 is assumed.</p>
*
* <p>If multiple Converter get found the one with the highest priority will be used.</p>
* <p>If multiple Converters are found, the one with the highest priority will be used.</p>
*
* <p>The Converter for the following types are automatically enabled:</p>
* <ul>
Expand Down

0 comments on commit e12b038

Please sign in to comment.