TAMAYA-260: Implemented Microprofile.io Config API, added basic tests.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/commit/2852c48e Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/tree/2852c48e Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/diff/2852c48e Branch: refs/heads/master Commit: 2852c48e11e932d7b42ed3a09f71a8c792990bb1 Parents: 7efb64e Author: anatole <anat...@apache.org> Authored: Fri Mar 24 22:53:34 2017 +0100 Committer: anatole <anat...@apache.org> Committed: Fri Mar 24 22:53:34 2017 +0100 ---------------------------------------------------------------------- .../microprofile/MicroprofileAdapter.java | 182 +++++++++++++++++++ .../tamaya/microprofile/MicroprofileConfig.java | 82 +++++++++ .../microprofile/MicroprofileConfigBuilder.java | 84 +++++++++ .../MicroprofileConfigProviderResolver.java | 73 ++++++++ .../microprofile/MicroprofileConfigSource.java | 78 ++++++++ .../MicroprofileConfigSourceProvider.java | 64 +++++++ .../microprofile/MicroprofileConverter.java | 50 +++++ .../microprofile/TamayaConfiguration.java | 96 ++++++++++ .../microprofile/TamayaPropertyConverter.java | 48 +++++ .../microprofile/TamayaPropertySource.java | 76 ++++++++ .../TamayaPropertySourceProvider.java | 56 ++++++ .../org/eclipse/microprofile/config/Config.java | 126 +++++++++++++ .../microprofile/config/ConfigProvider.java | 102 +++++++++++ .../config/inject/ConfigProperty.java | 112 ++++++++++++ .../config/inject/package-info.java | 40 ++++ .../microprofile/config/package-info.java | 75 ++++++++ .../microprofile/config/spi/ConfigBuilder.java | 83 +++++++++ .../config/spi/ConfigProviderResolver.java | 164 +++++++++++++++++ .../microprofile/config/spi/ConfigSource.java | 107 +++++++++++ .../config/spi/ConfigSourceProvider.java | 58 ++++++ .../microprofile/config/spi/Converter.java | 77 ++++++++ .../microprofile/config/spi/package-info.java | 30 +++ ...croprofile.config.spi.ConfigProviderResolver | 20 ++ .../MicroprofileConfigProviderTest.java | 63 +++++++ .../microprofile/MicroprofileConfigTest.java | 89 +++++++++ 25 files changed, 2035 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileAdapter.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileAdapter.java b/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileAdapter.java new file mode 100644 index 0000000..29f563c --- /dev/null +++ b/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileAdapter.java @@ -0,0 +1,182 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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.apache.tamaya.microprofile; + + +import org.apache.tamaya.*; +import org.apache.tamaya.spi.ConfigurationContextBuilder; +import org.apache.tamaya.spi.PropertyConverter; +import org.apache.tamaya.spi.PropertySource; +import org.apache.tamaya.spi.PropertyValue; +import org.eclipse.microprofile.config.Config; +import org.eclipse.microprofile.config.spi.ConfigBuilder; +import org.eclipse.microprofile.config.spi.ConfigSource; +import org.eclipse.microprofile.config.spi.Converter; + +import java.util.*; + +/** + * Utility class for adapting microprofile artifacts into Tamaya artifacts and vice versa. + */ +public final class MicroprofileAdapter{ + + /** + * Singleton constructor. + */ + private MicroprofileAdapter(){} + + /** + * Converts a Tamaya {@link Configuration} into a Microprofile.io {@Config}. + * @param config the Tamaya {@link Configuration} instance, not null. + * @return the corresponding Microprofile.io {@Config} instance, never null. + */ + public static Config toConfig(Configuration config){ + if(config instanceof TamayaConfiguration){ + return ((TamayaConfiguration)config).getConfig(); + } + return new MicroprofileConfig(config); + } + + /** + * Converts a Microprofile {@link Config}s into Tamaya {@Configuration}s. + * @param config the Microprofile {@link Config} instance, not null. + * @return the corresponding Tamaya {@Configuration} instance, never null. + */ + public static Configuration toConfiguration(Config config){ + if(config instanceof MicroprofileConfig){ + return ((MicroprofileConfig)config).getConfiguration(); + } + return new TamayaConfiguration(config); + } + + /** + * Converts a Tamaya {@link PropertySource}s into a Microprofile.io {@ConfigSource}. + * @param propertySources the Tamaya {@link PropertySource} instances, not null. + * @return the corresponding Microprofile.io {@ConfigSource} instance, never null. + */ + public static List<ConfigSource> toConfigSources(Iterable<PropertySource> propertySources) { + List<ConfigSource> configSources = new ArrayList<>(); + for(PropertySource ps:propertySources){ + configSources.add(toConfigSource(ps)); + } + return configSources; + } + + /** + * Converts a Microprofile {@link ConfigSource}s into Tamaya {@PropertySource}s. + * @param configSources the Microprofile {@link ConfigSource} instances, not null. + * @return the corresponding Tamaya {@PropertySource} instances, never null. + */ + public static List<PropertySource> toPropertySources(Iterable<ConfigSource> configSources) { + List<PropertySource> propertySources = new ArrayList<>(); + for(ConfigSource cs:configSources){ + propertySources.add(toPropertySource(cs)); + } + return propertySources; + } + + /** + * Converts a Tamaya {@link PropertySource} into a Microprofile.io {@ConfigSource}. + * @param propertySource the Tamaya {@link PropertySource} instance, not null. + * @return the corresponding Microprofile.io {@ConfigSource} instance, never null. + */ + public static ConfigSource toConfigSource(PropertySource propertySource) { + if(propertySource instanceof TamayaPropertySource){ + return ((TamayaPropertySource)propertySource).getConfigSource(); + } + return new MicroprofileConfigSource(propertySource); + } + + /** + * Converts a Microprofile {@link ConfigSource} into a Tamaya {@PropertySource}. + * @param configSource the Microprofile {@link ConfigSource} instance, not null. + * @return the corresponding Tamaya {@PropertySource} instance, never null. + */ + public static PropertySource toPropertySource(ConfigSource configSource) { + if(configSource instanceof MicroprofileConfigSource){ + return ((MicroprofileConfigSource)configSource).getPropertySource(); + } + return new TamayaPropertySource(configSource); + } + + /** + * Converts a Microprofile {@link Converter} into a Tamaya {@PropertyConverter}. + * @param converter the Microprofile {@link Converter} instance, not null. + * @return the corresponding Tamaya {@PropertyConverter} instance, never null. + */ + public static <T> PropertyConverter<T> toPropertyConverter(Converter<T> converter) { + if(converter instanceof MicroprofileConverter){ + return ((MicroprofileConverter)converter).getPropertyConverter(); + } + return new TamayaPropertyConverter(converter); + } + + /** + * Converts a Tamaya {@link PropertyConverter} into a Microprofile.io {@Converter}. + * @param converter the Tamaya {@link PropertyConverter} instance, not null. + * @return the corresponding Microprofile.io {@Converter} instance, never null. + */ + public static <T> Converter<T> toConverter(PropertyConverter<T> converter) { + if(converter instanceof TamayaPropertyConverter){ + return ((TamayaPropertyConverter)converter).getConverter(); + } + return new MicroprofileConverter(converter); + } + + /** + * Converts a Tamaya {@link ConfigurationContextBuilder} into a Microprofile.io {@ConfigBuilder}. + * @param builder the Tamaya {@link ConfigurationContextBuilder} instance, not null. + * @return the corresponding Microprofile.io {@ConfigBuilder} instance, never null. + */ + public static ConfigBuilder toConfigBuilder(ConfigurationContextBuilder builder) { + return new MicroprofileConfigBuilder(builder); + } + + /** + * Converts the given Tamaya key, value map into a corresponding String based map, hereby + * omitting all meta-entries. + * @param properties the Tamaya key, value map, not null. + * @return the corresponding String based map, never null. + */ + public static Map<String, String> toStringMap(Map<String, PropertyValue> properties) { + Map<String, String> valueMap = new HashMap<>(properties.size()); + for(Map.Entry<String,PropertyValue> en:properties.entrySet()){ + if(en.getValue().getValue()!=null) { + valueMap.put(en.getKey(), en.getValue().getValue()); + } + } + return valueMap; + } + + /** + * Converts the given String based key, value map into a corresponding String,PropertyValue + * based map. + * @param properties the String based key, value map, not null. + * @param source the source of the entries, not null. + * @return the corresponding String,PropertyValue based map, never null. + */ + public static Map<String, PropertyValue> toPropertyValueMap(Map<String, String> properties, String source) { + Map<String, PropertyValue> valueMap = new HashMap<>(properties.size()); + for(Map.Entry<String,String> en:properties.entrySet()){ + valueMap.put(en.getKey(), PropertyValue.of(en.getKey(), en.getValue(), source)); + } + return valueMap; + } + +} http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConfig.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConfig.java b/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConfig.java new file mode 100644 index 0000000..fa8d7b0 --- /dev/null +++ b/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConfig.java @@ -0,0 +1,82 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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.apache.tamaya.microprofile; + +import org.apache.tamaya.ConfigException; +import org.apache.tamaya.Configuration; +import org.apache.tamaya.spi.PropertySource; +import org.eclipse.microprofile.config.Config; +import org.eclipse.microprofile.config.spi.ConfigSource; + +import java.util.*; + +/** + * Microprofile {@link ConfigSource} implementation that wraps a {@link PropertySource} instance. + */ +final class MicroprofileConfig implements Config { + + private Configuration delegate; + + MicroprofileConfig(Configuration delegate){ + this.delegate = Objects.requireNonNull(delegate); + } + + public Configuration getConfiguration(){ + return this.delegate; + } + + + @Override + public <T> T getValue(String propertyName, Class<T> propertyType) { + T value = null; + try{ + value = delegate.get(propertyName, propertyType); + }catch(ConfigException e){ + if(e.toString().contains("Unparseable")){ + throw new IllegalArgumentException("Invalid type: " + propertyType.getName()); + } + } + if(value == null){ + throw new NoSuchElementException("No such config property: " + propertyName); + } + return value; + } + + @Override + public <T> Optional<T> getOptionalValue(String propertyName, Class<T> propertyType) { + return Optional.ofNullable(delegate.get(propertyName, propertyType)); + } + + @Override + public Iterable<String> getPropertyNames() { + return delegate.getProperties().keySet(); + } + + @Override + public Iterable<ConfigSource> getConfigSources() { + return MicroprofileAdapter.toConfigSources(delegate.getContext().getPropertySources()); + } + + @Override + public String toString() { + return "MicroprofileConfig{" + + "delegate=" + delegate + + '}'; + } +} http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConfigBuilder.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConfigBuilder.java b/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConfigBuilder.java new file mode 100644 index 0000000..fa46fea --- /dev/null +++ b/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConfigBuilder.java @@ -0,0 +1,84 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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.apache.tamaya.microprofile; + +import org.apache.tamaya.ConfigurationProvider; +import org.apache.tamaya.TypeLiteral; +import org.apache.tamaya.spi.ConfigurationContextBuilder; +import org.eclipse.microprofile.config.Config; +import org.eclipse.microprofile.config.spi.ConfigBuilder; +import org.eclipse.microprofile.config.spi.ConfigSource; +import org.eclipse.microprofile.config.spi.Converter; + +import java.util.Objects; + +/** + * Created by atsticks on 23.03.17. + */ +final class MicroprofileConfigBuilder implements ConfigBuilder{ + + private ConfigurationContextBuilder contextBuilder; + + MicroprofileConfigBuilder(ConfigurationContextBuilder contextBuilder){ + this.contextBuilder = Objects.requireNonNull(contextBuilder); + } + + public ConfigurationContextBuilder getConfigurationContextBuilder(){ + return contextBuilder; + } + + @Override + public ConfigBuilder addDefaultSources() { + contextBuilder.addDefaultPropertySources(); + return this; + } + + @Override + public ConfigBuilder forClassLoader(ClassLoader loader) { + return null; + } + + @Override + public ConfigBuilder withSources(ConfigSource... sources) { + for(ConfigSource source:sources){ + contextBuilder.addPropertySources(MicroprofileAdapter.toPropertySource(source)); + } + return this; + } + + @Override + public ConfigBuilder withConverters(Converter<?>... converters) { + for(Converter<?> converter:converters){ + TypeLiteral lit = TypeLiteral.of(converter.getClass()); + TypeLiteral target = TypeLiteral.of(lit.getType()); + contextBuilder.removePropertyConverters(target); + contextBuilder.addPropertyConverters( + target, + MicroprofileAdapter.toPropertyConverter(converter)); + } + return this; + } + + @Override + public Config build() { + return MicroprofileAdapter.toConfig(ConfigurationProvider.createConfiguration( + contextBuilder.build() + )); + } +} http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConfigProviderResolver.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConfigProviderResolver.java b/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConfigProviderResolver.java new file mode 100644 index 0000000..f1d336e --- /dev/null +++ b/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConfigProviderResolver.java @@ -0,0 +1,73 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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.apache.tamaya.microprofile; + +import org.apache.tamaya.ConfigurationProvider; +import org.eclipse.microprofile.config.Config; +import org.eclipse.microprofile.config.spi.ConfigBuilder; +import org.eclipse.microprofile.config.spi.ConfigProviderResolver; + +import java.util.Map; +import java.util.concurrent.ConcurrentHashMap; + +/** + * Created by atsticks on 23.03.17. + */ +public class MicroprofileConfigProviderResolver extends ConfigProviderResolver { + + private Map<ClassLoader, Config> configs = new ConcurrentHashMap<>(); + + @Override + public Config getConfig() { + return getConfig(Thread.currentThread().getContextClassLoader()); + } + + @Override + public Config getConfig(ClassLoader loader) { + Config config = this.configs.get(loader); + if(config==null){ + config = MicroprofileAdapter.toConfig(ConfigurationProvider.getConfiguration()); + this.configs.put(loader, config); + } + return config; + } + + @Override + public ConfigBuilder getBuilder() { + return new MicroprofileConfigBuilder(ConfigurationProvider.getConfigurationContextBuilder()); + } + + @Override + public void registerConfig(Config config, ClassLoader classLoader) { + if(configs.containsKey(classLoader)){ + throw new IllegalArgumentException("Alreadsy a config registered with classloader: " + classLoader); + } + this.configs.put(classLoader, config); + } + + @Override + public void releaseConfig(Config config) { + for(Map.Entry<ClassLoader, Config> en: this.configs.entrySet()){ + if(en.getValue().equals(config)){ + this.configs.remove(en.getKey()); + return; + } + } + } +} http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConfigSource.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConfigSource.java b/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConfigSource.java new file mode 100644 index 0000000..fbb02b4 --- /dev/null +++ b/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConfigSource.java @@ -0,0 +1,78 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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.apache.tamaya.microprofile; + +import org.apache.tamaya.spi.PropertySource; +import org.apache.tamaya.spi.PropertyValue; +import org.eclipse.microprofile.config.spi.ConfigSource; + +import java.util.HashMap; +import java.util.Map; +import java.util.Objects; + +/** + * Microprofile {@link ConfigSource} implementation that wraps a {@link PropertySource} instance. + */ +final class MicroprofileConfigSource implements ConfigSource{ + + private PropertySource delegate; + + MicroprofileConfigSource(PropertySource propertySource){ + this.delegate = Objects.requireNonNull(propertySource); + } + + public PropertySource getPropertySource(){ + return this.delegate; + } + + @Override + public int getOrdinal() { + return delegate.getOrdinal(); + } + + @Override + public String getName() { + return delegate.getName(); + } + + @Override + public String getValue(String key) { + PropertyValue value = delegate.get(key); + if(value!=null){ + return value.getValue(); + } + return null; + } + + @Override + public Map<String, String> getProperties() { + return toMap(delegate.getProperties()); + } + + private Map<String, String> toMap(Map<String, PropertyValue> properties) { + Map<String, String> valueMap = new HashMap<>(properties.size()); + for(Map.Entry<String,PropertyValue> en:properties.entrySet()){ + if(en.getValue().getValue()!=null) { + valueMap.put(en.getKey(), en.getValue().getValue()); + } + } + return valueMap; + } + +} http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConfigSourceProvider.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConfigSourceProvider.java b/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConfigSourceProvider.java new file mode 100644 index 0000000..c31224f --- /dev/null +++ b/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConfigSourceProvider.java @@ -0,0 +1,64 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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.apache.tamaya.microprofile; + +import org.apache.tamaya.spi.PropertySource; +import org.apache.tamaya.spi.PropertySourceProvider; +import org.apache.tamaya.spi.PropertyValue; +import org.eclipse.microprofile.config.spi.ConfigSource; +import org.eclipse.microprofile.config.spi.ConfigSourceProvider; + +import java.util.*; + +/** + * Microprofile {@link ConfigSource} implementation that wraps a {@link PropertySource} instance. + */ +final class MicroprofileConfigSourceProvider implements ConfigSourceProvider{ + + private PropertySourceProvider delegate; + + MicroprofileConfigSourceProvider(PropertySourceProvider propertySourceProvider){ + this.delegate = Objects.requireNonNull(propertySourceProvider); + } + + public PropertySourceProvider getPropertySourceProvider(){ + return this.delegate; + } + + + private Map<String, String> toMap(Map<String, PropertyValue> properties) { + Map<String, String> valueMap = new HashMap<>(properties.size()); + for(Map.Entry<String,PropertyValue> en:properties.entrySet()){ + if(en.getValue().getValue()!=null) { + valueMap.put(en.getKey(), en.getValue().getValue()); + } + } + return valueMap; + } + + @Override + public Iterable<ConfigSource> getConfigSources(ClassLoader forClassLoader) { + if(delegate instanceof TamayaPropertySourceProvider){ + return ((TamayaPropertySourceProvider)delegate).getConfigSourceProvider() + .getConfigSources(forClassLoader); + }else { + return MicroprofileAdapter.toConfigSources(delegate.getPropertySources()); + } + } +} http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConverter.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConverter.java b/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConverter.java new file mode 100644 index 0000000..2ee42b7 --- /dev/null +++ b/microprofile/src/main/java/org/apache/tamaya/microprofile/MicroprofileConverter.java @@ -0,0 +1,50 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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.apache.tamaya.microprofile; + + +import org.apache.tamaya.TypeLiteral; +import org.apache.tamaya.spi.ConversionContext; +import org.apache.tamaya.spi.PropertyConverter; +import org.eclipse.microprofile.config.spi.ConfigSource; +import org.eclipse.microprofile.config.spi.Converter; + +import java.util.Objects; + +/** + * Property source implementation that wraps a Microprofile {@link ConfigSource} instance. + */ +final class MicroprofileConverter<T> implements Converter<T> { + + private PropertyConverter<T> delegate; + + MicroprofileConverter(PropertyConverter<T> delegate){ + this.delegate = Objects.requireNonNull(delegate); + } + + public PropertyConverter<T> getPropertyConverter(){ + return this.delegate; + } + + @Override + public T convert(String value) { + return delegate.convert(value, new ConversionContext.Builder("microprofile:no-key", TypeLiteral.of( + TypeLiteral.of(getClass()).getType())).build()); + } +} http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/apache/tamaya/microprofile/TamayaConfiguration.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/apache/tamaya/microprofile/TamayaConfiguration.java b/microprofile/src/main/java/org/apache/tamaya/microprofile/TamayaConfiguration.java new file mode 100644 index 0000000..8fb87cf --- /dev/null +++ b/microprofile/src/main/java/org/apache/tamaya/microprofile/TamayaConfiguration.java @@ -0,0 +1,96 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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.apache.tamaya.microprofile; + +import org.apache.tamaya.ConfigOperator; +import org.apache.tamaya.ConfigQuery; +import org.apache.tamaya.Configuration; +import org.apache.tamaya.TypeLiteral; +import org.apache.tamaya.spi.ConfigurationContext; +import org.eclipse.microprofile.config.Config; + +import java.util.*; + +/** + * Created by atsticks on 23.03.17. + */ +class TamayaConfiguration implements Configuration{ + + private Config delegate; + + TamayaConfiguration(Config config){ + this.delegate = Objects.requireNonNull(config); + } + + public Config getConfig(){ + return delegate; + } + + @Override + public String get(String key) { + return this.delegate.getOptionalValue(key, String.class).orElse(null); + } + + @Override + public String getOrDefault(String key, String defaultValue) { + return this.delegate.getOptionalValue(key, String.class).orElse(defaultValue); + } + + @Override + public <T> T getOrDefault(String key, Class<T> type, T defaultValue) { + return this.delegate.getOptionalValue(key, type).orElse(defaultValue); + } + + @Override + public <T> T get(String key, Class<T> type) { + return this.delegate.getOptionalValue(key, type).orElseThrow( + () -> new NoSuchElementException("Missing key: " + key)); + } + + @Override + public <T> T get(String key, TypeLiteral<T> type) { + return this.delegate.getOptionalValue(key, type.getRawType()).orElseThrow( + () -> new NoSuchElementException("Missing key: " + key)); + } + + @Override + public <T> T getOrDefault(String key, TypeLiteral<T> type, T defaultValue) { + return null; + } + + @Override + public Map<String, String> getProperties() { + return null; + } + + @Override + public Configuration with(ConfigOperator operator) { + return operator.operate(this); + } + + @Override + public <T> T query(ConfigQuery<T> query) { + return query.query(this); + } + + @Override + public ConfigurationContext getContext() { + return null; + } +} http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/apache/tamaya/microprofile/TamayaPropertyConverter.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/apache/tamaya/microprofile/TamayaPropertyConverter.java b/microprofile/src/main/java/org/apache/tamaya/microprofile/TamayaPropertyConverter.java new file mode 100644 index 0000000..6a33ffb --- /dev/null +++ b/microprofile/src/main/java/org/apache/tamaya/microprofile/TamayaPropertyConverter.java @@ -0,0 +1,48 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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.apache.tamaya.microprofile; + + +import org.apache.tamaya.spi.ConversionContext; +import org.apache.tamaya.spi.PropertyConverter; +import org.eclipse.microprofile.config.spi.ConfigSource; +import org.eclipse.microprofile.config.spi.Converter; + +import java.util.Objects; + +/** + * Property source implementation that wraps a Microprofile {@link ConfigSource} instance. + */ +final class TamayaPropertyConverter<T> implements PropertyConverter<T> { + + private Converter<T> delegate; + + TamayaPropertyConverter(Converter<T> delegate){ + this.delegate = Objects.requireNonNull(delegate); + } + + public Converter<T> getConverter(){ + return this.delegate; + } + + @Override + public T convert(String value, ConversionContext context) { + return delegate.convert(value); + } +} http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/apache/tamaya/microprofile/TamayaPropertySource.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/apache/tamaya/microprofile/TamayaPropertySource.java b/microprofile/src/main/java/org/apache/tamaya/microprofile/TamayaPropertySource.java new file mode 100644 index 0000000..d67db23 --- /dev/null +++ b/microprofile/src/main/java/org/apache/tamaya/microprofile/TamayaPropertySource.java @@ -0,0 +1,76 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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.apache.tamaya.microprofile; + +import org.apache.tamaya.spi.PropertySource; +import org.apache.tamaya.spi.PropertyValue; +import org.eclipse.microprofile.config.spi.ConfigSource; + +import java.util.HashMap; +import java.util.Map; +import java.util.Objects; + +/** + * Property source implementation that wraps a Microprofile {@link ConfigSource} instance. + */ +final class TamayaPropertySource implements PropertySource{ + + private ConfigSource delegate; + + TamayaPropertySource(ConfigSource configSource){ + this.delegate = Objects.requireNonNull(configSource); + } + + public ConfigSource getConfigSource(){ + return this.delegate; + } + + @Override + public int getOrdinal() { + return delegate.getOrdinal(); + } + + @Override + public String getName() { + return delegate.getName(); + } + + @Override + public PropertyValue get(String key) { + return PropertyValue.of(key, delegate.getValue(key),getName()); + } + + @Override + public Map<String, PropertyValue> getProperties() { + return toValueMap(delegate.getProperties()); + } + + private Map<String, PropertyValue> toValueMap(Map<String, String> properties) { + Map<String, PropertyValue> valueMap = new HashMap<>(properties.size()); + for(Map.Entry<String,String> en:properties.entrySet()){ + valueMap.put(en.getKey(), PropertyValue.of(en.getKey(), en.getValue(), getName())); + } + return valueMap; + } + + @Override + public boolean isScannable() { + return true; + } +} http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/apache/tamaya/microprofile/TamayaPropertySourceProvider.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/apache/tamaya/microprofile/TamayaPropertySourceProvider.java b/microprofile/src/main/java/org/apache/tamaya/microprofile/TamayaPropertySourceProvider.java new file mode 100644 index 0000000..8e910bb --- /dev/null +++ b/microprofile/src/main/java/org/apache/tamaya/microprofile/TamayaPropertySourceProvider.java @@ -0,0 +1,56 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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.apache.tamaya.microprofile; + + +import org.apache.tamaya.spi.PropertySource; +import org.apache.tamaya.spi.PropertySourceProvider; +import org.eclipse.microprofile.config.spi.ConfigSource; +import org.eclipse.microprofile.config.spi.ConfigSourceProvider; + +import java.util.*; + +/** + * Microprofile {@link ConfigSource} implementation that wraps a {@link PropertySource} instance. + */ +final class TamayaPropertySourceProvider implements PropertySourceProvider{ + + private ConfigSourceProvider delegate; + + TamayaPropertySourceProvider(ConfigSourceProvider configSourceProvider){ + this.delegate = Objects.requireNonNull(configSourceProvider); + } + + public ConfigSourceProvider getConfigSourceProvider(){ + return this.delegate; + } + + + @Override + public Collection<PropertySource> getPropertySources() { + if(delegate instanceof MicroprofileConfigSourceProvider){ + return ((MicroprofileConfigSourceProvider)delegate).getPropertySourceProvider() + .getPropertySources(); + }else { + return MicroprofileAdapter.toPropertySources( + delegate.getConfigSources(Thread.currentThread().getContextClassLoader())); + } + } + +} http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/eclipse/microprofile/config/Config.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/eclipse/microprofile/config/Config.java b/microprofile/src/main/java/org/eclipse/microprofile/config/Config.java new file mode 100644 index 0000000..6a888dd --- /dev/null +++ b/microprofile/src/main/java/org/eclipse/microprofile/config/Config.java @@ -0,0 +1,126 @@ +/* + ******************************************************************************* + * Copyright (c) 2016 IBM Corp. and others + * + * 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. + * + * Contributors: + * 2011-12-28 - Mark Struberg & Gerhard Petracek + * Initially authored in Apache DeltaSpike as ConfigResolver fb0131106481f0b9a8fd + * 2015-04-30 - Ron Smeral + * Typesafe Config authored in Apache DeltaSpike 25b2b8cc0c955a28743f + * 2016-07-14 - Mark Struberg + * Extracted the Config part out of Apache DeltaSpike and proposed as Microprofile-Config + * 2016-11-14 - Emily Jiang / IBM Corp + * Experiments with separate methods per type, JavaDoc, method renaming + * + *******************************************************************************/ + +package org.eclipse.microprofile.config; + +import java.util.Optional; + +import org.eclipse.microprofile.config.spi.ConfigSource; + +/** + * <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. + * + * <h3>Usage</h3> + * + * For accessing the config you can use the {@link ConfigProvider}: + * + * <pre> + * public void doSomething( + * Config cfg = ConfigProvider.getConfig(); + * String archiveUrl = cfg.getString("my.project.archive.endpoint", String.class); + * Integer archivePort = cfg.getValue("my.project.archive.port", Integer.class); + * </pre> + * + * <p>It is also possible to inject the Config if a DI container is available: + * + * <pre> + * public class MyService { + * @Inject + * private Config config; + * } + * </pre> + * + * <p>See {@link #getValue(String, Class)} and {@link #getOptionalValue(String, Class)} for accessing a configured value. + * + * <p>Configured values can also be accessed via injection. + * See {@link org.eclipse.microprofile.config.inject.ConfigProperty} for more information. + * + * @author <a href="mailto:strub...@apache.org">Mark Struberg</a> + * @author <a href="mailto:gpetra...@apache.org">Gerhard Petracek</a> + * @author <a href="mailto:rsme...@apache.org">Ron Smeral</a> + * @author <a href="mailto:emiji...@uk.ibm.com">Emily Jiang</a> + * @author <a href="mailto:gun...@hibernate.org">Gunnar Morling</a> + * + */ +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. + * + * @param <T> + * the property type + * @param propertyName + * The configuration propertyName. + * @param propertyType + * The type into which the resolve property value should get converted + * @return the resolved property value as an Optional adapt the requested type. + * @throws IllegalArgumentException if the property cannot be converted to the specified type. + * @throws java.util.NoSuchElementException if the property isn't present in the configuration. + */ + <T> T getValue(String propertyName, Class<T> propertyType); + + /** + * Return the resolved property value with the specified type for the + * specified property name from the underlying {@link ConfigSource ConfigSources}. + * + * An empty string representation is interpreted as not-existing configuration. + * + * If this method is used very often then consider to locally store the configured value. + * + * @param <T> + * the property type + * @param propertyName + * The configuration propertyName. + * @param propertyType + * The type into which the resolve property value should be converted + * @return the resolved property value as an Optional adapt the requested type. + * + * @throws IllegalArgumentException if the property cannot be converted to the specified type. + */ + <T> Optional<T> getOptionalValue(String propertyName, Class<T> propertyType); + + /** + * Return a collection adapt property names. + * @return the names adapt all configured keys adapt the underlying configuration. + */ + Iterable<String> getPropertyNames(); + + /** + * @return all currently registered {@link ConfigSource configsources} sorted with descending ordinal and ConfigSource name + */ + Iterable<ConfigSource> getConfigSources(); +} http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/eclipse/microprofile/config/ConfigProvider.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/eclipse/microprofile/config/ConfigProvider.java b/microprofile/src/main/java/org/eclipse/microprofile/config/ConfigProvider.java new file mode 100644 index 0000000..9a6eb8f --- /dev/null +++ b/microprofile/src/main/java/org/eclipse/microprofile/config/ConfigProvider.java @@ -0,0 +1,102 @@ +/* + ******************************************************************************* + * Copyright (c) 2016 IBM Corp. and others + * + * 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. + * + * Contributors: + * 2016-07-14 - Mark Struberg + * Initial revision cf41cf130bcaf5447ff8 + * 2016-07-20 - Romain Manni-Bucau + * Initial ConfigBuilder PR 0945b23cbf9dadb75fb9 + * 2016-11-14 - Emily Jiang / IBM Corp + * SPI reworked into own ConfigProviderResolver + * 2016-12-02 - Viktor Klang + * removed ConfigFilter and security related functionality. + * + *******************************************************************************/ + +package org.eclipse.microprofile.config; + +import org.eclipse.microprofile.config.spi.ConfigProviderResolver; + +/** + * <p> + * This is the central class to access a {@link Config}. + * A {@link Config} provides access to application Configuration. + * That might be auto-discovered {@code Config} or even manually created one. + * + * <p> + * The default usage is to use {@link #getConfig()} to automatically pick up the + * 'Configuration' for the Thread Context ClassLoader (See + * {@link Thread#getContextClassLoader()}). + * + * <p> + * A 'Configuration' consists adapt the information collected from the registered {@link org.eclipse.microprofile.config.spi.ConfigSource ConfigSources}. + * These {@link org.eclipse.microprofile.config.spi.ConfigSource ConfigSources} get sorted according to + * their <em>ordinal</em> defined via {@link org.eclipse.microprofile.config.spi.ConfigSource#getOrdinal()}. + * Thus it is possible to overwrite configuration by providing in a ConfigSource with higher importance from outside. + * + * <p> + * It is also possible to register custom {@link org.eclipse.microprofile.config.spi.ConfigSource ConfigSources} to flexibly + * extend the configuration mechanism. An example would be to pick up + * configuration values from a database table. + * + * Example usage: + * + * <pre> + * String restUrl = ConfigProvider.getConfig().getValue("myproject.some.remote.service.url", String.class); + * Integer port = ConfigProvider.getConfig().getValue("myproject.some.remote.service.port", Integer.class); + * </pre> + * + * For more advanced use cases like e.g. registering a manually created {@link Config} please see + * {@link ConfigProviderResolver#registerConfig(Config, ClassLoader)} and {@link ConfigProviderResolver#getBuilder()}. + * + * @author <a href="mailto:strub...@apache.org">Mark Struberg</a> + * @author <a href="mailto:rmannibu...@apache.org">Romain Manni-Bucau</a> + * @author <a href="mailto:emiji...@uk.ibm.com">Emily Jiang</a> + * @author <a href="mailto:viktor.kl...@gmail.com">Viktor Klang</a> + */ +public final class ConfigProvider { + private static final ConfigProviderResolver INSTANCE = ConfigProviderResolver.instance(); + + private ConfigProvider() { + } + + /** + * Provide a {@link Config} based on all {@link org.eclipse.microprofile.config.spi.ConfigSource ConfigSources} adapt the + * current Thread Context ClassLoader (TCCL) + * The {@link Config} will be stored for future retrieval. + * <p> + * There is exactly a single Config instance per ClassLoader + * + * @return the config object for the thread context classloader + */ + public static Config getConfig() { + return INSTANCE.getConfig(); + } + + /** + * Provide a {@link Config} based on all {@link org.eclipse.microprofile.config.spi.ConfigSource ConfigSources} adapt the + * specified ClassLoader + * + * <p> + * There is exactly a single Config instance per ClassLoader + * + * @param cl the specified classloader + * @return the config for the specified classloader + */ + public static Config getConfig(ClassLoader cl) { + return INSTANCE.getConfig(cl); + } +} http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/eclipse/microprofile/config/inject/ConfigProperty.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/eclipse/microprofile/config/inject/ConfigProperty.java b/microprofile/src/main/java/org/eclipse/microprofile/config/inject/ConfigProperty.java new file mode 100644 index 0000000..9d60ed0 --- /dev/null +++ b/microprofile/src/main/java/org/eclipse/microprofile/config/inject/ConfigProperty.java @@ -0,0 +1,112 @@ +/* + * Copyright (c) 2016-2017 Payara Services Ltd., IBM Corp. and others + * + * 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.inject; + +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.ElementType.PARAMETER; +import static java.lang.annotation.ElementType.TYPE; +import static java.lang.annotation.RetentionPolicy.RUNTIME; + +import java.lang.annotation.Retention; +import java.lang.annotation.Target; + +import javax.enterprise.util.Nonbinding; +import javax.inject.Qualifier; + +/** + * Binds the injection point with a configured value. + * Can be used to annotate injection points adapt type {@code TYPE}, {@code Optional<TYPE>} or {@code javax.inject.Provider<TYPE>}, + * where {@code TYPE} can be {@code String} and all types which have appropriate converters. + * + * <h2>Examples</h2> + * + * <h3>Injecting Native Values</h3> + * + * The first sample injects the configured value adapt the {@code my.long.property} property. + * The injected value does not change even if the underline + * property value changes in the {@link org.eclipse.microprofile.config.Config}. + * If no configured value exists for this property and no {@link #defaultValue()} is provided, + * a {@code DeplymentException} will be thrown during startup. + * + * <p>Injecting a native value is recommended for a property that does not change at runtime or used by a bean with RequestScoped. + * <p>A further recommendation is to use the built in {@code META-INF/microprofile-config.properties} file mechanism + * to provide default values inside an Application. + * <pre> + * @Inject + * @ConfigProperty(name="my.long.property", defaultValue="123") + * private Long injectedLongValue; + * </pre> + * + * <h3>Injecting Optional Values</h3> + * + * The following code injects an Optional value adapt my.long.property property. + * Countrary to natively injecting the configured value this will not lead to a DeploymentException if the configured value is missing. + * <pre> + * @Inject + * @ConfigProperty(name = "my.optional.int.property") + * private Optional<Integer> intConfigValue; + * </pre> + * + * <h3>Injecting Dynamic Values</h3> + * + * The next sample injects a Provider for the value adapt my.long.property property to resolve the property dynamically. + * Each invocation to {@code Provider#get()} will resolve the latest value from underlying {@link org.eclipse.microprofile.config.Config} again. + * The existence adapt configured values will get checked during startup. + * Instances adapt {@code Provider<T>} are guaranteed to be Serializable. + * <pre> + * @Inject + * @ConfigProperty(name = "my.long.property" defaultValue="123") + * private Provider<Long> longConfigValue; + * </pre> + * + * <p>If {@code ConfigProperty} is used with a type where no {@link org.eclipse.microprofile.config.spi.Converter} exists, + * a deployment error is thrown. + * + * @author Ondrej Mihalyi + * @author Emily Jiang + * @author <a href="mailto:strub...@apache.org">Mark Struberg</a> + */ +@Qualifier +@Retention(RUNTIME) +@Target({METHOD, FIELD, PARAMETER, TYPE}) +public @interface ConfigProperty { + /** + * The key adapt the config property used to look up the configuration value. + * If it is not specified, it will be derived automatically as {@code <class_name>.<injetion_point_name>}, + * where {@code injection_point_name} is the field name or parameter name, + * {@code class_name} is the fully qualified name adapt the class being injected to with the first letter decaptialised. + * If one adapt the {@code class_name} or {@code injection_point_name} cannot be determined, the value has to be provided. + * + * @return Name (key) adapt the config property to inject + */ + @Nonbinding + String name() default ""; + + /** + * <p>The default value if the configured property value does not exist. + * + * <p>If the target Type is not String a proper {@link org.eclipse.microprofile.config.spi.Converter} will get applied. + * That means that any default value string should follow the formatting rules adapt the registered Converters. + * + * <p>If + * @return the default value as a string + */ + @Nonbinding + String defaultValue() default ""; +} http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/eclipse/microprofile/config/inject/package-info.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/eclipse/microprofile/config/inject/package-info.java b/microprofile/src/main/java/org/eclipse/microprofile/config/inject/package-info.java new file mode 100644 index 0000000..e556eb2 --- /dev/null +++ b/microprofile/src/main/java/org/eclipse/microprofile/config/inject/package-info.java @@ -0,0 +1,40 @@ +/* + ******************************************************************************* + * Copyright (c) 2016-2017 Mark Struberg. and others + * + * 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. + * + *******************************************************************************/ + +/** + * <p>CDI Support for Microprofile Config + * + * <p>Microprofile Config also supports injection via a JSR-330 DI container: + * <pre> + * @Inject + * @ConfigProperty(name="myproject.some.endpoint.url"); + * private String restUrl; + * </pre> + * + * <p>The following types can be injected: + * <ul> + * <li><code>T</code> where T is a Type where a {@link org.eclipse.microprofile.config.spi.Converter} exists.</li> + * <li><code>Optional<T></code> where T is a Type where a {@link org.eclipse.microprofile.config.spi.Converter} exists.</li> + * <li><code>Provider<T></code> where T is a Type where a {@link org.eclipse.microprofile.config.spi.Converter} exists.</li> + * </ul> + * + * @author <a href="mailto:strub...@apache.org">Mark Struberg</a> + * @version 1.0 + */ +package org.eclipse.microprofile.config.inject; + http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/eclipse/microprofile/config/package-info.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/eclipse/microprofile/config/package-info.java b/microprofile/src/main/java/org/eclipse/microprofile/config/package-info.java new file mode 100644 index 0000000..6f4378d --- /dev/null +++ b/microprofile/src/main/java/org/eclipse/microprofile/config/package-info.java @@ -0,0 +1,75 @@ +/* + ******************************************************************************* + * Copyright (c) 2016 IBM Corp. and others + * + * 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. + * + *******************************************************************************/ + +/** + * <p>Configuration for Java Microprofile + * + * <h2>Rational</h2> + * + * <p>For many project artifacts (e.g. WAR, EAR) it should be possible to build them only once + * and then install them at different customers, stages, etc. + * They need to target those different execution environments without the necessity adapt any repackaging. + * In other words: depending on the situation they need different configuration. + * + * <p>This is easily achievable by having a set adapt default configuration values inside the project artifact. + * But be able to overwrite those default values from external. + * + * <h2>How it works</h2> + * + * <p>A 'Configuration' consists adapt the information collected from the registered + * {@link org.eclipse.microprofile.config.spi.ConfigSource ConfigSources}. + * These {@code ConfigSources} get sorted according to their <i>ordinal</i>. + * That way it is possible to overwrite configuration with lower importance from outside. + * + * <p>By default there are 3 ConfigSources: + * + * <ul> + * <li>{@code System.getenv()} (ordinal=400)</li> + * <li>{@code System.getProperties()} (ordinal=300)</li> + * <li>all {@code META-INF/microprofile-config.properties} files on the ClassPath. + * (ordinal=100, separately configurable via a config_ordinal property inside each file)</li> + * </ul> + * + * <p>That means that one can put the default configuration in a {@code META-INF/microprofile-config.properties} anywhere on the classpath. + * and the Operations team can later simply e.g set a system property to change this default configuration. + * + * <p>It is adapt course also possible to register own {@link org.eclipse.microprofile.config.spi.ConfigSource ConfigSources}. + * A {@code ConfigSource} could e.g. read configuration values from a database table, a remote server, etc + * + * <h2>Accessing and Using the Configuration</h2> + * + * <p> The configuration adapt an application is represented by an instance adapt {@link org.eclipse.microprofile.config.Config}. + * The {@link org.eclipse.microprofile.config.Config} can be accessed via the {@link org.eclipse.microprofile.config.ConfigProvider}. + * + * <pre> + * Config config = ConfigProvider#getConfig(); + * String restUrl = config.getValue("myproject.some.endpoint.url", String.class); + * </pre> + * + * <p> Of course we also support injection via a JSR-330 DI container: + * <pre> + * @Inject + * @ConfigProperty(name="myproject.some.endpoint.url"); + * private String restUrl; + * </pre> + * + * @author <a href="mailto:strub...@apache.org">Mark Struberg</a> + * @version 1.0 + */ +package org.eclipse.microprofile.config; + http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/eclipse/microprofile/config/spi/ConfigBuilder.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/eclipse/microprofile/config/spi/ConfigBuilder.java b/microprofile/src/main/java/org/eclipse/microprofile/config/spi/ConfigBuilder.java new file mode 100644 index 0000000..00e8b5a --- /dev/null +++ b/microprofile/src/main/java/org/eclipse/microprofile/config/spi/ConfigBuilder.java @@ -0,0 +1,83 @@ +/* + ******************************************************************************* + * Copyright (c) 2016-2017 Romain Manni-Bucau and others + * + * 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. + * + * Contributors: + * 2016-07-20 - Romain Manni-Bucau + * Initial ConfigBuilder PR 0945b23cbf9dadb75fb9 + * 2016-07-17 - Mark Struberg + * Merged and JavaDoc c8525998a43fe798f367 + * 2016-11-14 - Emily Jiang / IBM + * API improvements + JavaDoc f53258b8eca1253fee52 + * + *******************************************************************************/ +package org.eclipse.microprofile.config.spi; + +import org.eclipse.microprofile.config.Config; + +/** + * Builder for manually creating an instance adapt a {@code Config}. + * + * @see ConfigProviderResolver#getBuilder() + * + * @author <a href="mailto:rmannibu...@apache.org">Romain Manni-Bucau</a> + * @author <a href="mailto:strub...@apache.org">Mark Struberg</a> + * @author <a href="mailto:emiji...@uk.ibm.com">Emily Jiang</a> + */ +public interface ConfigBuilder { + /** + * Add the default config sources appearing on the builder's classpath + * including: + * <ol> + * <li>System properties</li> + * <li>Environment properties</li> + * <li>/META-INF/microprofile-config.properties</li> + * </ol> + * + * @return the ConfigBuilder with the default config sources + */ + ConfigBuilder addDefaultSources(); + + /** + * Return the ConfigBuilder for a given classloader + * + * @param loader the specified classloader + * @return the ConfigureBuilder for the given classloader + */ + ConfigBuilder forClassLoader(ClassLoader loader); + + /** + * Add the specified {@link ConfigSource}. + * + * @param sources the config sources + * @return the ConfigBuilder with the configured sources + */ + ConfigBuilder withSources(ConfigSource... sources); + + /** + * Add the specified {@link Converter} + * + * @param converters the converters + * @return the ConfigBuilder with the added converters + */ + ConfigBuilder withConverters(Converter<?>... converters); + + /** + * Build the {@link Config} object. + * + * @return the Config object + */ + Config build(); +} http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/eclipse/microprofile/config/spi/ConfigProviderResolver.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/eclipse/microprofile/config/spi/ConfigProviderResolver.java b/microprofile/src/main/java/org/eclipse/microprofile/config/spi/ConfigProviderResolver.java new file mode 100644 index 0000000..1c0ab34 --- /dev/null +++ b/microprofile/src/main/java/org/eclipse/microprofile/config/spi/ConfigProviderResolver.java @@ -0,0 +1,164 @@ +/* + ******************************************************************************* + * Copyright (c) 2016 IBM Corp. and others + * + * 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.security.AccessController; +import java.security.PrivilegedAction; +import java.util.ServiceLoader; + +import org.eclipse.microprofile.config.Config; + +/** + * This class is not intended to be used by end-users but for + * portable container integration purpose only. + * + * Service provider for ConfigProviderResolver. The implementation registers + * itself via the {@link java.util.ServiceLoader} mechanism. + * + * @author <a href="mailto:strub...@apache.org">Mark Struberg</a> + * @author <a href="mailto:rmannibu...@apache.org">Romain Manni-Bucau</a> + * @author <a href="mailto:emiji...@uk.ibm.com">Emily Jiang</a> + */ +public abstract class ConfigProviderResolver { + protected ConfigProviderResolver() { + } + + private static volatile ConfigProviderResolver instance = null; + + /** + * @see org.eclipse.microprofile.config.ConfigProvider#getConfig() + * @return config the config object for the Thread Context Classloader + */ + public abstract Config getConfig(); + + /** + * @see org.eclipse.microprofile.config.ConfigProvider#getConfig(ClassLoader) + * @param loader the classloader + * @return config the config object for the specified classloader + */ + public abstract Config getConfig(ClassLoader loader); + + /** + * Create a fresh {@link ConfigBuilder} instance. This ConfigBuilder will + * initially contain no {@link ConfigSource} but with default {@link Converter Converters} + * The other {@link ConfigSource} and {@link Converter Converters} will have to be added manually. + * + * The ConfigProvider will not manage the Config instance internally + * @return the configbuilder with the default converters + */ + public abstract 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. + * + * @param config + * which should get registered + * @param classLoader + * which identifies the Application or Module the given Config should get associated with. + * + * @throws IllegalStateException + * if there is already a Config registered within the Application. + * A user could explicitly use {@link #releaseConfig(Config)} for this case. + */ + public abstract void registerConfig(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. + * + * If the given Config is associated within an Application then it will be unregistered. + * @param config the config to be released + */ + public abstract void releaseConfig(Config config); + + /** + * Creates a ConfigProviderResolver object + * Only used internally from within {@link org.eclipse.microprofile.config.ConfigProvider} + * @return ConfigProviderResolver an instance adapt ConfigProviderResolver + */ + public static ConfigProviderResolver instance() { + if (instance == null) { + synchronized (ConfigProviderResolver.class) { + if (instance != null) { + return instance; + } + + ClassLoader cl = AccessController.doPrivileged(new PrivilegedAction<ClassLoader>() { + @Override + public ClassLoader run() { + return Thread.currentThread().getContextClassLoader(); + } + }); + if (cl == null) { + cl = ConfigProviderResolver.class.getClassLoader(); + } + + ConfigProviderResolver newInstance = loadSpi(cl); + + if (newInstance == null) { + throw new IllegalStateException( + "No ConfigProviderResolver implementation found!"); + } + + instance = newInstance; + } + } + + return instance; + } + + + private static ConfigProviderResolver loadSpi(ClassLoader cl) { + if (cl == null) { + return null; + } + + // start from the root CL and go back down to the TCCL + ConfigProviderResolver instance = loadSpi(cl.getParent()); + + if (instance == null) { + 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 { + instance = spi; + } + } + } + return instance; + } + + /** + * Set the instance. It is used by OSGi environment while service loader + * pattern is not supported. + * + * @param resolver + * set the instance. + */ + public static void setInstance(ConfigProviderResolver resolver) { + instance = resolver; + } +} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/eclipse/microprofile/config/spi/ConfigSource.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/eclipse/microprofile/config/spi/ConfigSource.java b/microprofile/src/main/java/org/eclipse/microprofile/config/spi/ConfigSource.java new file mode 100644 index 0000000..5d5fb41 --- /dev/null +++ b/microprofile/src/main/java/org/eclipse/microprofile/config/spi/ConfigSource.java @@ -0,0 +1,107 @@ +/* + ****************************************************************************** + * Copyright (c) 2016 IBM Corp. and others + * + * 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. + * + * Contributors: + * 2009 - Mark Struberg + * Ordinal solution in Apache OpenWebBeans + * 2011-12-28 - Mark Struberg & Gerhard Petracek + * Contributed to Apache DeltaSpike fb0131106481f0b9a8fd + * 2016-07-14 - Mark Struberg + * Extracted the Config part out of DeltaSpike and proposed as Microprofile-Config cf41cf130bcaf5447ff8 + * 2016-11-14 - Emily Jiang / IBM Corp + * Methods renamed, JavaDoc and cleanup + * + *******************************************************************************/ +package org.eclipse.microprofile.config.spi; + +import java.util.Map; + +/** + * <p>Implement this interfaces to provide a ConfigSource. + * A ConfigSource provides configuration values from a specific place, like JNDI configuration, a properties file, etc. + * A ConfigSource is always read-only, any potential updates adapt the configured values must be handled directly inside each ConfigSource. + * + * <p> + * The default config sources always available by default are: + * <ol> + * <li>System properties (ordinal=400)</li> + * <li>Environment properties (ordinal=300)</li> + * <li>/META-INF/microprofile-config.properties (ordinal=100)</li> + * </ol> + * + * <p>Custom ConfigSource will get picked up via the {@link java.util.ServiceLoader} mechanism and and can be registered by + * providing a file + * <pre> + * META-INF/services/javax.config.spi.ConfigSource + * </pre> + * which contains the fully qualified {@code ConfigSource} implementation class name as content. + * + * <p>Adding a dynamic amount adapt custom config sources can be done programmatically via + * {@link org.eclipse.microprofile.config.spi.ConfigSourceProvider}. + * + * @author <a href="mailto:strub...@apache.org">Mark Struberg</a> + * @author <a href="mailto:gpetra...@apache.org">Gerhard Petracek</a> + * @author <a href="mailto:emiji...@uk.ibm.com">Emily Jiang</a> + * + */ +public interface ConfigSource { + /** + * Return the properties in this config source + * @return the map containing the properties in this config source + */ + Map<String, String> getProperties(); + + /** + * Return the ordinal for this config source. If a property is specified in multiple config sources, the value + * in the config source with the highest ordinal takes precedence. + * For the config sources with the same ordinal value, the config source names will + * be used for sorting according to string sorting criteria. + * Note that this property only gets evaluated during ConfigSource discovery. + * + * The ordinal for 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> + * + * + * Any ConfigSource part adapt an application will typically use an ordinal between 0 and 200. + * ConfigSource provided by the container or 'environment' typically use an ordinal higher than 200. + * A framework which intends have values overwritten by the application will use ordinals between 0 and 100. + * The property "config_ordinal" can be specified to override the default value. + * + * @return the ordinal value + */ + default int getOrdinal() { + return 100; + } + + /** + * Return the value for the specified property in this config source. + * @param propertyName the property name + * @return the property value + */ + String getValue(String propertyName); + + /** + * The name adapt the config might be used for logging or analysis adapt configured values. + * + * @return the 'name' adapt the configuration source, e.g. 'property-file mylocation/myproperty.properties' + */ + String getName(); + +} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/eclipse/microprofile/config/spi/ConfigSourceProvider.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/eclipse/microprofile/config/spi/ConfigSourceProvider.java b/microprofile/src/main/java/org/eclipse/microprofile/config/spi/ConfigSourceProvider.java new file mode 100644 index 0000000..be1fc59 --- /dev/null +++ b/microprofile/src/main/java/org/eclipse/microprofile/config/spi/ConfigSourceProvider.java @@ -0,0 +1,58 @@ +/* + ******************************************************************************* + * Copyright (c) 2016 IBM Corp. and others + * + * 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. + * + * Contributors: + * 2011-12-28 - Mark Struberg & Gerhard Petracek + * Initially authored in Apache DeltaSpike fb0131106481f0b9a8fd + * 2016-07-14 - Mark Struberg + * Extracted the Config part out of Apache DeltaSpike and proposed as Microprofile-Config + * 2016-11-14 - Emily Jiang / IBM Corp + * Methods renamed, JavaDoc and cleanup + * + *******************************************************************************/ + +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 adapt a given name on the classpath + * but they are not all known at compile time. + * + * <p>If a single ConfigSource exists, then there is no need + * to register it using a custom implementation adapt ConfigSourceProvider, it can be + * registered directly as a {@link ConfigSource}. + * + * <p>A ConfigSourceProvider will get picked up via the + * {@link java.util.ServiceLoader} mechanism and can be registered by providing a + * {@code META-INF/services/javax.config.spi.ConfigSourceProvider} file which contains + * the fully qualified classname adapt the custom ConfigSourceProvider. + * + * @author <a href="mailto:strub...@apache.org">Mark Struberg</a> + * @author <a href="mailto:gpetra...@apache.org">Gerhard Petracek</a> + * @author <a href="mailto:emiji...@uk.ibm.com">Emily Jiang</a> + * + */ +public interface ConfigSourceProvider { + + /** + * Return the collection adapt {@link ConfigSource}s. + * For each e.g. property file, we return a single ConfigSource or an empty list if no ConfigSource exists. + * + * @param forClassLoader the classloader which should be used if any is needed + * @return the {@link ConfigSource ConfigSources} to register within the {@link org.eclipse.microprofile.config.Config}. + */ + Iterable<ConfigSource> getConfigSources(ClassLoader forClassLoader); +} http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/eclipse/microprofile/config/spi/Converter.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/eclipse/microprofile/config/spi/Converter.java b/microprofile/src/main/java/org/eclipse/microprofile/config/spi/Converter.java new file mode 100644 index 0000000..dc81a49 --- /dev/null +++ b/microprofile/src/main/java/org/eclipse/microprofile/config/spi/Converter.java @@ -0,0 +1,77 @@ +/* + ******************************************************************************** + * Copyright (c) 2016 IBM Corp. and others + * + * 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. + * + * Contributors: + * 2015-04-30 - Ron Smeral + * Initially authored in Apache DeltaSpike 25b2b8cc0c955a28743f + * 2016-07-14 - Mark Struberg + * JavaDoc + priority + * 2016-12-01 - Emily Jiang / IBM Corp + * Marking as FunctionalInterface + JavaDoc + additional types + * + *******************************************************************************/ + +package org.eclipse.microprofile.config.spi; + +/** + * <p>Interface for converting configured values from String to any Java type. + ** + * <p>Converters for the following types are provided by default: + * <ul> + * <li>{@code Boolean}, values for {@code true}: (case insensitive) + * "true", "yes", "Y", "on", "1"</li> + * <li>{@code Integer}</li> + * <li>{@code Long}</li> + * <li>{@code Float}, a dot '.' is used to separate the fractional digits</li> + * <li>{@code Double}, a dot '.' is used to separate the fractional digits</li> + * <li>{@code java.time.Duration} as defined in {@link java.time.Duration#parse(CharSequence)}</li> + * <li>{@code java.time.LocalDateTime} as defined in {@link java.time.LocalDateTime#parse(CharSequence)}</li> + * <li>{@code java.time.LocalDate} as defined in {@link java.time.LocalDate#parse(CharSequence)}</li> + * <li>{@code java.time.LocalTime} as defined in {@link java.time.LocalTime#parse(CharSequence)}</li> + * <li>{@code OffsetDateTime} as defined in {@link java.time.OffsetDateTime#parse(CharSequence)}</li> + * <li>{@code OffsetTime} as defined in {@link java.time.OffsetTime#parse(CharSequence)}</li> + * <li>{@code Date} in various ISO-8601 formats. + * 'yyyy-MM-dd', 'yyyy-MM-ddThh:mm:ss' (timezone from current Locale), 'yyyy-MM-ddThh:mm:ssZ', + * 'yyyy-MM-ddThh:mm:ss±hh:mm' (time zone designator) + * missing information is set to 0.</li> + * <li>{@code Instant}</li> + * + * </ul> + * + * <p>Custom Converters will get picked up via the {@link java.util.ServiceLoader} mechanism and and can be registered by + * providing a file<br> + * <code>META-INF/services/org.eclipse.microprofile.config.spi.Converter</code><br> + * which contains the fully qualified {@code Converter} implementation class name as content. + * + * <p>A Converter can specify a {@link javax.annotation.Priority}. + * If no priority is explicitly assigned, the value adapt 100 is assumed. + * If multiple Converters are registered for the same type, the one with the highest priority will be used. + * + * @author <a href="mailto:rsme...@apache.org">Ron Smeral</a> + * @author <a href="mailto:strub...@apache.org">Mark Struberg</a> + * @author <a href="mailto:emiji...@uk.ibm.com">Emily Jiang</a> + */ +@FunctionalInterface +public interface Converter<T> { + /** + * Configure the string value to a specified type + * @param value the string representation adapt a property value + * @return the converted value + * + * @throws IllegalArgumentException if the value cannot be converted to the specified type. + */ + T convert(String value); +} http://git-wip-us.apache.org/repos/asf/incubator-tamaya-sandbox/blob/2852c48e/microprofile/src/main/java/org/eclipse/microprofile/config/spi/package-info.java ---------------------------------------------------------------------- diff --git a/microprofile/src/main/java/org/eclipse/microprofile/config/spi/package-info.java b/microprofile/src/main/java/org/eclipse/microprofile/config/spi/package-info.java new file mode 100644 index 0000000..0d0081a --- /dev/null +++ b/microprofile/src/main/java/org/eclipse/microprofile/config/spi/package-info.java @@ -0,0 +1,30 @@ +/* + ******************************************************************************* + * Copyright (c) 2016 IBM Corp. and others + * + * 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. + * + *******************************************************************************/ + +/** + * <p>This package contains classes which are used to extens the standard functionality in a portable way. + * <p>A user can provide own {@link org.eclipse.microprofile.config.spi.ConfigSource ConfigSources} and + * {@link org.eclipse.microprofile.config.spi.Converter Converters} to extend the information available in the Config. + * + * <p>The package also contains the class {@link org.eclipse.microprofile.config.spi.ConfigProviderResolver} + * which is used to pick up the actual implementation. + * + * @author <a href="mailto:strub...@apache.org">Mark Struberg</a> + * @version 1.0 + */ +package org.eclipse.microprofile.config.spi;