Skip to content

Commit

Permalink
ConfigValue API.
Browse files Browse the repository at this point in the history
Signed-off-by: Roberto Cortez <[email protected]>
  • Loading branch information
radcortez committed Apr 22, 2020
1 parent e6e7cc3 commit bb16cc6
Show file tree
Hide file tree
Showing 8 changed files with 460 additions and 18 deletions.
67 changes: 51 additions & 16 deletions api/src/main/java/org/eclipse/microprofile/config/Config.java
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,6 @@
* Additional reviews and feedback by Tomas Langer.
*
*******************************************************************************/

package org.eclipse.microprofile.config;

import java.lang.reflect.Array;
Expand All @@ -40,20 +39,24 @@
import java.util.Optional;

import org.eclipse.microprofile.config.spi.ConfigSource;
import org.eclipse.microprofile.config.spi.ConfigValue;
import org.eclipse.microprofile.config.spi.ConfigValueSource;
import org.eclipse.microprofile.config.spi.Converter;

/**
* Resolves the property value by searching through all configured {@link ConfigValueSource ConfigSources}. If the same
* property is specified in multiple {@link ConfigValueSource ConfigSources}, the value in the
* {@link ConfigValueSource} with the highest ordinal will be used.
* <p>
* Resolves the property value by searching through all configured
* {@link ConfigSource ConfigSources}. If the same property is specified in multiple
* {@link ConfigSource ConfigSources}, the value in the {@link ConfigSource} with the highest
* ordinal will be used.
* <p>If multiple {@link ConfigSource ConfigSources} are specified with
* the same ordinal, the {@link ConfigSource#getName()} will be used for sorting.
*
* If multiple {@link ConfigValueSource ConfigSources} are specified with the same ordinal, the
* {@link ConfigValueSource#getName()} will be used for sorting.
* <p>
*
* The config objects produced via the injection model {@code @Inject Config} are guaranteed to be serializable, while
* the programmatically created ones are not required to be serializable.
* <p>
*
* If one or more converters are registered for a class of a requested value then the registered {@link org.eclipse.microprofile.config.spi.Converter}
* which has the highest {@code @javax.annotation.Priority} is used to convert the string value retrieved from the config sources.
*
Expand Down Expand Up @@ -90,11 +93,11 @@
*/
@org.osgi.annotation.versioning.ProviderType
public interface Config {

/**
* Return the resolved property value with the specified type for the
* specified property name from the underlying {@linkplain ConfigSource configuration sources}.
* Return the resolved property value with the specified type for the specified property name from the underlying
* {@linkplain ConfigValueSource configuration sources}.
* <p>
*
* The configuration value is not guaranteed to be cached by the implementation, and may be expensive
* to compute; therefore, if the returned value is intended to be frequently used, callers should consider storing
* rather than recomputing it.
Expand All @@ -112,9 +115,25 @@ public interface Config {
<T> T getValue(String propertyName, Class<T> propertyType);

/**
* Return the resolved property values with the specified type for the
* specified property name from the underlying {@linkplain ConfigSource configuration sources}.
* Return the {@link ConfigValue} for the specified property name from the underlying
* {@linkplain ConfigValueSource configuration sources}.
* <p>
*
* The configuration value is not guaranteed to be cached by the implementation, and may be expensive
* to compute; therefore, if the returned value is intended to be frequently used, callers should consider storing
* rather than recomputing it.
*
* @param propertyName
* The configuration property name
* @return the ConfigValue, or {@code null} if the property is not present
*/
ConfigValue getConfigValue(String propertyName);

/**
* Return the resolved property values with the specified type for the specified property name from the
* underlying {@linkplain ConfigValueSource configuration sources}.
* <p>
*
* The configuration values are not guaranteed to be cached by the implementation, and may be expensive
* to compute; therefore, if the returned values are intended to be frequently used, callers should consider storing
* rather than recomputing them.
Expand All @@ -136,9 +155,10 @@ default <T> List<T> getValues(String propertyName, Class<T> propertyType) {
}

/**
* Return the resolved property value with the specified type for the
* specified property name from the underlying {@linkplain ConfigSource configuration sources}.
* Return the resolved property value with the specified type for the specified property name from the
* underlying {@linkplain ConfigValueSource configuration sources}.
* <p>
*
* The configuration value is not guaranteed to be cached by the implementation, and may be expensive
* to compute; therefore, if the returned value is intended to be frequently used, callers should consider storing
* rather than recomputing it.
Expand All @@ -158,9 +178,10 @@ default <T> List<T> getValues(String propertyName, Class<T> propertyType) {
<T> Optional<T> getOptionalValue(String propertyName, Class<T> propertyType);

/**
* Return the resolved property values with the specified type for the
* specified property name from the underlying {@linkplain ConfigSource configuration sources}.
* Return the resolved property values with the specified type for the specified property name from the
* underlying {@linkplain ConfigValueSource configuration sources}.
* <p>
*
* The configuration values are not guaranteed to be cached by the implementation, and may be expensive
* to compute; therefore, if the returned values are intended to be frequently used, callers should consider storing
* rather than recomputing them.
Expand All @@ -184,21 +205,25 @@ default <T> Optional<List<T>> getOptionalValues(String propertyName, Class<T> pr
/**
* Returns a sequence of configuration property names. The order of the returned property names is unspecified.
* <p>
*
* The returned property names are unique; that is, if a name is returned once by a given iteration, it will not be
* returned again during that same iteration.
* <p>
*
* There is no guarantee about the completeness or currency of the names returned, nor is there any guarantee that a
* name that is returned by the iterator will resolve to a non-empty value or be found in any configuration source
* associated with the configuration; for example, it is allowed for this method to return an empty set always.
* However, the implementation <em>should</em> return a set of names that is useful to a
* user that wishes to browse the configuration.
* <p>
*
* It is implementation-defined whether the returned names reflect a point-in-time "snapshot" of names, or an
* aggregation of multiple point-in-time "snapshots", or a more dynamic view of the available property names.
* Implementations are not required to return the same sequence of names on each iteration; however, the produced
* {@link java.util.Iterator Iterator} must adhere to the contract of that class, and must not return any more
* elements once its {@link java.util.Iterator#hasNext() hasNext()} method returns {@code false}.
* <p>
*
* The returned instance is thread safe and may be iterated concurrently. The individual iterators are not
* thread-safe.
*
Expand All @@ -212,8 +237,18 @@ default <T> Optional<List<T>> getOptionalValues(String propertyName, Class<T> pr
*
* @return the configuration sources
*/
@Deprecated
Iterable<ConfigSource> getConfigSources();

/**
* Return all of the currently registered {@linkplain ConfigValueSource configuration sources} for this
* configuration. The returned sources will be sorted by descending ordinal value and name, which can be iterated
* in a thread-safe manner.
*
* @return the configuration sources
*/
Iterable<ConfigValueSource> getConfigValueSources();

/**
* Return the {@link Converter} used by this instance to produce instances of the specified type from string values.
*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -76,11 +76,16 @@ public interface ConfigBuilder {
/**
* Add the specified {@link ConfigSource} instances to the configuration being built.
*
* @deprecated use {@linkplain #withSources(ConfigValueSource...)} with the newer api {@link ConfigValueSource}.
*
* @param sources the configuration sources
* @return this configuration builder instance
*/
@Deprecated
ConfigBuilder withSources(ConfigSource... sources);

ConfigBuilder withSources(ConfigValueSource... sources);

/**
* Add the specified {@link Converter} instances to the configuration being built.
* <p>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -88,11 +88,14 @@
* then its {@linkplain AutoCloseable#close() close method} will be called when
* the underlying configuration is released.
*
* @deprecated use the newer api {@link ConfigValueSource} which exposes a {@link ConfigValue} accessor style object.
*
* @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>
* @author <a href="mailto:[email protected]">John D. Ament</a>
*/
@Deprecated
public interface ConfigSource {
/**
* The name of the configuration ordinal property, "{@code config_ordinal}".
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -41,11 +41,13 @@
* {@linkplain ClassLoader#getResource(String) resource} which contains
* the fully qualified class name of the custom {@code ConfigSourceProvider} implementation.
*
* @deprecated use the newer api {@link ConfigValueSourceProvider}.
*
* @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>
*
*/
@Deprecated
public interface ConfigSourceProvider {

/**
Expand Down
161 changes: 161 additions & 0 deletions api/src/main/java/org/eclipse/microprofile/config/spi/ConfigValue.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,161 @@
/*
* Copyright (c) 2020 Contributors to the Eclipse Foundation
*
* See the NOTICE file(s) distributed with this work for additional
* information regarding copyright ownership.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* You may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package org.eclipse.microprofile.config.spi;

import java.util.Objects;

/**
* The ConfigValue is a metadata object that holds additional information after the lookup of a configuration.
* <p>
*
* Right now, it is able to hold information like the configuration name, value, the Config Source from where
* the configuration was loaded, the ordinal of the Config Source and a line number from where the configuration was
* read if exists.
* <p>
*
* This is used together with {@link ConfigValueSource} to expose the Configuration lookup metadata.
*
* @author <a href="mailto:[email protected]">Roberto Cortez</a>
*/
public class ConfigValue {
private final String name;
private final String value;
private final String configSourceName;
private final int configSourceOrdinal;

private final int lineNumber;

private ConfigValue(final ConfigValueBuilder builder) {
this.name = builder.name;
this.value = builder.value;
this.configSourceName = builder.configSourceName;
this.configSourceOrdinal = builder.configSourceOrdinal;
this.lineNumber = builder.lineNumber;
}

public String getName() {
return name;
}

public String getValue() {
return value;
}

public String getConfigSourceName() {
return configSourceName;
}

public int getConfigSourceOrdinal() {
return configSourceOrdinal;
}

public int getLineNumber() {
return lineNumber;
}

public ConfigValue withName(final String name) {
return from().withName(name).build();
}

public ConfigValue withValue(final String value) {
return from().withValue(value).build();
}

public ConfigValue withConfigSourceName(final String configSourceName) {
return from().withConfigSourceName(configSourceName).build();
}

public ConfigValue withConfigSourceOrdinal(final int configSourceOrdinal) {
return from().withConfigSourceOrdinal(configSourceOrdinal).build();
}

public ConfigValue withLineNumber(final int lineNumber) {
return from().withLineNumber(lineNumber).build();
}

@Override
public boolean equals(final Object o) {
if (this == o) {
return true;
}
if (o == null || getClass() != o.getClass()) {
return false;
}
final ConfigValue that = (ConfigValue) o;
return name.equals(that.name) &&
value.equals(that.value) &&
configSourceName.equals(that.configSourceName);
}

@Override
public int hashCode() {
return Objects.hash(name, value, configSourceName);
}

ConfigValueBuilder from() {
return new ConfigValueBuilder()
.withName(name)
.withValue(value)
.withConfigSourceName(configSourceName)
.withConfigSourceOrdinal(configSourceOrdinal)
.withLineNumber(lineNumber);
}

public static ConfigValueBuilder builder() {
return new ConfigValueBuilder();
}

public static class ConfigValueBuilder {
private String name;
private String value;
private String configSourceName;
private int configSourceOrdinal;
private int lineNumber = -1;

public ConfigValueBuilder withName(final String name) {
this.name = name;
return this;
}

public ConfigValueBuilder withValue(final String value) {
this.value = value;
return this;
}

public ConfigValueBuilder withConfigSourceName(final String configSourceName) {
this.configSourceName = configSourceName;
return this;
}

public ConfigValueBuilder withConfigSourceOrdinal(final int configSourceOrdinal) {
this.configSourceOrdinal = configSourceOrdinal;
return this;
}

public ConfigValueBuilder withLineNumber(final int lineNumber) {
this.lineNumber = lineNumber;
return this;
}

public ConfigValue build() {
return new ConfigValue(this);
}
}
}
Loading

0 comments on commit bb16cc6

Please sign in to comment.