TAMAYA-274 Updated documentation. TAMAYA-355 Updated documentation. TAMAYA-353 Updated documentation.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/commit/1c033714 Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/1c033714 Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/1c033714 Branch: refs/heads/master Commit: 1c033714eb241b602ea7b46bd46c5e6d5aa65381 Parents: 15c355a 43f983e Author: Anatole Tresch <[email protected]> Authored: Mon Nov 5 00:14:41 2018 +0100 Committer: Anatole Tresch <[email protected]> Committed: Mon Nov 5 00:14:41 2018 +0100 ---------------------------------------------------------------------- content/documentation-new/api.adoc | 778 ------------------ content/documentation-new/core.adoc | 283 ------- content/documentation-new/extensions.adoc | 65 -- .../documentation-new/extensions/mod_camel.adoc | 132 --- .../documentation-new/extensions/mod_cdi.adoc | 244 ------ .../extensions/mod_classloader_support.adoc | 79 -- .../extensions/mod_collections.adoc | 245 ------ .../extensions/mod_consul.adoc | 66 -- .../documentation-new/extensions/mod_etcd.adoc | 192 ----- .../extensions/mod_events.adoc | 308 ------- .../extensions/mod_features.adoc | 87 -- .../extensions/mod_filter.adoc | 117 --- .../extensions/mod_formats.adoc | 290 ------- .../extensions/mod_functions.adoc | 136 ---- .../extensions/mod_hazelcast.adoc | 118 --- .../extensions/mod_injection.adoc | 481 ----------- .../documentation-new/extensions/mod_jndi.adoc | 68 -- .../extensions/mod_jodatime.adoc | 80 -- .../documentation-new/extensions/mod_json.adoc | 80 -- .../extensions/mod_management.adoc | 97 --- .../extensions/mod_metamodel.adoc | 632 -------------- .../extensions/mod_mutable_config.adoc | 236 ------ .../extensions/mod_optional.adoc | 61 -- .../documentation-new/extensions/mod_osgi.adoc | 814 ------------------- .../extensions/mod_remote.adoc | 111 --- .../extensions/mod_resolver.adoc | 131 --- .../extensions/mod_resources.adoc | 167 ---- .../extensions/mod_server.adoc | 239 ------ .../extensions/mod_spring.adoc | 177 ---- .../extensions/mod_usagetracker.adoc | 161 ---- .../extensions/mod_validation.adoc | 104 --- .../documentation-new/extensions/mod_vertx.adoc | 185 ----- .../documentation-new/extensions/mod_yaml.adoc | 118 --- content/documentation-new/quickstart.adoc | 224 ----- content/documentation-new/spisupport.adoc | 63 -- content/documentation-new/usecases.adoc | 472 ----------- templates/footer.thyme | 7 +- 37 files changed, 5 insertions(+), 7843 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/api.adoc ---------------------------------------------------------------------- diff --cc content/documentation-new/api.adoc index 581c368,581c368..0000000 deleted file mode 100644,100644 --- a/content/documentation-new/api.adoc +++ /dev/null @@@ -1,778 -1,778 +1,0 @@@ --:jbake-type: page --:jbake-status: published -- --[[CoreDesign]] --== Apache Tamaya: Configuration API -- --Tamaya implements the Java JSR 382 Configuration API. You will find the spec link:http://jcp.org/jsr/?id=382[here]. --Also worth reading might be Tamaya's link:../highleveldesign.html[High Level Design Documentation]. -- --[[API]] --== The Configuration API --The Configuration API provides the main artifacts to access and change configuration, which are: -- --* The package +javax.config+ defines a simple but complete SE *API* for accessing key/value based _Config_: -- ** +Config+ hereby models _configuration_, the main interface. +Config+ provides -- *** access to literal key/value pairs. -- ** +ConfigProvider+ provides with +getConfig()+ the static entry point for accessing configuration. -- A default +Config+ instance is automatically created on first access collecting and adding all discoverable artifacts. -- --* The package +javax.config.spi+ provides interfaces used for extending and/or -- adapting functionality, as well as artifacts for creating -- +Config+ instances programmatically: -- ** _ConfigSource:_ is the interface to be implemented for adding configuration entries. A +ConfigSource+ hereby -- *** is minimalistic and can be implemented in any way. E.g. there is no distinction that -- the configuration data provided is managed locally, remotely. There is even no -- requirement that the configuration data is always fully available. Summarizing a -- +ConfigSource+ -- *** provides property access for single key/value pairs in _raw_ format (meaning no postprocessing -- is applied yet). -- *** can _optionally_ provide access to a +Map<String,String>+, providing all its properties at once. -- *** defines the default ordinal to be used for establishing the order of significance among all -- auto-discovered property sources. -- ** _ConfigSourceProvider:_ allows to automatically register multiple property sources, e.g. all config files found in -- a file system folder. -- ** +ConfigProviderResolver+ defines the abstract entry point to be extended for providing configuration. It is the -- main implementation hook for an API implementation provider. -- ** A +Config+ can also be created by using a +ConfigBuilder+, which can be obtained from the +ConfigProviderResolver+. -- It allows to build up a +Config+ by adding config sources and converters in various ways. -- -- == Tamaya Configuration API Extensions -- -- Tamaya provides a few mechanisms that extend the standard API, which have shown to be very useful: -- --* +Filter+ allows filtering of property values prior before getting returned to the caller. Filters by default are -- registered as global filters, filtering _raw_ values. The final +String+ value of a configuration entry is the -- final value after all registered filters have been applied. --* A +ConfigValueCombinationPolicy+ optionally can be registered to change the logic how key/value -- pairs from subsequent property sources in the property source chain are combined to calculate the final -- _raw_ value passed over to the filters registered. --* Tamaya provides a much more powerful +TamayaConfigBuilder+, extending the default +ConfigBuilder+ -- adding additional methods for managing the config source order, adding filters and multiple converters. --* Finally Tamaya uses a flexible +ServiceContext+ and +ServiceContextManager+ to provide an abstraction to -- the underlying runtime environment, allowing different component loading and lifecycle strategies to be used. -- This is very useful since component (service) loading in Java SE, Java EE, OSGI and other runtime environments -- may differ significantly. In most cases even extension programmers will not have to deal with these two -- artifacts. -- --To integrate Tamaya modules with config implementations, the only things the implementations should do, is to --implement the +ConfigContextSupplier+ with an implementation of +Config+. Hereby a +ConfigContext+ is the abstraction --of the inner components (+ConfigSource, Filter, ConfigValueCombinationPolicy, Converter+) required to implement a --+Config+. Also the ordering of the config sources, filters and converters is defined by the context. -- --Summarizing a +ConfigurationContext+ contains the ordered property sources, property filters, converters and combination --policy used. -- -- --[[APIKeyValues]] --=== Excourse: Key/Value Pairs -- --Basically configuration is a very generic concept. Therefore it should be modelled in a generic way. The most simple --and most commonly used approach is simple literal key/value pairs. So the core building block of {name} are key/value pairs. --You can think of a common +.properties+ file, e.g. -- --[source,properties] --.A simple properties file ---------------------------------------------- --a.b.c=cVal --a.b.c.1=cVal1 --a.b.c.2=cVal2 --a=aVal --a.b=abVal --a.b2=abVal ---------------------------------------------- -- --Now you can use +java.util.Properties+ to read this file and access the corresponding properties, e.g. -- --[source,properties] ---------------------------------------------- --Properties props = new Properties(); --props.readProperties(...); --String val = props.getProperty("a.b.c"); --val = props.getProperty("a.b.c.1"); --... ---------------------------------------------- -- -- --==== Why Using Strings Only -- --There are good reason for keeping non-String-values as core storage representation of configuration. Mostly --there are several huge advantages: -- --* Strings are simple to understand --* Strings are human readable and therefore easy to prove for correctness --* Strings can easily be used within different languages, different VMs, files or network communications. --* Strings can easily be compared and manipulated --* Strings can easily be searched, indexed and cached --* It is very easy to provide Strings as configuration, which gives much flexibility for providing configuration in -- production as well in testing. -- --On the other hand there are also disadvantages: -- --* Strings are inherently not type safe, they do not provide validation out of the box for special types, such as --numbers, dates etc. --* In many cases you want to access configuration in a typesafe way avoiding conversion to the target types explicitly -- throughout your code. --* Strings are neither hierarchical nor multi-valued, so mapping hierarchical and collection structures requires some -- extra efforts. -- --Nevertheless most of these disadvantages can be mitigated easily, hereby still keeping all the benefits from above: -- --* Adding type safe adapters on top of String allows to add any type easily, that can be directly mapped from String. -- This includes all common base types such as numbers, dates, time, but also timezones, formatting patterns and more. --* Also multi-valued, complex and collection types can be defined. A corresponding +PropertyAdapter+ knows how to -- parse and create the target instance required. --* Strings ca also be used as references pointing to other locations and formats, where configuration is -- accessible. -- -- --[[API Configuration]] -- --=== Config -- --+Config+ is the main artifact modelling configuration. It allows reading single property values or all known --properties, but also supports type safe access: -- --[source,java] --.Interface Configuration ---------------------------------------------- --public interface Config{ -- <T> T getValue(String key, Class<T> type); -- <T> Optional<T> getOptionalValue(String key, Class<T> type); -- Iterable<String> getPropertyNames(); -- -- Iterable<ConfigSource> getConfigSources(); --} ---------------------------------------------- -- --Hereby -- --* +<T> T getValue(String, Class<T>)+ provides type safe accessors for all basic wrapper types of the JDK. If a -- key cannot be found a +NoSuchElementException+ is thrown. --* +getOptionalValue+ allows to use +Optional+ for handling default values as needed. --* +getPropertyNames()+ provides access to all keys, whereas entries from non-scannable config sources may not -- be included. --* +getConfigSources()+ allows access to the underlying config sources. -- -- --Instances of +Config+ can be accessed from the +ConfigProvider+ singleton: -- --[source,java] --.Accessing Configuration ---------------------------------------------- --Config config = ConfigProvider.getConfig(); ---------------------------------------------- -- --Hereby the singleton is backed up by an instance of +ConfigProviderResolver+ registered using Java's +ServiceLoader+ --mechanism. -- -- --[[Converter]] --==== Property Type Conversion -- --As illustrated in the previous section, +Config+ also allows access of typed values. Internally --all properties are strictly modelled as Strings. As a consequence non String values must be derived by converting the --String values into the required target type. This is achieved with the help of +Converter+: -- --[source,java] ---------------------------------------------- --@FunctionalInterface --public interface Converter<T>{ -- T convert(String value); --} ---------------------------------------------- -- --Tamaya additionally offers a +ConversionContext+, which contains additional meta-information about the key --accessed, including the key'a name and additional metadata. This can be very useful, e.g. when the implementation --of a +Converter+ requires additional metadata for determining the correct conversion to be applied: -- --[source,java] ---------------------------------------------- --ConversionContext context = ConversionContext.getContext(); ---------------------------------------------- -- --+Converter+ instances can be implemented and registered by default using the Java +ServiceLoader+. The ordering --of the registered converters, by default, is based on the annotated +@Priority+ values (priority +0+ is assumed if the --annotation is missing). The first non-null result of a converter is returned as the final configuration value. -- --Access to converters is provided by Tamaya's +ConfigContext+. The Config JSR does not provide a methgod to --access the currently registered converters. -- --NOTE: Tamaya, different to the JSR allows to register multiple converters for a type. Tamaya will walk through -- all converters for a type, using the first value evaluated to non-null as the result of a conversion -- process. -- -- --[[ExtensionPoints]] --=== Extension Points -- --We are well aware of the fact that this library will not be able to cover all kinds of use cases. Therefore --we have added _functional_ extension mechanisms to +Configuration+ that were used in other areas of the --Java eco-system (e.g. Java Time API and JSR 354) as well. -- --Tamaya -- --* +with(ConfigOperator operator)+ allows to pass arbitrary unary functions that take and return instances of -- +Configuration+. Operators can be used to cover use cases such as filtering, configuration views, security -- interception and more. --* +query(ConfigQuery query)+ allows to apply a function returning any kind of result based on a -- +Configuration+ instance. Queries are used for accessing/deriving any kind of data based on of a +Configuration+ -- instance, e.g. accessing a +Set<String>+ of root keys present. -- --Both interfaces hereby are functional interfaces. Because of backward compatibility with Java 7 we did not use --+UnaryOperator+ and +Function+ from the +java.util.function+ package. Nevertheless usage is similar, so you can --use Lambdas and method references in Java 8: -- --[source,java] --.Applying a +ConfigQuery+ using a method reference ---------------------------------------------- --SecurityContext context = ConfigQuery.from(ConfigProvider.getConfig()).query(ConfigSecurity::targetSecurityContext); ---------------------------------------------- -- --NOTE: +ConfigSecurity+ is an arbitrary class only for demonstration purposes. -- -- --Operator calls basically look similar: -- --[source,java] --.Applying a +ConfigOperator+ using a lambda expression: ---------------------------------------------- --Configuration secured = ConfigOperator.from(config) -- .with((config) -> -- config.get("foo")!=null?; -- FooFilter.apply(config): -- config); ---------------------------------------------- -- -- -- --[[SPI]] --== SPI -- --[[PropertyValue]] --=== PropertyValue, PropertyValueBuilder -- --On the API properties are represented as Strings only, whereas in the SPI value are represented as +ProeprtyValue+, --which contain -- --* the property's _key_ (String) --* the property's _value_ (String) --* the property's _source_ (String, typically equals to the property source's name) --* any additional meta-data represented as _Map<String,String>_ -- --This helps to kepp all value relevant data together in one place and also allows to choose any kind of --representation for meta-data entries. The +PropertyValue+ itself is a final and _serializable_ data container, --which also has a powerful builder API (e.g. for using within filters): -- --[source,java] ------------------------------------------------------------------ --public final class PropertyValue implements Serializable{ -- [...] -- -- public static PropertyValue of(String key, String value, String source); -- -- public String getKey(); -- public String getSource(); -- public String getValue(); -- public Map<String, String> getMetaEntries(); -- public String getMetaEntry(String key); -- public PropertyValueBuilder toBuilder(); -- -- public static PropertyValueBuilder builder(String key, String source); -- public static PropertyValueBuilder builder(String key, String value, String source); -- -- /** -- * Maps a map of {@code Map<String,String>} to a {@code Map<String,PropertyValue>}. -- * @param config the String based map, not null. -- * @param source the source name, not null. -- * @return the corresponding value based map. -- */ -- public static Map<String,PropertyValue> map(Map<String, String> config, String source); -- -- /** -- * Maps a map of {@code Map<String,String>} to a {@code Map<String,PropertyValue>}. -- * @param config the String based map, not null. -- * @param source the source name, not null. -- * @param metaData additional metadata, not null. -- * @return the corresponding value based map. -- */ -- public static Map<String,PropertyValue> map(Map<String, String> config, String source, -- Map<String,String> metaData); --} ------------------------------------------------------------------ -- --When writing your own datasource you can easily create your own +PropertyValues+: -- --[source,java] ------------------------------------------------------------------ --PropertyValue val = PropertyValue.of("key","value","source"); ------------------------------------------------------------------ -- --If you want to add additional metadata in most cases you would use the builder API: -- --[source,java] ------------------------------------------------------------------ --PropertyValue val = PropertyValue.builder("key","value","source") -- .addMetaEntry("figured", "true") -- .build(); ------------------------------------------------------------------ -- --+PropertyValues+ are type safe value objects. To change a value you have to create a --new instance using a builder: -- --[source,java] ------------------------------------------------------------------ --PropertyValue val = PropertyValue.builder("key","value","source") -- .addMetaEntry("figured", "true") -- .build(); --PropertyValue newVal = val.toBuilder().setValue("anotehrValue") -- .addMetaEntry("remote", "true") -- .removeMetaEntry("figured") -- .build(); ------------------------------------------------------------------ -- --[[ConfigSource]] --=== Interface ConfigSource -- --We have seen that constraining configuration aspects to simple literal key/value pairs provides us with an easy to --understand, generic, flexible, yet extensible mechanism. Looking at the Java language features a +java.util.Map<String, --String>+ and +java.util.Properties+ basically model these aspects out of the box. -- --Though there are advantages in using these types as a model, there are some drawbacks. Notably implementation --of these types is far not trivial and the collection API offers additional functionality not useful when aiming --for modelling simple property sources. -- --To render an implementation of a custom +PropertySource+ as convenient as possible only the following methods were --identified to be necessary: -- --[source,java] ---------------------------------------------- --public interface ConfigSource{ -- int getOrdinal(); -- String getName(); -- String getValue(String key); -- Map<String,String> getProperties(); --} ---------------------------------------------- -- --Hereby -- --* +getValue+ looks similar to the methods on +Map+. It may return +null+ in case no such entry is available. --* +getProperties+ allows to extract all property data to a +Map<String,String>+. Other methods like +containsKey, -- keySet+ as well as streaming operations then can be applied on the returned +Map+ instance. --* +int getOrdinal()+ defines the ordinal of the +PropertySource+. Property sources are managed in an ordered chain, where -- property sources with higher ordinals override ones with lower ordinals. If the ordinal of two property sources is -- the same, the natural ordering of the fully qualified class names of the property source implementations is used. -- The reason for not using +@Priority+ annotations is that property sources can define dynamically their ordinals, -- e.g. based on a property contained with the configuration itself. -- Implementations of this API may provide additional functionality to adapt the default ordinal of auto-discovered -- property sources. --* Finally +getName()+ returns a (unique) name that identifies the +PropertySource+ within its containing +ConfigurationContext+. -- --This interface can be implemented by any kind of logic. It could be a simple in memory map, a distributed configuration --provided by a data grid, a database, the JNDI tree or other resources. Or it can be a combination of multiple --property sources with additional combination/aggregation rules in place. -- --+ConfigSources+ to be picked up (auto-discovered) automatically and be added to the _default_ +Configuration, must be --registered using the Java +ServiceLoader+ (or the mechanism provided by the current active +ServiceContext+, see later --in this document for further details). -- -- --[[ConfigSourceProvider]] --=== Interface ConfigSourceProvider -- --Instances of this type can be used to register multiple instances of +ConfigSource+. -- --[source,java] ---------------------------------------------- --@FunctionalInterface --public interface ConfigSourceProvider{ -- Iterable<ConfigSource> getConfigSources(); --} ---------------------------------------------- -- --This allows to evaluate the config sources to be read/that are available dynamically. All config sources --are read out and added to the current chain of +ConfigSource+ instances within the current +Config+, --refer also to [[Config]]. -- --+ConfigSourceProviders+ are by default registered using the Java +ServiceLoader+ or the mechanism provided by the --current active +ServiceContext+. -- -- --[[Filter]] --=== Interface Filter -- --Also +Filters+ can be added to a +Config+. They are evaluated each time before a configuration value --is passed to the user. Filters can be used for multiple purposes, such as -- --* resolving placeholders --* masking sensitive entries, such as passwords --* constraining visibility based on the current active user --* ... -- --NOTE: Filters are not defined by the configuration JSR, but an useful extension of the Tamaya toolkit. -- --For +Filters+ to be picked up automatically and added to the _default_ +Config+ must be, by default, --registered using the Java +ServiceLoader+ (or the mechanism provided by the current active +ServiceContext+). --Similar to config sources they are managed in an ordered filter chain, based on the --class level +@Priority+ annotations (assuming +0+ if none is present). -- --A +Filter+ is defined as follows: -- --[source,java] ---------------------------------------------- --@FunctionalInterface --public interface Filter{ -- String filterProperty(String key, String value); --} ---------------------------------------------- -- --Hereby: -- --* returning +null+ will remove the key from the final result. --* non null values are used as the current value of the key. Nevertheless for resolving multi-step dependencies -- filter evaluation has to be continued as long as filters are still changing some of the values to be returned. -- To prevent possible endless loops after a defined number of loops evaluation is stopped. -- --Additionally Tamaya allows to configure an additional +FilterContext+, which can be accessed from the filter --implementation. +FilterContext+ provides additional metdata, including the property accessed, which is useful --in many use cases: -- --[source,java] ---------------------------------------------- --FilterContext context = FilterContext.getContext(); ---------------------------------------------- -- -- --[[ConfigValueCombinationPolicy]] --==== Interface ConfigValueCombinationPolicy -- --This interface is purely optional and can be used to adapt the way how property key/value pairs are combined to --build up the final configuration _raw_ value to be passed over to the +Filters+. The default implementation --is just overriding all values read before with the new value read. Nevertheless for collections and other use cases --more intelligent logic is required. -- --[source,java] ---------------------------------------------- --@FunctionalInterface --public interface ConfigValueCombinationPolicy{ -- -- ConfigValueCombinationPolicy DEFAULT_OVERRIDING_COLLECTOR = -- new ConfigValueCombinationPolicy(){ -- @Override -- public String collect(String currentValue, String key, -- ConfigSource configSource) { -- String value = configSource.getValue(key); -- return value!=null?value:currentValue; -- } -- }; -- -- String collect(String currentValue, String key, -- ConfigSource configSource); --} ---------------------------------------------- -- --Looking at the +collect+ method's signature, returning a value allows also to filter/combine/use meta entries. -- -- --[[ConfigContext]] --==== The Config Context -- --A +Config+ provides some access to it's underlying elements by exposing the +getPropertySources()+ --method. Nevertheless a +Config+ at least also contains +Converters+. In Tamaya the underlying --implementation also supports filtering as well as multiple converters, organized as a --converter chain. -- --All these artifacts can be accessed using Tamaya's +ConfigContext+: -- --[source,java] --.Accessing the current +ConfigContext+ ---------------------------------------------- --Config config = ...; --ConfigContext context = ConfigContext.from(config); ---------------------------------------------- -- --The +ConfigContext+ provides access to the internal artifacts that determine the +Config+ and --also defines the ordering of the property sources, filters and converters contained: -- --* +ConfigSources+ registered (including the PropertySources provided from +PropertySourceProvider+ instances). --* +Filters+ registered, which filter values before they are returned to the client --* +Converter+ instances that provide conversion functionality for converting String values to any other types. --* the current +ConfigValueCombinationPolicy+ that determines how property values from different config sources are -- combined to the final property value returned to the client. -- --NOTE: Implementations of the JSR API that want to interoperate with the Tamaya extensions best -- implement the +ConfigContextSupplier+ interface by the +Config+ implementation. -- -- --[[Mutability]] --==== Changing the current Config -- --A +Config+ is not mutable once it is created. In many cases mutability is also not needed. Nevertheless --there are use cases where the current +Config+ must be adapted: -- --* New configuration files where detected in a folder observed by Tamaya. --* Remote configuration, e.g. stored in a database or alternate ways has been updated and the current system must -- be adapted to these changes. --* The overall configuration context is manually setup by the application logic. --* Within unit testing alternate configuration setup should be setup to meet the configuration requirements of the -- tests executed. -- --In such cases the +Config+ may change, meaning it must be possible: -- --* to add and load +ConfigSource+ instances --* to define the +Converter+ used for a type -- --In Tamaya, additionally it is also possible: -- --* to remove and reorder +ConfigSource+ instances --* to add or remove +Converter+ instances --* to add or remove +Filter+ instances --* to redefine the current +ConfigValueCombinationPolicy+ instances. -- --The JSR provides a +ConfigBuilder+, which can be obtained as follows: -- --[source,java] --.Accessing a +ConfigBuilder+ ---------------------------------------------- --ConfigBuilder emptyConfigBuilder = ConfigProviderResolver.getInstance().getConfigBuilder(); ---------------------------------------------- -- --Finally when we are finished a new +Config+ can be created: -- --[source,java] --.Creating and applying a new +Config+ ---------------------------------------------- --Config config = emptyConfigBuilder.withPropertySources(new MyPropertySource()) -- .withDiscoveredConverters() -- .build(); ---------------------------------------------- -- --Unfortunately the JSR API is rather constraint, so Tamaya provides a more powerful builder --(extending the JSR +ConfigBuilder+), that allows to add, remove or --reorder config sources, converters and filters or changing any other aspect of a +Config+: -- --A +TamayaConfigBuilder+ can be obtained in several ways: -- --[source,java] --.Chain manipulation using a fresh +TamayaConfigBuilder+ ---------------------------------------------- --TamayaConfigBuilder builder = TamayaConfigBuilder.create(); --builder.withDiscoveredSources(); --ConfigSource configSource = builder.getConfigSource("sourceId"); -- --// changing the priority of a config source. The ordinal value hereby is not considered. --// Instead the position of the property source within the chain is changed. --builder.decreasePriority(configSource); -- --// Alternately a comparator expression can be passed to establish the defined ordering... --builder.sortFilters(MyFilterComparator::compare); ---------------------------------------------- -- --Alternately a new builder can be created from any +Config+ instance: -- --[source,java] --.Chain manipulation using a fresh +TamayaConfigBuilder+ ---------------------------------------------- --Config config = ...; --TamayaConfigBuilder builder = TamayaConfigBuilder.from(config); --ConfigSource configSource = builder.getConfigSource("sourceId"); -- --// changing the priority of a config source. The ordinal value hereby is not considered. --// Instead the position of the property source within the chain is changed. --builder.decreasePriority(configSource); -- --// Alternately a comparator expression can be passed to establish the defined ordering... --builder.sortFilters(MyFilterComparator::compare); ---------------------------------------------- -- --Finally if a new +Config+ can be created. --Optionally the new +Config+ can also be installed as the new _default_ +Config+ --instace as illustrated below: -- --[source,java] --.Creating and applying a new +Config+ ---------------------------------------------- --Config newConfig = builder.build(); -- --// Apply the new config to replace the current configuration: --ConfigProviderResolver.getInstance().registerConfig(newConfig, Thread.currentThread().getContextClassLoader()); ---------------------------------------------- -- -- --[[ConfigProviderResolver]] --==== Implementing and Managing Configuration -- --The most important SPI for Config is the +ConfigProviderResolver+ abstract class, which is backing up the --+ConfigProvider+ singleton. Implementing this class allows -- --* to fully determine the implementation class for +Config+ --* to manage the current +Config+ in the scope and granularity required. --* to provide access to the right +Config+ based on the current runtime context. --* Performing changes as set with the current +ConfigBuilder+. -- --[[BuilderCore]] --== The TamayaConfigtBuilder interface in Detail -- --=== Overview -- --The Tamaya builder module provides a generic (one time) builder for creating +Config+ instances, --e.g. as follows: -- --[source,java] ----------------------------------------------------------------- --TamayaConfigBuilder builder = TamayaConfigBuilder.create(); --// do something --Config config = builder.build(); ----------------------------------------------------------------- -- --Basically the builder allows to create configuration instances completely independent of the current configuration --setup. This gives you full control how and when +Config+ is created. -- -- --=== Supported Functionality -- --The builder allows you to add +ConfigySource+ instances: -- --[source,java] ------------------------------------------------------------------ --TamayaConfigBuilder builder = ... --builder.withConfigSources(sourceOne, sourceTwo, sourceThree --Config config = builder.build(); ------------------------------------------------------------------ -- --Hereby the ordering of the config sources is not changed, regardless of the ordinals provided --by the config sources. This allows alternate ordering policies easily being implemented because --creating a configuration based on a configuration context is already implemented and provided by the core --API. -- --Similarly you can add +Filters+: -- --[source,java] ------------------------------------------------------------------ --builder.withFilters(new MyConfigFilter()); ------------------------------------------------------------------ -- --...or +ConfigSourceProvider+ instances: -- --[source,java] ------------------------------------------------------------------ --builder.addConfigSourceProvider(new MyPropertySourceProvider()); ------------------------------------------------------------------ -- -- -- --[[ServiceContext]] --==== The ServiceContext -- --The +ServiceContext+ allows to define how components are loaded in Tamaya. It is the glue layer, which interacts --with the underlying runtime system such as Java SE, Java EE, OSGI, VertX etc. --The +ServiceContext+ hereby defines access methods to obtain components, whereas itself it is available from the --+ServiceContextManager+ singleton: -- --[source,java] --.Accessing the +ServiceContext+ ---------------------------------------------- --ServiceContext serviceContext = ServiceContextManager.getServiceContext(); -- --public interface ServiceContext{ -- int ordinal(); -- <T> T getService(Class<T> serviceType); -- <T> List<T> getServices(Class<T> serviceType); --} ---------------------------------------------- -- --With the +ServiceContext+ a component can be accessed in two different ways: -- --. access as as a single property. Hereby the registered instances (if multiple) are sorted by priority and then finally -- the most significant instance is returned only. --. access all items given a type. This will return (by default) all instances loadedable from the current -- runtime context, ordered by priority (the most significant components added first). -- -- --## Examples --### Accessing Configuration -- --_Config_ is obtained from the ConfigProvider singleton: -- --[source,java] --.Accessing +Config+ ---------------------------------------------- --Config config = ConfigProvider.getConfig(); ---------------------------------------------- -- --Many users in a SE context will probably only work with _Config_, since it offers all functionality --needed for basic configuration with a very lean memory and runtime footprint. It is also possible --to access optional values: -- --[source,java] ---------------------------------------------- --Config config = ConfigProvider.getConfig(); --String myKey = config.getValue("myKey", String.class); // never returns null --Optional<Integer> myLimit = config.getOptionalValue("all.size.limit", Integer.class); ---------------------------------------------- -- -- --### Environment and System Properties -- --By default environment and system properties are included into the _Config_. So we can access the current --_PROMPT_ environment variable as follows: -- --[source,java] ---------------------------------------------- --String prompt = ConfigProvider.getConfig().getValue("PROMPT", String.class); ---------------------------------------------- -- --Similary the system properties are directly applied to the _Config_. So if we pass the following system --property to our JVM: -- --[source,java] ---------------------------------------------- --java ... -Duse.my.system.answer=yes ---------------------------------------------- -- --we can access it as follows: -- --[source,java] ---------------------------------------------- --boolean useMySystem = ConfigProvider.getConfig().getValue("use.my.system.answer", boolean.class); ---------------------------------------------- -- -- --### Adding a Custom Configuration -- --Adding a classpath based configuration is simply as well: just implement an according _ConfigSource_. With the --_tamaya-spi-support_ module you just have to perform a few steps: -- --. Define a ConfigSource as follows: -- --[source,java] ---------------------------------------------- -- public class MyConfigSource extends PropertiesResourceConfigSource{ -- -- public MyConfigSource(){ -- super(ClassLoader.getSystemClassLoader().getResource("META-INF/cfg/myconfig.properties"), DEFAULT_ORDINAL); -- } -- } ---------------------------------------------- -- --Then register +MyConfigSource+ using the +ServiceLoader+ by adding the following file: -- --[source,listing] ---------------------------------------------- --META-INF/servicesjavax.config.spi.ConfigSource ---------------------------------------------- -- --...containing the following line: -- --[source,listing] ---------------------------------------------- --com.mypackage.MyConfigSource ---------------------------------------------- -- -- --[[APIImpl]] --== API Implementation -- --The Config API is implemented by the +tamaya-base+ and +tamaya-core+ module. Refer to the link:core.html[Core documentation] for --further details. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/core.adoc ---------------------------------------------------------------------- diff --cc content/documentation-new/core.adoc index e7a2c46,e7a2c46..0000000 deleted file mode 100644,100644 --- a/content/documentation-new/core.adoc +++ /dev/null @@@ -1,283 -1,283 +1,0 @@@ --:jbake-type: page --:jbake-status: published -- --[[Core]] --== Tamaya Core Implementation --=== Overview -- --Tamaya Core provides an implementation of the link:api.html[Configuration API] and adds additional functionality --and building blocks for supporting SPI implementations. -- --Tamaya contains the following core artifacts: -- --* *tamaya-base* provides implementations and base classes for different API artifacts such as +Config, -- ConfigContext, ConfigBuilder, BaseConfigSource+ and more. It is -- built as an independent module, which also can be used with other implementations. --* The *tamaya-core* -- implementation -- ** leverages these base classes to build up a full API implementation, adding converter -- implementations for most common Java types. -- ** A +java.util.ServiceLoader+ based +ServiceContext+ implementation. This allows component priorization based -- on the +@Priority+ annotations. -- ** A +PropertyConverterManager+ that loads and stores references to all the preconfigured +PropertyConverter+ instances, -- thus providing type conversion for all important types. --* A simple default configuration setup using the current classpath and an optional staging variable. --* It collects all +ConfigSource+ and +ConfigSourceProvider+ instances registered with the +ServiceLoader+ and -- registers them in the global +ConfigurationContext+ --* It provides a +ConfigBuilder+ implementation (+DefaultConfigBuilder+), including an extended +TamayaConfigBuilder+ -- variant. -- --The overall size of the library is very small. All required components are implemented and registered, so basically the --Core module is a complete configuration solution. Nevertheless it is also very minimalistic, but fortunately is flexible --enough to be extended/accommodated with additional features as needed, such as -- --* placeholder and resolution mechanisms (+org.apache.tamaya.ext:tamaya-resolver+) --* dynamic resource path lookup, e.g. with ant styled patterns (+org.apache.tamaya.ext:tamaya-resources+) --* configuration injection and configuration templates (+org.apache.tamaya.ext:tamaya-injcetion-api+) --* abstraction for reusable formats (+org.apache.tamaya.ext:tamaya-formats+) --* integration with other existing solutions (e.g. +org.apache.tamaya.ext:tamaya-spring+) --* configuration and configuration isolation targeting Java EE (+org.apache.tamaya.ext:tamaya-injection-ee+) --* dynamic configuration and configuration updates (+org.apache.tamaya.ext:tamaya-events+) --* remote configuration (+org.apache.tamaya.ext:tamaya-etcd, org.apache.tamaya.ext:tamaya-consul, -- org.apache.tamaya.ext:tamaya-hazelcast+) --* and more -- --For details about the extension modules available and their functionality refer to the link:extensions.html[extension user guide]. -- -- --[[CoreConverters]] --=== Default Converters -- --The _SPI_ base module provides several +Converter+ implementations, which are automatically registered by the --_Core_ module. Find below the listing of converters automatically registered with the Core module: -- --[width="100%",frame="1",options="header",grid="all"] --|======= --|_Target Type_ |_Class Name_ |_Supported Formats_ --|java.math.BigDecimal |BigDecimalConverter |1.2345, 0xFF --|java.math.BigInteger |BigIntegerConverter |0xFF, 1234 --|java.ui.lang.Boolean |BooleanConverter |true, false, T, F, 1 ,0 --|java.ui.lang.Byte |ByteConverter |0xFF, MIN_VALUE, MAX_VALUE, 123 --|java.ui.lang.Character |CharConverter |0xFF, 'a', 'H', 123 --|java.ui.lang.Class |ClassConverter |<fully qualified class name> --|java.util.Currency |CurrencyConverter |CHF, 123 --|java.ui.lang.Double |DoubleConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE --|_Enums_ |EnumConverter |<Enum item name> --|java.ui.lang.Float |FloatConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE --|java.ui.lang.Integer |IntegerConverter |1, 0xD3, MIN_VALUE, MAX_VALUE --|LocalDate |LocalDateConverter |<Date as defined by LocalDate.parse(String) --|LocalTime |LocalTimeConverter |<Time as defined by LocalTime.parse(String) --|LocalDateTime |LocalDateTimeConverter |<LocalDateTime as defined by LocalDateTime.parse(String)> --|java.ui.lang.Long |LongConverter |1, 0xD3, MIN_VALUE, MAX_VALUE --|java.ui.lang.Number |NumberConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY --|java.ui.lang.Short |ShortConverter |1, 0xD3, MIN_VALUE, MAX_VALUE --|java.net.URI |URIConverter |http://localhost:2020/testresource?api=true --|java.net.URL |URLConverter |http://localhost:2020/testresource?api=true --|ZoneId |ZoneIdConverter |Europe/Zurich --|======= -- -- --=== Registering Converters -- --Additional +Converters+ can be implemented easily. It is recommended to register them using --the +java.util.ServiceLoader+, meaning you add a file under +META-INF/service/javax.config.spi.Converter+ --containing the fully qualified class names of the converters to be registered (one line each) to enable --auto-discovery. -- --Alternatively you can also use a +TamayaConfigBuilder+ to add additional converters programmatically. -- -- --[[ComponentLoadingAndPriorization]] --=== Component Loading and Priorization -- --Tamaya _Core_ in general loads all components by default using the +java.util.ServiceLoader+ mechanism. This means that --new components must be registered by adding a file under +META-INF/service/<myInterfaceName>+ containing the fully --qualified implementation class names of the components to be registered (one line per each). --The +ServiceLoader+ itself does not provide any functionality for overriding or ordering of --components. Tamaya _Core_ adds such a functionality with the possibility to add +@Priority+ --annotations to the components registered. By default, and if no annotation is added +0+ is assumed --as priority. Hereby higher values preceed lower values, meaning -- --* if a _singleton_ component is accessed from the current +ServiceContext+ the component with the -- higher value effectively _overrides/replaces_ any component with lower values. --* if a _collection_ of components is obtained from the +ServiceContext+ the components are _ordered_ -- based on their priorities, where the ones with higher priority are before components with lower -- priority. --* if priorities _match_ Tamaya _Core_ additionally sorts them using the _simple class name_. -- This ensures that ordering is still defined and predictable in all scenarios. -- --NOTE: Sorting the property sources based on their ordinal value is only the default ordering -- principle applied. By implementing your own implementation of +ConfigurationProviderSpi+ -- you can apply a different logic: -- -- --[[RegisteringConfigSources]] --=== Registering ConfigSources -- --+ConfigSource+ implementations that provide configuration properties are registered as components as described in the --previous section. Hereby the precedence (ordering) of property sources is not hard-coded. Instead a +Comparator<ConfigSource>+ --can be passed to a +ConfigurationContextBuilder+ to perform automatic ordering of the property sources --registered. The default implementation hereby uses the following logic: -- --. It checks for an property entry +config.ordinal+ if present the value is parsed into an +int+ value and used as -- the ordinal val value. --. It checks for an explicit method +int getOrdinal()+, if found its value is taken as an ordinal. --. It checks for a +@Priority+ annotation, if present the priority value is used as an ordinal. --. If none of the above works, +0+ is assumed as ordinal value. --. If multiple +ConfigSource+ instances share the same ordinal value, they are ordered based on their fully qualified -- class names. -- --Custom implementations of the config source comparator can be applied by calling --+TamayaConfigBuilder.sortSources(Comparator<ConfigSource>)+. The default comparator can be replaced --by passing the fully qualified comparator class name as system property: -- --+-Dconfig-source-comparator=a.b.c.MyComparatorClass+ -- --The ladder allows to adapt the ordering of auto-discovered config sources, even if the value returned by --+int getOrdinal()+ cannot be changed. -- -- --[[CoreConfigSources]] --== Configuration Setup in Core -- --Tamaya Core provides a minimal configuration setting, that allows you to configure SE --applications already easily. Basically configuration is built up by default as follows: -- --. Read environment properties and add them prefixed with +env.+ --. Read all files found at +META-INF/javaconfig.properties+ -- and +META-INF/javaconfig.xml+ -- -- --=== Overview of Registered Default Config Sources and Providers -- --The Tamaya Core implementation provides a couple of default +ConfigSource+ implementations, which are automatically --registered. They are all in the package +org.apache.tamaya.base.configsource+: -- --[width="100%",frame="1",options="header",grid="all"] --|======= --|_Type_ |_Class Name_ |_Ordinal Used_ --|META-INF/javaconfig.properties |JavaConfigurationProvider |100 --|META-INF/javaconfig.xml |JavaConfigurationProvider |100 --|JNDI Entries |JNDIConfigSource |200 --|Environment Properties |EnvironmentConfigSource |300 --|System Properties |SystemConfigSource |1000 --|======= -- --NOTE: Similarly to converters the config sources shown here are defined within the "tamaya-base* module -- and automatically registered with the *tamaya-core* implementation using Tamaya's auto-discovery mechanisms. -- --NOTE: +JNDIConfigSource+ is provided by the `tamaya-jndi` extension module. -- -- --=== Abstract Class PropertiesFileConfigSource -- --The abstract class +PropertiesFileConfigSource+ can be used for implementing a +ConfigSource+ based on a +URL+ --instance that points to a +.properites+ file. It requires a +URL+ to be passed on the constructor: -- --[source,java] ---------------------------------------------- --PropertiesFileConfigSource(URL url); ---------------------------------------------- -- -- --==== Abstract Class PropertiesConfigSource -- --The abstract class +PropertiesConfigSource+ can be used for implementing a +ConfigSource+ based on a +Properties+ --instance. It requires a +Properties+ to be passed on the constructor: -- --[source,java] ---------------------------------------------- --PropertiesConfigSource(Properties properties); ---------------------------------------------- -- -- --==== Abstract Class BaseConfigSource -- --The abstract class +BaseConfigSource+ can be used for implementing custom +ConfigSource+ classes. It requires only --one method to implemented: -- --[source,java] --.Implementing a ConfigSource using BaseConfigSource ---------------------------------------------- --public class MyConfigSource extends BaseConfigSource{ -- -- public String getName(){ -- // return a unique name for the config source, e.g. based on the underlying resource. This name also -- // allows to access the property source later -- } -- -- public Map<String, String> getProperties(){ -- // Get a map with all properties provided by this config source -- } -- --} ---------------------------------------------- -- --By default the ordinal of the config sources will be 1000, unless the key +config.ordinal+ --as defined in +ConfigSource.CONFIG_ORDINAL+ is present in the current +ConfigSource+. Of course --it is also possible to override the inherited +protected void initializeOrdinal(final int defaultOrdinal)+, --or directly +int getOrdinal()+. -- -- --[[CoreConfigSourceProviders]] --=== Default ConfigSourceProvider in Core -- --With +org.apache.tamaya.core.provider.JavaConfigurationProvider+ there is also a default +ConfigSourceProvider+ --present that loads all +.properties+ files found at +META-INF/javaconfig.properties+ --and +META-INF/javaconfig.xml+. -- -- --=== Replacing the property value evaluation policy -- --Tamaya's core implementation allows to replace the complete logic how a configuration value or the current configuration --properties are calculated from a given +ConfigContext+ by implementing the +ConfigValueEvaluator+ --interface: -- --[source,java] ---------------------------------------------- --/** -- * Component SPI which encapsulates the evaluation of a single or full <b>raw</b>value -- * for a {@link ConfigurationContext}. -- */ --public interface ConfigValueEvaluator { -- -- /** -- * Evaluates single value using a {@link ConfigContext}. -- * @param key the config key, not null. -- * @param context the context, not null. -- * @return the value, or null. -- */ -- ConfigValue evaluteRawValue(String key, ConfigContext context); -- -- /** -- * Evaluates all property values from a {@link ConfigurationContext}. -- * @param context the context, not null. -- * @return the value, or null. -- */ -- Iterable<ConfigValue> evaluateRawValues(ConfigContext context); -- --} ---------------------------------------------- -- --The default implementation +DefaultConfigValueEvaluator+ implements the following logic: -- --. Collect all +ConfigSources+ from the context. --. Access +String get(String)+ (single key access)/ +Map<String,String> getProperties()+ -- (config map access) from each property source and combine the previous with the next value using -- the +ConfigValueCombinationPolicy+ in place. -- --The resulting _raw_ value(s) are then finally handed over to the registered filters and finally --converted to +String/Map<String,String>+ as required by the user API. -- --To replace this default behaviour you must register your implementation with the current --+ServiceContext+. -- -- --[[Extensions]] --== Adding Extensions -- --Tamaya _Core_ only implements the link:api.html[API]. Many users require/wish additional functionality from a --configuration system. Fortunately there are numerous extensions available that add further functionality. --Loading extensions hereby is trivial: you only are required to add the corresponding dependency to the classpath. -- --For detailed information on the extensions available refer to the link:extensions.html[extensions documentation]. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions.adoc ---------------------------------------------------------------------- diff --cc content/documentation-new/extensions.adoc index 26b5832,26b5832..0000000 deleted file mode 100644,100644 --- a/content/documentation-new/extensions.adoc +++ /dev/null @@@ -1,65 -1,65 +1,0 @@@ --:jbake-type: page --:jbake-status: published -- --== Apache Tamaya: Extension Modules -- --toc::[] -- --=== Mature Extensions -- --Mature extensions have a stable API and SPI, similar to the API and Implementations provided. -- --[width="100%",frame="1",options="header",grid="all"] --|======= --|_Artifact_ |_Description_ |_Links_ --| | N/A: currently no extensions have reached that maturity level. | - --|+org.apache.tamaya.ext:tamaya-collections+ |Collections support. |link:extensions/mod_collections.html[Documentation] --|+org.apache.tamaya.ext:tamaya-events+ |Provides support for publishing configuration changes |link:extensions/mod_events.html[Documentation] --|+org.apache.tamaya.ext:tamaya-filter+ |Provides a programmatic filter for config entries. |link:extensions/mod_filter.html[Documentation] --|+org.apache.tamaya.ext:tamaya-features+ |Provides a simple feature check for loaded extensions. |link:extensions/mod_features.html[Documentation] --|+org.apache.tamaya.ext:tamaya-formats+ |Provides an abstract model for configuration formats |link:extensions/mod_formats.html[Documentation] --|+org.apache.tamaya.ext:tamaya-functions+ |Provides several functional extension points. |link:extensions/mod_functions.html[Documentation] --|+org.apache.tamaya.ext:tamaya-injection-api+ |Provides Tamaya's injection annotations API. |link:extensions/mod_injection.html[Documentation] --|+org.apache.tamaya.ext:tamaya-injection+ |Provides configuration injection services and configuration template support. |link:extensions/mod_injection.html[Documentation] --|+org.apache.tamaya.ext:tamaya-injection-cdi+ | Java EE/standalone compliant CDI integration using CDI for injection. | link:extensions/mod_cdi.html[Documentation] --|+org.apache.tamaya.ext:tamaya-jndi+ |Provides a JNDI based PropertySource. |link:extensions/mod_jndi.html[Documentation] --|+org.apache.tamaya.ext:tamaya-json+ |Provides format support for JSON based configuration. |link:extensions/mod_json.html[Documentation] --|+org.apache.tamaya.ext:tamaya-microprofile+ |Implemenation and Integration with the Microprofile API. | link:extensions/mod_microprofile.html[Documentation] --|+org.apache.tamaya.ext:tamaya-mutable-config+|Provides API/SPI for writing configuration |link:extensions/mod_mutable_config.html[Documentation] --|+org.apache.tamaya.ext:tamaya-optional+ |Lets a Tamaya configuration to be used as an optional project extension only. |link:extensions/mod_optional.html[Documentation] --|+org.apache.tamaya.ext:tamaya-osgi+ |Integration with OSGI containers. |link:extensions/mod_osgi.html[Documentation] --|+org.apache.tamaya.ext:tamaya-resolver+ |Provides placeholder and dynamic resolution functionality for configuration values. |link:extensions/mod_resolver.html[Documentation] --|+org.apache.tamaya.ext:tamaya-resources+ |Provides ant-style resource path resolution |link:extensions/mod_resources.html[Documentation] --|+org.apache.tamaya.ext:tamaya-spring+ |Integration for Spring / Spring Boot. | link:extensions/mod_spring.html[Documentation] --|+org.apache.tamaya.ext:tamaya-yaml+ |Support for using yaml as a configuration format. |link:extensions/mod_yaml.html[Documentation] --|======= -- --=== Extensions Sandbox -- --Extensions in _draft state_ rather experimental or not yet very mature. API changes may occurr at any time --and the may also have severe issues or even not work at all. So use at your own risk or join and help --us getting them stable and well tested! -- --NOTE: All extensions currently require Java 8. -- --[width="100%",frame="1",options="header",grid="all"] --|======= --|_Artifact_ |_Description_ |_Links_ --|+org.apache.tamaya.ext:tamaya-camel_beta+ |Integration with Apache Camel. | link:extensions/mod_camel.html[Documentation] --|+org.apache.tamaya.ext:tamaya-classloader-support+ |Configuration services considering classloaderas. |link:extensions/mod_classloader_support.html[Documentation] --|+org.apache.tamaya.ext:tamaya-commons_beta+ |Integration Support for Apache Commons. | - --|+org.apache.tamaya.ext:tamaya-configured-sysprops_beta+ | Tamaya configuration to be provided as +System.getProperties()+. | link:extensions/mod_sysprops.html[Documentation] --|+org.apache.tamaya.ext:tamaya-consul_beta+ |Integration with consul clusters. | link:extensions/mod_consul.html[Documentation] --|+org.apache.tamaya.ext:tamaya-etcd_beta+ |Integration with etcd clusters. | link:extensions/mod_etcd.html[Documentation] --|+org.apache.tamaya.ext:tamaya-hazelcast_beta+ |Integration with Hazelcast datagrids. | link:extensions/mod_hazelcast.html[Documentation] --|+org.apache.tamaya.ext:tamaya-jodatime_beta+ |Provides support for JodaTime. | link:extensions/mod_jodatime.html[Documentation] --|+org.apache.tamaya.ext:tamaya-management_alpha+ |Provides JMX support for inspecting configuration. |link:extensions/mod_management.html[Documentation] --|+org.apache.tamaya.ext:tamaya-metamodel_alpha+ |Provides an XML API for building configuration. |link:extensions/mod_metamodel-staged.html[Documentation] --|+org.apache.tamaya.ext:tamaya-remote_alpha+ |Remote configuration support using the server API. |link:extensions/mod_remote.html[Documentation] --|+org.apache.tamaya.ext:tamaya-server_alpha+ |Publishes configuration as a REST service. |link:extensions/mod_server.html[Documentation] --|+org.apache.tamaya.ext:tamaya-ui_alpha+ |Provides a web UI for a VM running Tamaya. |link:extensions/mod_ui.html[Documentation] --|+org.apache.tamaya.ext:tamaya-uom_beta+ |Provides additional converters based on the Units of Measurement JSR. |link:extensions/mod_uom.html[Documentation] --|+org.apache.tamaya.ext:tamaya-usagetracker_beta+ |Allows tracking of configuration usage. |link:extensions/mod_usagetracker.html[Documentation] --|+org.apache.tamaya.ext:tamaya-validation-alpha+ |Provides an XML API for validating configuration. |link:extensions/mod_validation.html[Documentation] --|+org.apache.tamaya.ext:tamaya-vertx-alpha+ |Provides Vertx integration. |link:extensions/mod_vertx.html[Documentation] --|======= http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_camel.adoc ---------------------------------------------------------------------- diff --cc content/documentation-new/extensions/mod_camel.adoc index b21df17,b21df17..0000000 deleted file mode 100644,100644 --- a/content/documentation-new/extensions/mod_camel.adoc +++ /dev/null @@@ -1,132 -1,132 +1,0 @@@ --:jbake-type: page --:jbake-status: published -- --= Apache Tamaya - Extension: Integration with Apache Camel -- --toc::[] -- -- --[[Camel]] --== Integration with Apache Camel (Extension Module) -- --Tamaya _Camel_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. -- --=== What functionality this module provides ? -- --The Tamaya _Camel_ module provides different artifacts which allows integration of Apachae Tamaya --configuration with Apache Camel. -- -- --=== Compatibility -- --The module is based on Java 8, so it will not run on Java 8 and beyond. -- -- --=== Installation -- --To benefit from configuration builder support you only must add the corresponding dependency to your module: -- --[source, xml] ------------------------------------------------- --<dependency> -- <groupId>org.apache.tamaya.ext</groupId> -- <artifactId>tamaya-camel</artifactId> -- <version>{tamaya_version}</version> --</dependency> ------------------------------------------------- -- -- --=== The Functionality Provided -- --Tamaya Camel comes basically with three artifacts: -- --* A Camel +ResolverFunction+ implementation adding explicit property resolution -- (+org.apache.tamaya.camel.TamayaPropertyResolver+). --* A Camel +PropertiesComponent+ implementation, which allows implicitly preconfigures the resolvers from above and -- additionally allows using Tamaya configuration as Camel _overrides_ -- (+org.apache.tamaya.camel.TamayaPropertiesComponent+). -- -- --=== Configuring using Camel Java DSL -- --Camel integration using Java DSL is basically simple: -- --[source, java] ------------------------------------------------- --import org.apache.tamaya.camel.TamayaPropertiesComponent; -- --camelContext.addComponent("properties", new TamayaPropertiesComponent()); ------------------------------------------------- -- --Given so you can then use +cfg+ or +tamaya+ as prefix for resolving entries with Tamaya as follows: -- --[source, java] ------------------------------------------------- --RouteBuilder builder = new RouteBuilder() { -- public void configure() { -- from("direct:hello1").transform().simple("{{cfg:message}}"); -- } --}; --camelContext.addRoutes(builder); --builder = new RouteBuilder() { -- public void configure() { -- from("direct:hello2").transform().simple("{{tamaya:message}}"); -- } --}; --camelContext.addRoutes(builder); ------------------------------------------------- -- -- --Optionally you can also configure +TamayaPropertiesComponent+ that all currently known Tamaya properties are used --as Camel overrides, meaning they are evaluated prior to all other available resolver functions in the Camel --+PropertiesComponent+: -- --[source, java] ------------------------------------------------- --TamayaPropertiesComponent props = new TamayaPropertiesComponent(); --props.setTamayaOverrides(true); ------------------------------------------------- -- -- --=== Configuring using Camel XML DSL -- --Camel integration using XML DSL is basically very similar. You just have to add the +properties+ component as bean --as well. All other configuration parameters (e.g. file URIs are similar supported). In the example code below we --again use Tamaya as the main configuration solutions only using Camel's default behaviour as a fallback: -- --[source, xml] ------------------------------------------------- --<beans xmlns="http://www.springframework.org/schema/beans"; -- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; -- xsi:schemaLocation=" -- http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd -- http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd -- "> -- -- <routeContext id="myCoolRoutes" xmlns="http://camel.apache.org/schema/spring";> -- <route id="r1"> -- <from uri="direct:hello1"/> -- <transform> -- <simple>{{message}}</simple> -- </transform> -- </route> -- <route id="r2"> -- <from uri="direct:hello2"/> -- <transform> -- <simple>{{cfg:message}}</simple> -- </transform> -- </route> -- <route id="r3"> -- <from uri="direct:hello3"/> -- <transform> -- <simple>{{tamaya:message}}</simple> -- </transform> -- </route> -- </routeContext> -- -- <bean id="properties" class="org.apache.tamaya.camel.TamayaPropertiesComponent"> -- <property name="tamayaOverrides" value="true"/> -- </bean> -- --</beans> ------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_cdi.adoc ---------------------------------------------------------------------- diff --cc content/documentation-new/extensions/mod_cdi.adoc index deb8842,deb8842..0000000 deleted file mode 100644,100644 --- a/content/documentation-new/extensions/mod_cdi.adoc +++ /dev/null @@@ -1,244 -1,244 +1,0 @@@ --:jbake-type: page --:jbake-status: published -- --= Apache Tamaya - Extension: CDI Support -- --toc::[] -- -- --[[CDI]] --== Tamaya CDI Integration (Extension Modules) -- --Tamaya _CDI_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. -- -- --=== What functionality this module provides ? -- --Apache _CDI_ provides integration with CDI: -- --* Loading of CDI managed SPI components as configuration extensions such as +ConfigSources, ConfigSourceProviders, -- Converters, Filters, etc+. This also includes SPI defined by any Tamaya submodules. -- This is useful when Tamaya is used as an application module managed by the CDI implementation. --* Implement and enable Tamaya's configuration injection services (either using CDI injection or -- Tamaya's standalone injection module. -- --Hereby there are two implementations provided: -- --* +tamaya-injection-cdi+ implements injection by using CDI's injection mechanism to inject configuration values into the -- beans managed by the CDI systems. --* +tamaya-injection-standalone+ implements injection by integrating the +tamaya-injection+ SE based injection module (also used -- for Spring and OSGI injection) with CDI. Injection hereby is performed by the Tamaya SE module, whereas -- beans and injection control overall are still managed by CDI. --* One difference, of course, is that +tamaya-injection-standalone+ also provides an SE compatible API (+ConfigurationInjection, -- ConfigurationInjector+), which is not available, when using the purely CDI based variant. -- --Most annotations used are defined as part of the Config JSR API, whereas Tamaya adds additional features not available --in the JSR as separate modules. This allows you to code against the injection API without dependency on the concrete --injection implementation. As a consequence your components will be compatible regardless if deployed in a pure SE or as --Java EE (CDI) or Spring environment: -- ------------------------------------------------- --<dependency> -- <groupId>javax.config</groupId> -- <artifactId>config-api</artifactId> -- <version>{config_api_version}</version> --</dependency> --<dependency> -- <groupId>org.apache.tamaya.ext</groupId> -- <artifactId>tamaya-injection-api</artifactId> -- <version>{tamaya_version}</version> --</dependency> ------------------------------------------------- -- -- --=== Compatibility -- --All modules are based on Java 8, so they will not run on Java 8 and beyond. -- -- --=== Installation -- --To benefit from Tamaya CDI integration you only must one of the following dependencies to your module. Ensure that --you never have installed both CDI extensions at the same time because this may be lead to unforseen side-effects. -- --.CDI Java EE Application Configuration --[source, xml] ------------------------------------------------- --<dependency> -- <groupId>org.apache.tamaya.ext</groupId> -- <artifactId>tamaya-cdi</artifactId> -- <version>{tamaya_version}</version> --</dependency> ------------------------------------------------- -- --.To use Tamaya's _standalone injection support_, you additionally should add the --following dependency. If this dependency is missing injection is purely based on --CDI injection features. -- --[source, xml] ------------------------------------------------- --<dependency> -- <groupId>org.apache.tamaya.ext</groupId> -- <artifactId>tamaya-injection-standalone</artifactId> -- <version>{tamaya_version}</version> --</dependency> ------------------------------------------------- -- --Both components will auto-register its components and override the default +ServicceContext+ in use. Additionally they --register CDI extensions that implement Configuration injection as described before. -- --For working with a pure non Java EE environment have a look at the link:mod_injection-standalone.html[tamaya-injection-standalone module]. -- --Additionally you have to register Tamaya's CDI extension modules into your `beans-xml`: -- --Contents of `META-INF/services/javax.enterprise.inject.spi.Extension`: --[source, properties] ------------------------------------------------- --# Register Tamaya to perform injection --# org.apache.tamaya.cdi.TamayaCDIInjectionExtension --# org.apache.tamaya.cdi.TamayaSEInjectionExtension --org.apache.tamaya.cdi.TamayaCDIAccessor ------------------------------------------------- -- --If you want to use CDI standard injection (using +@Inject @Config+), activate --+org.apache.tamaya.cdi.TamayaCDIInjectionExtension+ as a CDI extension. -- --If you want to use +SE based injection+ (using +@Config+ *without* +@Inject+), --activate +org.apache.tamaya.cdi.TamayaSEInjectionExtension+ instead of. -- --Though not recommended, it is possible to activate both extension at the same time. -- -- --=== Annotating your Classes -- --Basically annotating your classes is stright forward. Depending --on the module deployed, your annotations are handled by a CDI producer (+tamaya-cdi-ee+) or the --Tamaya SE injection mechanism (+tamaya-cdi-se+). All types injected by this module are injected --using _dependent scope_. -- -- --[source, java] ---------------------------------------------------------- --@RequestScoped --public class ConfiguredClass{ -- -- @Config -- private String testProperty; -- -- @Config(key="a.b.c.key1", -- defaultValue="The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.") -- String value1; -- -- @Config(key="foo") -- private String value2; -- -- @Config(defaultValue="N/A") -- private String runtimeVersion; -- -- @Config(defdaultValue="${sys:java.version}") -- private String javaVersion2; -- -- @Config(defaultValue="5") -- private Integer int1; -- -- ... -- --} ---------------------------------------------------------- -- -- -- --=== Registering CDI managed components into the Application's ConfigurationContext -- --As mentioned both modules allow to provide Tamaya SPI extensions modules as ordinary CDI managed beans. By default --extensions should be registered using +@Singleton+ or +@ApplicationScoped+ scope annotations. So you can define/deploy --additional application specific +PropertySources+ and other artifacts simply by defining a CDI managed bean implementing --the required SPI interface: -- --[source, java] ---------------------------------------------------------- --@Singleton --public class TestConfigSource implements ConfigSource{ -- -- final Map<String,String> config = new HashMap<>(); -- -- public TestConfigSource(){ -- config.put("a.b.c.key1", "keys current a.b.c.key1"); -- config.put("a.b.c.key2", "keys current a.b.c.key2"); -- config.put("{"+getName()+"}source", getClass().getName()); -- } -- -- @Override -- public int getOrdinal() { -- return 10; -- } -- -- @Override -- public String getName() { -- return getClass().getName(); -- } -- -- @Override -- public String get(String key) { -- return config.get(key); -- } -- -- @Override -- public Map<String, String> getProperties() { -- return config; -- } -- --} ---------------------------------------------------------- -- --To enable this (optional) feature you must replace Tamaya's +ServiceContext+ with the --CDI aware implementation: -- --Contents of `META-INF/services/org.apache.tamaya.spi.ServiceContext`: --[source, properties] ------------------------------------------------- --# Registering a CDI aware service context --org.apache.tamaya.cdi.CDIAwareServiceContext ------------------------------------------------- -- -- --=== Advanced Use Cases -- --Beside basic configuration Tamaya also covers additional requirements: -- --* _Reading multiple keys, where the first successful one is determining the value of the configuration, is -- simply possible, by defining additional keys with +@ConfigFallbackKeys+ annotation. -- E.g. for trying first +a.b+ and then +new.b+ you would configure it as follows: -- --[source,java] ---------------------------------------------------------------------------------------- --@Config(key="a.b") --@ConfigFallbackKeys({"new.b"}) --private String value; ---------------------------------------------------------------------------------------- -- --* When you must apply a some special conversion, or you use a type that is not registered -- for conversion, you can configure a custom converter to be applied as follows: -- --[source,java] ---------------------------------------------------------------------------------------- --@Config(key="a.b") --@WithConverter(MyConverter.class) --private MySpecialFooType value; ---------------------------------------------------------------------------------------- -- --* Often multiple keys in a class belong to the same root section. So instead of copying this to -- every entry you can define the most common root sections in the type's header: -- --[source,java] ---------------------------------------------------------------------------------------- --@ConfigDefaultSections({"aaaa", "new"}); --public class MyType{ -- --@Config(key="b"} --@ConfigFallbackKeys({"[legacy.bKey]"}) // lookups: "aaaa.b", "new.b", legacy.bKey --private String value; ---------------------------------------------------------------------------------------- -- --In the example above +legacy.bKey+ defines an absolute key, which is not combined with any defined --default section parts. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_classloader_support.adoc ---------------------------------------------------------------------- diff --cc content/documentation-new/extensions/mod_classloader_support.adoc index 501bcc8,501bcc8..0000000 deleted file mode 100644,100644 --- a/content/documentation-new/extensions/mod_classloader_support.adoc +++ /dev/null @@@ -1,79 -1,79 +1,0 @@@ --:jbake-type: page --:jbake-status: published -- --= Apache Tamaya - Extension: Classloader Isolation Support -- --toc::[] -- --[[Classloader]] --== Tamaya Classloader Aware ServiceContext (Extension Module) -- --Tamaya _Classloader_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. -- --=== What functionality this module provides ? -- --The Tamaya _Classloader_ support provides an alternative implementation of +java.util.ServiceLoader+, which is aware --of classloaders, hereby preventing multiple loading of components within a classloader hierarchy. -- -- --=== Compatibility -- --The module is based on Java 8, so it will not run on Java 8 and beyond. -- -- --=== Installation -- --To benefit from configuration server support you only must add the corresponding dependency to your module: -- --[source, xml] ------------------------------------------------- --<dependency> -- <groupId>org.apache.tamaya.ext</groupId> -- <artifactId>tamaya-classloader-support</artifactId> -- <version>{tamaya_version}</version> --</dependency> ------------------------------------------------- -- --The component will auto.register its components and override the default +ServiceContext+ in use by default --with an instance of type +org.apache.tamaya.clsupport.internal.CLAwareServiceContext+ with a precendence value --(component priority) of +10+. -- -- --=== How it works -- --Basically the component manages a +Map+ of all classloaders encountered. When services are accessed, the component --will evaluate the services as follows: -- --* the component walks up the class loader hierarchy. --* in a next step the hierarchy is traversed down from the parent to the current classloader. Hereby it is checked -- if the service list for the required type has been loaded already. If not the service configuration files are -- evaluated. --* This configuration file evaluation will ignore all resources already loaded by any of the already traversed parent -- classloaders. --* For each configuration file newly visible to the classloader currently traversed, the corresponding services are -- loaded unleyy, the same service class already has been loaded by one its parent classloaders or another file -- loaded with this classloader. --* Finally all services found are returned as the full collection of services valid for the given context (classloader). -- --This ensures no service is loaded multiple times, even when it is referenced multiple times in several service --configurations. Additionally every service is loaded on the classloader where it is also declared the first time. -- -- --=== Control Logging -- --The service component by default only logs errors. But it is possible to change this by reconfiguring the logging --levels on the following logging names/path: +org.apache.tamaya.clsupport.internal.CLAwareServiceContext+ -- --* _INFO_ logs additional info on the services accessed. --* _FINEST_ logs additional info on the services scanned and selected. -- -- --=== Classloader Aware Configuration -- --The mechanism above is used to provide a classloader aware implementation of +ConfigurationContext+ --(+org.apache.tamaya.clsupport.internal.CLAwareConfigurationContext+). Similarly to the service variants --this class provides a context implementation that manages the core configuration aspects considering classloading --hierarchies: -- --* +PropertySource+, +PropertySourceProviders+ --* +PropertyFilters+, +PropertyCombinationPolicy+
