http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_jodatime.adoc ---------------------------------------------------------------------- diff --cc content/documentation-new/extensions/mod_jodatime.adoc index 67a88a1,67a88a1..0000000 deleted file mode 100644,100644 --- a/content/documentation-new/extensions/mod_jodatime.adoc +++ /dev/null @@@ -1,80 -1,80 +1,0 @@@ --:jbake-type: page --:jbake-status: published -- --= Apache Tamaya - Extension: JodaTime -- --toc::[] -- --[[JodaTime]] --== Tamaya JodaTime (Extension Module) --Tamaya _JodaTime_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. -- --=== What functionality this module provides ? -- --Tamaya _JodaTime_ is an extension module to support the usage of http://www.joda.org/joda-time/[Joda-Time] --in conjunction with Tamaya. Tamaya JodaTime defines some additional property --converters to use Joda-Time types when accessing configuration. -- -- --=== Installation -- --To support Joda-Time types as configuration values, you only have to add the following --maven dependency to your project: -- --[source, listing] ------------------------------------------------- --<dependency> -- <grooupId>org.apache.tamaya.ext</groupId> -- <artifactId>tamaya-jodatime</artifactId> -- <version>{tamaya_version}</version> --</dependency> ------------------------------------------------- -- -- --=== Usage -- --After adding this module to your project you can retrieve --Joda-Time based values directly from a given configuration. -- --[source,java] ------------------------------------------------- --Config configuration = ConfigProvider.getConfig(); -- --DateTime pit = configuration.get("pointInTime", DateTime.class) ------------------------------------------------- -- --Currently the following types are supported: -- -- --[width="80%",options=header] --|================================================================ --| Joda-Time target type | Supported Input Formats --.12+^.<| +org.joda.time.DateTime+ +org.joda.time.Instant+ | `yyyy-MM-dd'T'HH:mm:ss.SSSZ` -- | `yyyy-MM-dd'T'HH:mm:ss.SSSz` -- | `yyyy-MM-dd'T'HH:mm:ss.SSS z` -- | `yyyy-MM-dd'T'HH:mm:ssZ` -- | `yyyy-MM-dd'T'HH:mm:ssz` -- | `yyyy-MM-dd'T'HH:mm:ss z` -- | `yyyy-MM-dd'T'HH:mmZ` -- | `yyyy-MM-dd'T'HH:mmz` -- | `yyyy-MM-dd'T'HH:mm z` -- | `yyyy-MM-dd'T'HHZ` -- | `yyyy-MM-dd'T'HHz` -- | `yyyy-MM-dd'T'HH z` --.2+^.<| +org.joda.time.DateTimeZone+ | `[+-]hh:mm` (reg.ex.) -- | all _timezone ids_ known by Joda-Time. --.3+^.<| +org.joda.time.Duration+ | `PTa.bS` -- | `PdDThHmMsS` -- | `ddThh:mm:ss` --.2+^.<| +org.joda.time.Period+ | `PyYmMwWdDThHmMsS` -- | `Pyyyy-mm-ddThh:mm:ss` --.4+^.<| +org.joda.time.LocalDate+ | `yyyy ['-' MM ['-' dd]]` -- | `yyyy ['-' DDD]` -- | `LocalDateConverter` -- | `yyyy ['-' dd ['-' MM]]` --.4+^.<| +org.joda.time.LocalTime+ | `['T']` _time-element_ -- | _time-element_ = HH [_minute-element_] _or_ [_fraction_] -- | _minute-element_ = ':' mm [_second-element_] _or_ [_fraction_] -- | _second-element_ = ':' ss [_fraction_] -- | _fraction_ = ('.' _or_ ',') digit+` --|================================================================
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_json.adoc ---------------------------------------------------------------------- diff --cc content/documentation-new/extensions/mod_json.adoc index a6e0572,a6e0572..0000000 deleted file mode 100644,100644 --- a/content/documentation-new/extensions/mod_json.adoc +++ /dev/null @@@ -1,80 -1,80 +1,0 @@@ --:jbake-type: page --:jbake-status: published -- --= Apache Tamaya - Extension: Builder -- --toc::[] -- -- --[[JSON]] --== Tamaya JSON (Extension Module) --Tamaya _JSON_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. -- --=== What functionality this module provides ? -- --Tamaya _JSON_ provides support for reading configuration using JSON --format: -- --[source, json] ------------------------------------------------- --{ -- "a.b"{ -- "key1": "blabla", -- "key2": true, -- } --} ------------------------------------------------- -- --Hereby the hierarchical structure of the JSON document will be mapped to a --flat key-value pairs of type `String`, e.g. the bove will be mapped to -- --[source, properties] ------------------------------------------------- --a.b.key1=blabla --a.b.key2=true ------------------------------------------------- -- --This extension uses SPI defined by the +tamaya.formats+ extension module. -- -- --=== Compatibility -- --The module is based on Java 8, so it will run on Java 8 and beyond. -- -- --=== Installation -- --To use the JSON extension module you only must add the corresponding dependency to your module: -- --[source, xml] ------------------------------------------------- --<dependency> -- <groupId>org.apache.tamaya.ext</groupId> -- <artifactId>tamaya-json</artifactId> -- <version>{tamaya_version}</version> --</dependency> ------------------------------------------------- -- --This extension also transitively requires the +tamaya.formats+ module. -- -- --=== Reading configuration in JSON -- --For reading JSON based onfiguration most easily a +JSONFormat+ can be --used: -- --[source, java] ------------------------------------------------- --ConfigurationData dataRead = ConfigurationFormats.readConfig( -- getClassLoader().getResource("myFileConfig.json"), new JSONFormat())); ------------------------------------------------- -- --Or, if you are fine with the _default_ mapping you can directly create a --+PropertySource+ using the _formats_ API (this works since this module --registers the _json_ format automatically using the `ServiceContext`): -- --[source, java] ------------------------------------------------- --ConfigSource ps = ConfigurationFormats.createConfigSource( -- getClassLoader().getResource("myFileConfig.json")); ------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_management.adoc ---------------------------------------------------------------------- diff --cc content/documentation-new/extensions/mod_management.adoc index df45aeb,df45aeb..0000000 deleted file mode 100644,100644 --- a/content/documentation-new/extensions/mod_management.adoc +++ /dev/null @@@ -1,97 -1,97 +1,0 @@@ --:jbake-type: page --:jbake-status: published -- --= Apache Tamaya - Extension: JMX Management Access -- --toc::[] -- -- --[[ExtModel]] --== Tamaya Management (JMX Support) (Extension Module) --Tamaya _Management_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. -- --=== What functionality this module provides ? -- --The Tamaya _Management_ module provides support for registering a JMX management bean for --accessing configuration. -- --=== Compatibility -- --The module is based on Java 8, so it will run on Java 8 and beyond. -- -- --=== Installation -- --To use the _management_ extension you only must add the corresponding dependency --to your module: -- --[source, xml] ------------------------------------------------- --<dependency> -- <groupId>org.apache.tamaya.ext</groupId> -- <artifactId>tamaya-management</artifactId> -- <version>{tamaya_version}</version> --</dependency> ------------------------------------------------- -- -- --=== The ManagedConfigMBean bean -- --The management model defines the MBean of type +ManagedConfigMBean+ as follows: -- -- --[source,java] ------------------------------------------------------------------------------- --public interface ManagedConfigMBean { -- String getJsonConfigurationInfo(); -- String getXmlConfigurationInfo(); -- Map<String, String> getConfiguration(); -- Map<String, String> getSection(String area, boolean recursive); -- Set<String> getSections(); -- Set<String> getTransitiveSections(); -- boolean isSectionExisting(String area); -- default boolean isSectionEmpty(String area); --} ------------------------------------------------------------------------------- -- --* +getJsonConfigurationInfo,getXmlConfigurationInfo+ return a JSON or XML representation of the --current configuration. --* +getConfiguration+ access the current configuration properties. --* +getSection+ allows to extract all entries below a certain subkey. With _recursive_ the query -- will not only return direct children, but also recursively walk down all subsection of the -- given section key. --* +getSections+ returns all current known section names. --* +getTransitiveSections+ return all sections, but also adds all transitive subsection as single -- entries to the set as well. --* +isSectionExisting+ and +isSectionEmpty+ allow for quering if entries are present under the given -- section keys. -- -- --=== Registering the ManagedConfigMBean -- --For registering the current +ManagedConfigMBean+ instance to the current MBean platform server, the --following static methods are available: -- --[source,java] ------------------------------------------------------------------------------- --public final class ConfigManagementSupport{ -- -- private JMXSupport(){} -- -- public static ObjectName registerMBean(); -- public static ObjectName registerMBean(String context); -- public static ObjectName unregisterMBean(); -- public static ObjectName unregisterMBean(String context); --} ------------------------------------------------------------------------------- -- --* +registerMBean+ creates a new +ManagedConfigMBean+ instance using the +ServiceContextManager+ -- and registers it. Optionally an additional _context_ parameter can be passed, which allows -- to register the management bean for different classloaders, e.g. for different -- ears. --* +unregisterMBean+ does the oppsite than registering obviously. -- --NOTE: The instance of +ManagedConfigMBean+ to be created and registered is evaluated by use og the -- +ServiceContextManager+. So you can replace the bean implementation by registering your -- overriding implementation using the current +ServiceContext+ (by default using -- +java.util.ServiceLoader+ and +@Priority+ annotation. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_metamodel.adoc ---------------------------------------------------------------------- diff --cc content/documentation-new/extensions/mod_metamodel.adoc index ed03b25,ed03b25..0000000 deleted file mode 100644,100644 --- a/content/documentation-new/extensions/mod_metamodel.adoc +++ /dev/null @@@ -1,632 -1,632 +1,0 @@@ --:jbake-type: page --:jbake-status: published -- --= Apache Tamaya - Extension: Metamodel (Configuration of Tamaya) -- --toc::[] -- -- --[[Model]] --== Tamaya Metamodel (Configuration of Tamaya) (Extension Module) -- --Tamaya _metamodel_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. -- -- --=== What functionality this module provides ? -- --The Tamaya _metamodel_ module provides support for configuring the Tamaya system itself. It --allows, like a logging configuration, to configure how your configuration framework should --work, where to find configuration and how it is combined using overrides, filters etc. -- --By default it uses an XML based configuration format as illustrated below: -- --[source, xml] --.Extract from `tamaya-config.xml` ------------------------------------------------- --<configuration> -- <!-- Context is evaluated first. --> -- <context> -- <context-entry name="stage">${properties:system:STAGE?default=DEV}</context-entry> -- <context-entry name="configdir">${properties:system:configdir?default=.}</context-entry> -- <context-entry name="app">${properties:system.APP?default=NONE}</context-entry> -- <context-entry name="context">${java:org.apache.tamaya.context.Context#id()}</context-entry> -- <context-entry name="company">Trivadis</context-entry> -- <context-entry name="default-formats">yaml,json</context-entry> -- <context-entry name="default-refresh-period">5 SECOND</context-entry> -- </context> -- -- <!-- combinationPolicy type="" / --> -- -- <!-- Configuration definition. --> -- -- <sources> -- <source enabled="${stage=TEST || stage=PTA || stage=PROD}" -- type="env-properties"> -- <filter type="PropertyMapping"> -- <param name="mapTarget">ENV.</param> -- </filter> -- <filter type="AccessMask"> -- <param name="roles">admin,power-user</param> -- <param name="policy">mask</param> -- <param name="mask">*****</param> -- <param name="matchExpression">SEC_</param> -- </filter> -- </source> -- <source type="sys-properties" > -- <filter type="ImmutablePropertySource" /> -- </source> -- <source type="file" refreshable="true"> -- <name>config.json</name> -- <param name="location">config.json</param> -- </source> -- ... -- </sources> --</configuration> ------------------------------------------------- -- --The module basically provides an XML representation to the +ConfigBuilder+ API. --It creates and registers the corresponding +Config+ --as the system's _default_ configuration (accessible from `ConfigProvider.getConfig(ClassLoader cl)`. -- -- --=== Compatibility -- --The module is based on Java 8, so it will not run on Java 8 and beyond. -- -- --=== Installation -- --To use _metamodel_ features you only must add the corresponding dependency to your module: -- --[source, xml] ------------------------------------------------- --<dependency> -- <groupId>org.apache.tamaya.ext</groupId> -- <artifactId>tamaya-model</artifactId> -- <version>{tamaya_version}</version> --</dependency> ------------------------------------------------- -- -- --=== Creating a Configuration using Meta-Configuration -- --The basic feature of this module is the capability of creating a +Config+ completely --based on a meta-configuration file. For this the +MetaConfig+ main singleton --provides different methods: -- --[source, java) ------------------------------------------------- --public final class MetaConfig { -- public static void configure(); -- public static void configure(URL metaConfig); -- public static ConfigBuilder createBuilder(URL metaConfig); -- public static Config createConfiguration(URL metaConfig); ------------------------------------------------- -- --* If you have supplied your meta-configuration at `META-INF/tamaya-config.xml` you simply -- call +MetaConfig.configure();+. This will read the meta-configuration and -- configure Tamaya's _default_ configuration. Alternatively you can choose your own -- metaconfiguration location by passing an alternate `URL` ro read from. --* With +MetaConfiguration.createContextBuilder()+ you can stop a step earlier: a new -- instance of +ConfigBuilder+ is created and configured with all the -- entries found in your meta-configuration. Also here you can optionally pass your -- custom location for the meta-configuration resouce. --* Finally +MetaConfig.createConfig(URL)+ allows you to create an -- arbitrary +Config+ instance using a meta-configuration file. The `Config` -- instance is completely independent and not registered as _default_ configuration, so -- it's lifecycle and usage is completely under your control. -- -- --=== MetaContext -- --When thinking what are the various input parameters for determining a correct configuration, there --might be different things relevant in different scenarios, especially for developers in different --companies. A good example of such an input parameter is the current `STAGE`. All these kinf od inputs --can be summarized in some sort of meta-configuration, commonly known as a _context_. So --the metamodel extension ships with a +MetaContext+ class that allows to define a common meta-context, --that can be accessed by components as needed to determine the correct settings to be applied: -- --[source, java) ------------------------------------------------- --public final class MetaContext { -- -- ... -- -- public static MetaContext getInstance(String contextName); -- -- /** -- * Access the default context. Contexts are managed as weak references in this class. If no -- * such context exists, a new instance is created. -- * @return the context instance, never null. -- */ -- public static MetaContext getDefaultInstance(); -- -- /** -- * Access a context by name. Contexts are managed as weak references in this class. If no -- * such valid context exists, a new instance is created, using the given {@code validSupplier}. -- * @param contextName the context name, not null. -- * @return the context instance, never null. -- */ -- public static MetaContext getInstance(String contextName, Supplier<Boolean> validSupplier); -- -- /** -- * Access the thread-based context. If no such context -- * exists a new one will be created. -- * @param reinit if true, clear's the thread's context. -- * @return the corresponding context, never null. -- */ -- public static MetaContext getThreadInstance(boolean reinit); -- -- /** -- * Access the current context, which actually is the current context, combined with the thread based -- * context (overriding). -- * @return the corresponding context, never null. -- */ -- public MetaContext getCurrentInstance(); -- -- /** -- * Access the current context, which actually is the current context, combined with the thread based -- * context (overriding). -- * @param reinit if true, clear's the thread's context. -- * @return the corresponding context, never null. -- */ -- public MetaContext getCurrentInstance(boolean reinit); -- -- -- /** -- * Method to evaluate if a context is valid. This basically depends on the -- * {@code validSupplier}, if any is set. If no supplier is present the context is valid. -- * -- * @return true, if this context is valid. -- */ -- public boolean isValid(); -- -- /** -- * Combine this context with the other contexts given, hereby only contexts are included -- * which are {@code valid}, see {@link #isValid()}. -- * @param contexts the context to merge with this context. -- * @return the newly created Context. -- */ -- public MetaContext combineWith(MetaContext... contexts); -- -- /** -- * Access the given context property. -- * @param key the key, not null -- * @return the value, or null. -- */ -- public String getProperty(String key); -- -- /** -- * Access the given context property. -- * @param key the key, not the default value. -- * @param defaultValue the default value to be returned, if no value is defined, or the -- * stored value's TTL has been reached. -- * @return the value, default value or null. -- */ -- public String getProperty(String key, String defaultValue); -- -- /** -- * Sets the given context property. -- * @param key the key, not null. -- * @param value the value, not null. -- * @return the porevious value, or null. -- */ -- public String setProperty(String key, String value); -- -- /** -- * Sets the given context property. -- * @param key the key, not null. -- * @param value the value, not null. -- * @param ttl the time to live. Zero or less than zero means, no timeout. -- * @param unit the target time unit. -- * @return the porevious value, or null. -- */ -- public String setProperty(String key, String value, int ttl, TimeUnit unit); -- -- /** -- * Sets the given property unless there is already a value defined. -- * @param key the key, not null. -- * @param value the value, not null. -- */ -- public void setPropertyIfAbsent(String key, String value); -- -- /** -- * Sets the given property unless there is already a value defined. -- * @param key the key, not null. -- * @param value the value, not null. -- * @param ttl the time to live. Zero or less than zero means, no timeout. -- * @param unit the target time unit. -- */ -- public void setPropertyIfAbsent(String key, String value, long ttl, TimeUnit unit); -- -- /** -- * Adds all properties given, overriding any existing properties. -- * @param properties the properties, not null. -- */ -- public void setProperties(Map<String,String> properties); -- -- /** -- * Adds all properties given, overriding any existing properties. -- * @param properties the properties, not null. -- * @param ttl the time to live. Zero or less than zero means, no timeout. -- * @param unit the target time unit. -- */ -- public void setProperties(Map<String,String> properties, long ttl, TimeUnit unit); -- -- /** -- * Checks if all the given properties are present. -- * @param keys the keys to check, not null. -- * @return true, if all the given keys are existing. -- */ -- public boolean checkProperties(String... keys); -- -- /** -- * Access all the current context properties. -- * @return the properties, never null. -- */ -- public Map<String,String> getProperties(); --} ------------------------------------------------- -- --As you see, a +MetaContext+ has the following aspects: -- --* there are multiple context's possible, identified by their name. --* Accessing an instance that does not yet exist, will create a new one. --* there is one shared _default_ instance. --* they store ordinary `String,String` key, value pairs. --* they can be _combined_ into a overriging hierarchy --* accessing the _default_ MetaContext returns the global instance combined with -- a threaded override instance. Passing `reinit` will clear the thread instance's -- data. -- -- --==== Configuring MetaContexts -- --`MetaContext` instances can be configured in the _meta-configuration_ in the first --`meta-context` section as illustrated below: -- --[source, xml] ------------------------------------------------- --<!-- Configuring the default context --> --<context> -- <context-entry name="stage">${properties:system:STAGE?default=DEV}</context-entry> -- <context-entry name="configdir">${properties:system:configdir?default=.}</context-entry> -- <context-entry name="app">${properties:system.APP?default=NONE}</context-entry> -- <context-entry name="context">${java:org.apache.tamaya.context.Context#id()}</context-entry> -- <context-entry name="company">Trivadis</context-entry> -- <context-entry name="default-formats">yaml,json</context-entry> -- <context-entry name="default-refresh-period">5 SECOND</context-entry> --</context> --<!-- Configuring a context named 'APP' --> --<context name="APP"> -- <context-entry name="application">someAppName</context-entry> --</context> ------------------------------------------------- -- --As shown above multiple contexts can be configured. Keys and values are of type `String`. -- -- --===== Using Expressions -- --As shown before, it is possible to add simple expressions, enclosed in `${}`. Hereby the --contents must be formatted as `evaluator:expression`, which then internally must be interpreted by --the +org.apache.tamaya.metamodel.internal.SimpleResolver+, which effectively reads and --applied context entries. -- --Currently the following placeholders for context entries are provided: -- --* properties - mapping to system properties (`properties:sys:KEY`) or -- environment properties (`properties:env:KEY`) or other MetaContext -- entries initialized already (`properties:ctx[:CTXNAME]:KEY`) --* java - mapping to a static method or field, returning a `String` value. -- -- --=== General Extensions -- --Working with meta-models requires additional aspects to be generalized to separate --concerns and reuse some of the common functionality. These concepts are shown in the following --subsections. -- --=== Enabled -- --Things can be dynamically enabled or disabled, e.g. based on context. This can be --modelled by the +Enabled+ interface: -- --[source, java] ------------------------------------------------- --public interface Enabled { -- -- /** -- * Returns the enabled property. -- * @return the enabled value. -- */ -- boolean isEnabled(); -- -- /** -- * Enables/disables this property source. -- * @param enabled the enabled value. -- */ -- void setEnabled(boolean enabled); --} ------------------------------------------------- -- --+Enabled+ can be used as a mixin-logic, e.g. for decorating property sources, --property source providers, filters and converters. The decorator can also, if not --set explicitly, evaluate the _enabled_ property based on the current runtime --context. -- -- --=== Refreshable -- --Similar to _Enabled_ things can also be refreshable. -- --[source, java] ------------------------------------------------- --public interface Refreshable { -- -- /** -- * Refreshes the given instance. -- */ -- void refresh(); --} ------------------------------------------------- -- --This can be used to define a common API for refreshing artifctas. Similar to --_Enabled_ this can be applied as a decorator/mix-in interface to property --sources and property source providers. This property also is supported in the --XML metaconfiguration, e.g. -- --[source, xml] ------------------------------------------------- --<sources> -- <source type="file" refreshable="true"> -- <name>config.json</name> -- <param name="location">config.json</param> -- </source> --</sources> ------------------------------------------------- -- -- --=== The MetaConfiguration XML Structure -- --In general the `tamaya-config.xml` file does never apply an XML schema or --similar. Nevertheless there is a common DSL structure, which can be extended --as well (see next chapter). -- --[source, xml] ------------------------------------------------- --<configuration> -- <!-- PART ONE: Contexts initialization. --> -- <context> -- <context-entry name="stage">${properties:system:STAGE?default=DEV}</context-entry> -- <context-entry name="configdir">${properties:system:configdir?default=.}</context-entry> -- ... -- </context> -- <context name="APP"> -- <context-entry name="application">someAppName</context-entry> -- </context> -- -- <!-- PART TWO: Global settings of ConfigurationContext. --> -- <!-- combinationPolicy type="" / --> -- -- <!-- PART THREE: Configuration definition. --> -- -- <sources> -- <source enabled="${stage=TEST || stage=PTA || stage=PROD}" -- type="env-properties"> -- <filter type="PropertyMapping"> -- <param name="mapTarget">ENV.</param> -- </filter> -- <filter type="AccessMask"> -- <param name="roles">admin,power-user</param> -- <param name="policy">mask</param> -- <param name="mask">*****</param> -- <param name="matchExpression">SEC_</param> -- </filter> -- </source> -- <source type="sys-properties" > -- <filter type="ImmutablePropertySource" /> -- </source> -- <source type="file" refreshable="true"> -- <name>config.json</name> -- <param name="location">config.json</param> -- </source> -- <source type="file" refreshable="true"> -- <name>config.xml</name> -- <param name="location">config.xml</param> -- <param name="formats">xml-properties</param> -- </source> -- <source-provider type="resource"> -- <name>classpath:application-config.yml</name> -- <param name="location">/META-INF/application-config.yml</param> -- </source-provider> -- <source type="ch.mypack.MyClassSource" /> -- <!--<include enabled="${stage==TEST}">TEST-config.xml</include>--> -- <source-provider type="resource" enabled="${configdir != null}"> -- <name>config-dir</name> -- <param name="location">/${configdir}/**/*.json</param> -- </source-provider> -- <source type="url" refreshable="true"> -- <name>remote</name> -- <param name="location">https://www.confdrive.com/cfg/customerId=1234</param> -- <param name="formats">json</param> -- <filter type="CachedPropertySource"> -- <param name="ttl">30 SECOND</param> -- </filter> -- </source> -- </sources> -- <filters> -- <filter type="UsageTrackerFilter"/> -- <filter type="AccessControl"> -- <param name="roles">admin,power-user</param> -- <param name="policy">hide</param> -- <param name="expression">*.secret</param> -- </filter> -- <filter type="Cache"> -- <param name="ttl">30000</param> -- <param name="expression">cached.*</param> -- </filter> -- </filters> -- <converters> -- <!--<converter type="AllInOneConverter"/>--> -- <default-converters/> -- </converters> --</configuration> ------------------------------------------------- -- --The different parts in fact are not hardcoded, but implemented --as independent components, where each of them gets access to the --XML DOM tree to read the configuration aspects of interest. --Instances related must implement the ++ interface and register it to --the `ServiceContext`. Reading order is mapped using `@Priority` --annotations. --For further details refer to the SPI section in this document. -- -- --== Model SPI -- --=== Extending the XML DSL -- --The XML DSL can be extended in various ways: -- --* Basically adding a new feature maps to adding a new section to the -- meta-config XML. This can be easily done, by implementing +MetaConfigurationReader+ -- and do whatever is appropriate for your use case. --* For adding new expression capabilities for `MetaContext`entries +SimpleResolver+ must -- be implemented. --* For allowing customized parameterization of artifacts, e.g. property sources, -- property source providers, converters and filters etc. you may implement +ItemFactory+ -- instances. -- --=== MetaConfigurationReader -- --XML metaconfiguration is effectively processed by instances of --type +org.apache.tamaya.metamodel.spi.MetaConfigurationReader+: -- --[source,java] ------------------------------------------------------------- --public interface MetaConfigReader { -- -- /** -- * Reads meta-configuration from the given document and configures the current -- * context builder. The priority of readers is determined by the priorization policy -- * implemented by the {@link org.apache.tamaya.spi.ServiceContext}, -- * @param document the meta-configuration document -- * @param configBuilder the config builder to use. -- */ -- void read(Document document, ConfigBuilder configBuilder); -- -- } ------------------------------------------------------------- -- --Hereby we also see that an instance of `ConfigBuilder` is passed. --Remember, we mentioned earlier that meta-configuration basically is a XML --API to the building a configuration using a +ConfigBuilder+. So --all you can do with the meta-config XML can also be done programmatically using --the Java API. -- --This module provides instances of this class for reading of meta-context, --property-sources, property source providers, converters, filters and more. --Look into the +org.apache.tamaya.metamodel.internal+ package for further details. -- --New instances implementing this interface must be registered into the current --+ServiceContext+, by default the +ServiceLoader+ is used. -- -- --=== ItemFactory -- --Instances of +ItemFactory+ allow to configure artifacts using XML data: -- --[source, java] ------------------------------------------------------------- --public interface ItemFactory<T> { -- -- /** -- * Get the factory name. -- * @return the factory name, not null. -- */ -- String getName(); -- -- /** -- * Create a new instance. -- * @param parameters the parameters for configuring the instance. -- * @return the new instance, not null. -- */ -- T create(Map<String,String> parameters); -- -- /** -- * Get the target type created by this factory. This can be used to -- * assign the factory to an acording item base type, e.g. a PropertySource, -- * PropertySourceProvider, PropertyFilter etc. -- * @return the target type, not null. -- */ -- Class<? extends T> getArea(); -- --} ------------------------------------------------------------- -- --The factory's name hereby is used as a short cut, e.g. have a look at the following --XML snippet defining a `PropertySource` to be added: -- --[source, xml] ------------------------------------------------------------- --<source type="file" refreshable="true"> -- <name>config.json</name> -- <param name="location">config.json</param> --</source> ------------------------------------------------------------- -- --In the above snippet _file_ equals to the factory name, which provides the user --a simple to use short name, instead of adding the fully qualified classname --(which is always possible). -- --The _location_ paramter with its value is passed as `Map` to the `create` method. -- -- --=== ItemFactoryManager -- --This singleton class manages the _ItemFactory_ instances found, hereby allowing --accessing and registering instances. This singleton is actually used by the --component parsers (type `MetaConfigurationReader`). -- --[source, java] ------------------------------------------------------------- --public final class ItemFactoryManager { -- -- ... -- -- public static ItemFactoryManager getInstance(); -- -- public <T> List<ItemFactory<T>> getFactories(Class<T> type); -- public <T> ItemFactory<T> getFactory(Class<T> type, String id); -- -- public <T> void registerItemFactory(ItemFactory<T> factory); -- --} ------------------------------------------------------------- -- -- --=== Extended Implementations -- --The package +org.apache.tamaya.metamodel.ext+ contains a few useful --implementations that also can be used in your meta-configuration and --show how mixin-functionality can be added without touching property source --implementations. -- --As of now the package contains -- --* +EnabledPropertySource+: a decorator for a `PropertySource` -- adding the capability to _enable/disable_ the property source. --* +EnabledPropertySourceProvider+ a decorator for a `PropertySourceProvider` -- adding the capability to _enable/disable_ the property source provider. --* +RefreshablePropertySource+: a decorator for a `PropertySource` -- adding the capability to _refresh_ the property source. --* +EnabledPropertySourceProvider+ a decorator for a `PropertySourceProvider` -- adding the capability to _refresh_ the property source provider. -- --Not yet implemented but planned are implementations to add the following --functionality: -- --* _caching_ of entries for a given time. --* _immutability_ of entries, so a configuration data (or parts of it) will -- never change later. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_mutable_config.adoc ---------------------------------------------------------------------- diff --cc content/documentation-new/extensions/mod_mutable_config.adoc index 478acee,478acee..0000000 deleted file mode 100644,100644 --- a/content/documentation-new/extensions/mod_mutable_config.adoc +++ /dev/null @@@ -1,236 -1,236 +1,0 @@@ --:jbake-type: page --:jbake-status: published -- --= Apache Tamaya - Extension: Mutable Configuration -- --toc::[] -- -- --[[MutableConfiguration]] --== Tamaya Mutable Configuration (Extension Module) -- --Tamaya _Mutable Configuration_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. -- -- --=== What functionality this module provides ? -- --+Config+ instances by default are read-only, which covers must of the use cases. But there are many legit scenarios --where configuration should be written back to backend systems or the local file system. This module adds this --functionality. -- -- --=== Compatibility -- --The module is based on Java 8, so it can be used with Java 8 and beyond. -- -- --=== Installation -- --To benefit from configuration mutability support you only must add the corresponding dependency to your module: -- --[source, xml] ------------------------------------------------- --<dependency> -- <groupId>org.apache.tamaya.ext</groupId> -- <artifactId>tamaya-mutable-config</artifactId> -- <version>{tamaya_version}</version> --</dependency> ------------------------------------------------- -- -- --=== Core Architecture -- --==== Accessing MutableConfig -- --The core of the module is the +MutableConfigProider+ singleton, which provides access to +MutableConfig+ --instance, which extends +Config+. This interface adds additional methods to add/update or remove property values. --Hereby each +MutableConfig+ manages a transaction like context, which includes --a UUID that identifes a change. --Backends for writing changes applied umst implement +MutableConfigSource+, which extends +ConfigSource+. --Registrations and ordering policies are exact the same as with ordinary config sources, but --mutable property sources can be targeted by config write operations. -- --The example below shows how a +MutableConfig+ can be obtained ,values added, removed and --finally changes written back to the backend: -- --[source,java] --.Accessing and changing configuration ---------------------------------------------- --MutableConfig config = MutableConfigProvider -- .createMutableConfig(); --config.put("newKey", "newValue") -- .put("anotherKey", "updatedValue") -- .remove("valueNotValid") -- .store(); ---------------------------------------------- -- --In the above scenario we use the system's _default_ configuration as the backend to be used. --We can also pass any +Config+ to render it into a mutable instance, e.g. -- --[source,java] --.Explicitly passing the backing configuration ---------------------------------------------- --Config config = ...; --MutableConfig config = MutableConfigProvider -- .createMutableConfig(config); ---------------------------------------------- -- --NOTE: If a configuration does not contain any +MutableConfigSource+ instances, -- a +IllegalArgumentException+ is thrown since it would not be able to accept -- any changes. -- -- --Following we show the possible methods you can use to create a +MutableConfig+. --We will show in the following sections more details on the options provided... -- --[source, java] ----------------------------------------------- --public final class MutableConfigProvider { -- -- private MutableConfigProvider(){} -- -- public static MutableConfig createMutableConfig(); -- public static MutableConfig createMutableConfig( -- ChangePropagationPolicy changePropgationPolicy); -- public static MutableConfig createMutableConfig(Config configuration); -- public static MutableConfig createMutableConfig( -- Config configuration, -- ChangePropagationPolicy changePropgationPolicy); -- -- [...] --} ----------------------------------------------- -- --As we have not yet shown it, +MutableConfiguration+ is defined as follows: -- --[source, java] ----------------------------------------------- --public interface MutableConfig extends Config { -- -- void store(); -- -- ConfigChangeRequest getConfigChangeRequest(); -- ChangePropagationPolicy getChangePropagationPolicy(); -- -- MutableConfig put(String key, String value); -- MutableConfig putAll(Map<String, String> properties); -- MutableConfig remove(Collection<String> keys); -- MutableConfig remove(String... keys); -- --} ----------------------------------------------- -- -- --===== Targeting specific MutableConfigSources -- --A +Config+ may have multiple +MutableConfigSource+ instances present. These are members of Tamaya's ordered list of --+ConfigSources+ to evaluate the configuration. Nevertheless writing back changes requires additional aspects to --be considered: --* Should changes written target all mutable config sources? Or should a change only -- target the most significant instance (hereby not writing the change to less significant config sources)? --* Or should a change be applied only to specific mutable config source(s), regardless its position in the -- processing chain? -- --Therefore a _default_ +ChangePropagationPolicy+ can be applied on a +MutableConfig+ instance, which allows to --control this aspect: -- --[source,java] --.Explicitly passing the backing configuration ---------------------------------------------- --public interface ChangePropagationPolicy { -- /** -- * Method being called when a multiple key/value pairs are added or updated. -- * @param configSources all config sources, including read-only config sources, of the current configuration, -- * never null. -- * @param configChange the configuration change, not null. -- */ -- void applyChange(ConfigChangeRequest configChange, Collection<ConfigSource> configSources); --} ---------------------------------------------- -- --By default, changes are applied to all registered +MutableConfigSource+ instances --similarly. -- --The +MutableConfigProvider+ singleton also provides the most common --change propagation policy implementations: -- --[source, java] ----------------------------------------------- --public final class MutableConfigProvider { -- -- [...] -- -- public static ChangePropagationPolicy getApplyAllChangePolicy(); -- public static ChangePropagationPolicy getApplyMostSignificantOnlyChangePolicy(); -- public static ChangePropagationPolicy getApplySelectiveChangePolicy(String... propertySourceNames); -- public static ChangePropagationPolicy getApplyNonePolicy(); --} ----------------------------------------------- -- -- --==== Some Aspects to consider -- --Due to Tamaya's design the effective effect of your changes to the overall configuration, cannot --be sometimes a bit tricky to be predicted, since it depends on several aspects: -- --. is the corresponding configuration resource configured as part of the current system's configuration? --. what is the +PropertySource's+ priority within the configuration context? Is it overriding or overridden -- by other sources? --. is the change directly visible to the configuration system? E.g. injected values are normally not updated, -- whereas injecting a +DynamicValue<T>+ instance allows to detect and react single value changes. Also the -- +PropertySources+ implementation must be able to detect any configuration changes and adapt its values returned -- accordingly. Finally values also can be marked as immutable or being cached. --. Is configuration cached, or written/collected directly on access? --. can the changes applied be committed at all? -- --So it is part of your application configuration design to clearly define, which property sources may be read-only, which --may be mutable, how overriding should work and to which backends finally any changes should be written back. -- -- --=== Configuration Changes -- --This module does not handle detection of changes to the overall system's +Config+. This can be done in --several ways, e.g. by: -- --* using the _tamaya-events_ extension, which can be used to observe the system's configuration and -- publishing events when things have been changed. --* The SPI implementing the +MutableConfigBackendSpi+ may inform/update any affected +ConfigSource, -- ConfigSourceProvider+ instances about the changes applied. -- -- --=== Supported Backends -- --Multiple backends are supported. E.g. _tamaya-etcd_ also registers --corresponding SPI implementations/backends. This module comes with --the following +MutableConfigSource+ implementations: -- --* +MutablePropertiesConfigSource+ resources, targeting local +.properties+ files, using the +java.util.Properties+ -- format. --* +MutableXmlPropertiesConfigSource+ resources, targeting local +.xml+ property files, using the +java.util.Properties+ -- XML format. -- -- --=== SPIs -- --The module defines +MutableConfigProviderSpi+, that is used as a delegate by the +MutableConfigProvider+ --singleton accessor: -- --[source,java] --.SPI: MutableConfigurationProviderSpi ---------------------------------------------------- --public interface MutableConfigProviderSpi { -- /** -- * Creates a new {@link MutableConfig} with {@code autoCommit = false} as default. -- * -- * @param configuration the configuration, not null. -- * @param propagationPolicy policy that defines how changes are published to the property -- * sources. -- * @return a new mutable configuration instance. -- */ -- MutableConfig createMutableConfig(Config configuration, -- ChangePropagationPolicy propagationPolicy); --} ---------------------------------------------------- -- --Implementations are registered with the current +ServiceContext+ (using by default the -- +java.util.ServiceLoader+ service). http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_optional.adoc ---------------------------------------------------------------------- diff --cc content/documentation-new/extensions/mod_optional.adoc index 29ed2fc,29ed2fc..0000000 deleted file mode 100644,100644 --- a/content/documentation-new/extensions/mod_optional.adoc +++ /dev/null @@@ -1,61 -1,61 +1,0 @@@ --:jbake-type: page --:jbake-status: published -- --= Apache Tamaya - Extension: Optional Tamaya Configuration -- --toc::[] -- -- --[[Optional]] --== Tamaya Optional (Extension Module) -- --Tamaya _Optional_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. -- --=== What functionality this module provides ? -- --Tamaya _Optional_ is for projects that want to benefit from Tamaya configuration optionally only. --E.g. doing an OSS project you can declare to support configuration with Tamaya as --an optional extension. This module can be added as a hard dependency to your code, hereby adding only --three artifacts. The _optional_ module automatically checks the availability of Tamaya on the --classpath and only if available it tries to access it for configuration evaluation. --Additionally an +EvaluationPolicy+ lets you define the precedence of configured values --(yours, or Tamaya ones, if present). -- -- --=== Compatibility -- --The module is based on Java 8, so it will not run on Java 8 and beyond. -- -- --=== Installation -- --To use Tamaya _optional_ you only must add the corresponding dependency to your module: -- --[source, xml] ------------------------------------------------- --<dependency> -- <groupId>org.apache.tamaya.ext</groupId> -- <artifactId>tamaya-optional</artifactId> -- <version>{tamaya_version}</version> --</dependency> ------------------------------------------------- -- -- --=== Reading configuration using the Tamaya Optional Module -- --Tamaya _Optional_ allows reading configuration with a small subset of functionality only. For more -- advanced use cases consider using the Apache Tamaya as your main configuration API. When -- creating your +OptionalConfiguration+ instance you also pass the logic to access a value -- with your own configuration logic. Tamaya Optional will delegate to your logic as needed -- (depending on the `EvaluationPolicy`). -- --[source, java] ------------------------------------------------- --BigDecimal interestRate = -- OptionalConfiguration.of( -- EvaluationPolicy.TAMAYA_OVERRIDES_OTHER, -- (k) -> MyConfigMechanism.get(k) // String get(String key); -- ) -- .get("com.mycomp.ratecalculator.rate", BigDecimal.class)) -- .orElse(BigDecimal.of(0.05d)); ------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_osgi.adoc ---------------------------------------------------------------------- diff --cc content/documentation-new/extensions/mod_osgi.adoc index d075ac1,d075ac1..0000000 deleted file mode 100644,100644 --- a/content/documentation-new/extensions/mod_osgi.adoc +++ /dev/null @@@ -1,814 -1,814 +1,0 @@@ --:jbake-type: page --:jbake-status: published -- --= Apache Tamaya - Extensions: OSGI Integration -- --toc::[] -- -- --[[OSGI]] --== Tamaya OSGI Support -- --Tamaya _OSGI_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. -- -- --=== What functionality this module provides ? -- --Tamaya _OSGI_ provides support for integration with OSGI. Hereby Tamaya does actively override or extend the OSGI --+ConfigAdmin+ based configuration with entries stored and managed by Tamaya. Tamaya provides also shell extensions --to enable/perform configuration loading and restoring actions. --Optionally Tamaya also provides extension for automatically trigger configuration updates, when configuration has --been changed and configuration injection using Tamaya's injection API. -- -- --=== Compatibility -- --All module described are based on Java 8, so it will run on Java 8 and beyond. --The modules are built against *OSGI Compendium version 5.0*. Tamaya OSGI support --is tested against the following OSGI runtimes: -- --* Apache Karaf, version 4.0.7 --* Apache Felix, version 5.6.1 --* Eclipse Equinox, version x.x.x. -- -- --=== Installation -- --To benefit from Tamaya in an OSGI context you must deploy at least the following modules to --your OSGI runtime environment: -- --[source, listing] ------------------------------------------------- --# Runtime with OSGI ConfigAdmin support, e.g. --org.apache.felix:org.apache.felix.configadmin:{felix_version} --# API and core --org.apache.geronimo.specs:geronimo-annotation_1.2_spec:1.0 --org.apache.tamaya:tamaya-api:{tamaya_version} --org.apache.tamaya:tamaya-spisupport:{tamaya_version} --org.apache.tamaya:tamaya-core:{tamaya_version} --# Required extensions --org.apache.tamaya.ext:tamaya-functions:{tamaya_version} --org.apache.tamaya.ext:tamaya-osgi:{tamaya_version} ------------------------------------------------- -- -- --=== Tamaya Service Loading in OSGI -- --Important to know is that within OSGI class- and resource loading is not compatible with standard Java SE. Also --in OSGI, bundles can be loaded or unloaded at any time, so Tamaya's logic must cope with this as well. --These constraints are handled by Tamaya (implemented in +tamaya-core+ and +tamaya-osgi+) as follows: -- --* Tamaya registers a +OSGIServiceContext+ which reads all +java.util.ServiceLoader+ configurations and -- registers them as OSGI services. Hereby integration is two-way: The core module contains an -- OSGI +Activator+ that replaces Tamaya's default +ServiceContext+ with an OSGI based implementation that -- will consume all services from the OSGI service API. Consequently you can also register Tamaya extensions -- as OSGI services using standard OSGI tooling (e.g. your own +PropertySource+ instances). Tamaya hereby -- also does not store any service references, so the dynamic nature of OSGI is fully honored. --* Tamaya's +ServiceContext+ SPI does additionally provide functionality for loading of (classpath) -- resources using the bundle's +getEntry(String)+ method. --* Tamaya similarly checks the classpath of all bundles for Tamaya SPI services to be registered thus -- implementing the +ServiceLoader+ logic in OSGI. Hereby Tamaya will only register services with the -- +org.apache.tamaya+ as root package. -- --NOTE: Tamaya actually does not replace any existing +ConfigAdmin+ component, Tamaya modifies any existing OSGI -- configuration on changes detected and stores backups of any OSGI configuration before applying any -- changes. -- --=== Configuring Bundles --==== Mapping of pids and factoryPids -- --When accessing configuration from the OSGI +ConfigAdmin+ a pid and an optional location can be provided. --Tamaya requires all configuration for a PID to be located in keys starting [PID]: -- --[source, listing] --.OSGI pid mapping ------------------------------------------------- --# OSGI settings --pid=myBundle --key=common.net.port -- --# Corresponding key in Tamaya configuration --[myBundle]key=common.net.port ------------------------------------------------- -- --==== Enabling/Disabling Tamaya -- --By default, Tamaya doesn't do anything, unless it is told to so so. So having installed the Tamaya OSGI plugin, --you will see the bundles are loaded, but your OSGI environment still works the same. This is not accidentally, since --configuration is a crucial part. This means Tamaya, by default, is disabled for all bundles. You have now several --options to enabled Tamaya: -- --* you can enable Tamaya for *all* bundles by default by -- ** setting the +-Dtamaya-enabled=true+ system property. -- ** by setting +tamaya-enabled=true+ in the OSGI Configuration for the PID +TamayaConfigPlugin+. --* you can enable Tamaya for a single bundle by -- ** by setting +tamaya-enabled=true+ in the OSGI Configuration for the given bundle. -- ** by adding +Tamaya-Enabled: true+ to the bundle's MANIFEST. -- --Similarly you can also combine these options the other way round: -- --* You can enable Tamaya by default as shown above. --* You can disable Tamaya for bundles by -- ** by setting +tamaya-enabled=false+ in the OSGI Configuration for the given bundle. -- ** by adding +Tamaya-Enabled: false+ to the bundle's MANIFEST. -- -- --==== Controlling How Tamaya changes your OSGI Configuration -- --Tamaya supports different policies that define how Tamaya is changing the OSGI configuration: -- --* *EXTEND*: Only add properties not existing in the OSGI configuration, but never override -- or remove existing properties. --* *OVERRIDE*: Override existing properties and also add new properties. --* *UPDATE_ONLY*: Only override existing properties but do not add any properties. -- --By default, Tamaya uses the _OVERRIDE_ policy. Also this policy can be configured in several --ways and with different scopes: -- --* You can define the _default_ policy applied, by -- ** setting the +-Dtamaya-policy=POLICY+ system property. -- ** by setting +tamaya-policy=POLICY+ in the OSGI Configuration for the PID +TamayaConfigPlugin+. -- --Hereby, _POLICY_ must be one of +OVERRIDE, EXTEND, UPDATE_ONLY+. -- --* You can also configure the policy individually for a bundle by -- ** by setting +tamaya-policy=POLICY+ in the OSGI Configuration for the given bundle. -- ** by adding +Tamaya-Policy: POLICY+ to the bundle's MANIFEST. -- --==== Mapping OSGI PIDs to Tamaya Configuration -- --Tamaya configuration is a single +Map<String,String> with String keys and String values. Whereas OSGI configuration are --multiple +Dictionary<String,?>+ (for several PIDs). The Tamaya OSGI extension implements the following mapping: -- --As an example refer to the followinf Tamaya configuration entries: -- --[source, listing] --.Tamaya configuration for PID 'MyPlugin' ------------------------------------------------- --[MyPlugin]ch.base.pack.Main.customer=Native Inc --[MyPlugin]ch.base.pack.Main.use=234 --[MyPlugin]ch.base.pack.Main.encoding=UTF-8 ------------------------------------------------- -- --The OSGI Configuration Plugin now provides the following configuration for PID: -- --[source, listing] --.OSGI configuration for PID 'MyPlugin' ------------------------------------------------- --ch.base.pack.Main.use=100 (Integer) --ch.base.pack.Main.switch=on (Boolean) --ch.base.pack.Main.customer=NONE (String) ------------------------------------------------- -- --Now using +Policy.OVERRIDE+ (as desribed in the previous section), Tamaya will change the OSGI configuration --as follows: -- --[source, listing] --.OSGI configuration after Tamaya update for PID 'MyPlugin' ------------------------------------------------- --ch.base.pack.Main.use=234 (Integer) --ch.base.pack.Main.switch=on (Boolean) --ch.base.pack.Main.customer=Native Inc (String) --[MyPlugin]ch.base.pack.Main.encoding=UTF-8 (String) ------------------------------------------------- -- --So Tamaya configuration mapping can be summarized as follows: -- --* The OSGI PID is mapped to a Tamaya prefix +[PID]+. --* The OSGI keys are the exact same keys as from Tamaya with the _[PID]_ prefix removed. --* New entries are added (depending on the +Policy+) as +String+ values. --* Types of existing entries are preserved on update (this requires the Tamaya entries to be convertable into -- the required target types. Refer to Tamaya's core documentation for supported types and how -- to add custom converters). -- --Finally, the mapping of the OSGI _PID_ to the Tamaya _[PID]_ prefix also can be customized by -- --* adding +tamaya-config-root+ as an OSGI configuration property to the OSGI configuration. --* adding +Tamaya-Config-Root+ as a MANIFEST entry to the bundle. -- --The root will replace the default _[PID]_ prefix with the value configured. -- --==== OSGI Configuration Backup -- --Before Tamaya changes any OSGI configuration it creates a _Backup_ of the existing OSGI --configuration dictionary and stores it in serialized form in the plugin's OSGI configuration. --This allows you to restore the original OSGI configuration in case of problems. Hereby Tamaya --automatically sets the +tamaya-enabled=false+ property to disable Tamaya for the given --configuration (bundle). -- --The history can be accessed from the Tamaya Configuration Plugin Service --(shown later). -- --==== OSGI Configuration Change Log -- --All changes applied by Tamaya are logged as well using --+ConfigHistory+ entry items. The history can be accessed from the Tamaya Configuration Plugin Service --(shown later): -- --[source, Java] --.OSGI ConfigHistory Entry ------------------------------------------------- --public final class ConfigHistory implements Serializable{ -- -- [...] -- -- public enum TaskType{ -- PROPERTY, -- BEGIN, -- END, -- } -- -- // *** -- // Entry = attributes -- // *** -- -- public TaskType getArea(){...} -- -- public String getPid() {... } -- -- public Object getPreviousValue() {... } -- -- public ConfigHistory setPreviousValue(Object previousValue) {... } -- -- public Object getValue() {...} -- -- public ConfigHistory setValue(Object value) {...} -- -- public String getKey() {...} -- -- public ConfigHistory setKey(String key) {...} -- --} ------------------------------------------------- -- --==== The Tamaya OSGI Configuration Service -- --As mentioned Tamaya exposes it's OSGI functionality, allowing programmatic access to Tamaya configuration --logic with the +TamayaConfigService+ OSGI service: -- --[source, Java] --.The exposed +TamayaConfigService+ ------------------------------------------------- --public interface TamayaConfigService{ -- /** The system/config property to set Tamaya's {@link Policy}. */ -- String TAMAYA_POLICY_PROP = "tamaya-policy"; -- /** The MANIFEST property to set Tamaya's {@link Policy}. */ -- String TAMAYA_POLICY_MANIFEST = "Tamaya-Policy"; -- /** The system/config property to define a customized Tamaya's configuration root, replacing the {@code [PID]} default -- * prefix used. */ -- String TAMAYA_CUSTOM_ROOT_PROP = "tamaya-config-root"; -- /** The MANIFEST property to define a customized Tamaya's configuration root, replacing the {@code [PID]} default -- * prefix used. */ -- String TAMAYA_CUSTOM_ROOT_MANIFEST = "Tamaya-Config-Root"; -- /** The system/config property to enable Tamaya. */ -- String TAMAYA_ENABLED_PROP = "tamaya-enabled"; -- /** The MANIFEST property to enable Tamaya. */ -- String TAMAYA_ENABLED_MANIFEST = "Tamaya-Enabled"; -- /** The system/config property to enable Tamaya automatic updates (requires Tamaya's Updater plugin to be loaded as well). */ -- String TAMAYA_AUTO_UPDATE_ENABLED_PROP = "tamaya-update-enabled"; -- /** The MANIFEST property to enable Tamaya automatic updates (requires Tamaya's Updater plugin to be loaded as well). */ -- String TAMAYA_AUTO_UPDATE_ENABLED_MANIFEST = "Tamaya-Update-Enabled"; -- -- /** -- * Enables/disables automatic updates (requires Tamaya's Updater plugin to be loaded as well). -- * @param enabled set to true to enable updates. -- */ -- void setAutoUpdateEnabled(boolean enabled); -- -- /** -- * Enables/disables Tamaya config by default. -- * @param enabled set to true to enable Tamaya for all bundles by default. -- */ -- void setTamayaEnabledByDefault(boolean enabled); -- -- /** -- * Get the flag, if Tamaya is enabled by default for all bundles. -- * @return true if Tamaya is enabled. -- */ -- boolean isTamayaEnabledByDefault(); -- -- /** -- * Get the default policy Tamaya is using for adapting OSGI configuration. -- * @return the default policy, never null. -- */ -- Policy getDefaultPolicy(); -- -- /** -- * Set the default policy Tamaya is using for adapting OSGI configuration. -- * @param policy the policy, not null. -- */ -- void setDefaultPolicy(Policy policy); -- -- /** -- * Updates the given OSGI configuration with Tamaya configuration. -- * @param pid the target PID, not null. -- * @return the new configuration. -- */ -- Dictionary<String,Object> updateConfig(String pid); -- -- /** -- * Updates the given OSGI configuration with Tamaya configuration. -- * @param pid the target PID, not null. -- * @param dryRun if true, the changes will not be applied to the OSGI configuration. -- * @return the configuration that would be applied, has been applied. -- */ -- Dictionary<String,Object> updateConfig(String pid, boolean dryRun); -- -- /** -- * Updates the given OSGI configuration with Tamaya configuration. -- * @param pid the target PID, not null. -- * @param policy the updating policy to be used, by default. -- * @param forcePolicy if set to true, the given policy will be used, even if an alternate policy is configured -- * for the given PID. -- * @param dryRun if true, the changes will not be applied to the OSGI configuration. -- * @return the configuration that would be applied, has been applied. -- */ -- Dictionary<String,Object> updateConfig(String pid, Policy policy, boolean forcePolicy, boolean dryRun); -- -- /** -- * Checks if a bundle is enabled for Tamaya configuration. -- * @param bundle the bundle, not null. -- * @return true, if the bundle is enabled. -- */ -- boolean isBundleEnabled(Bundle bundle); -- -- /** -- * Get the flag if automatic updates for config changes are enabled. -- * @return true, if automatic updates for config changes are enabled. -- */ -- boolean isAutoUpdateEnabled(); -- -- /** -- * Get the backup written for a PID. -- * @param pid the pid, not null. -- * @return the backup, or null, if no backup is present. -- */ -- Dictionary<String,?> getBackup(String pid); -- -- /** -- * Get all current known PIDs for which backups are registered. -- * @return all known PIDs for which backups are registered. -- */ -- Set<String> getBackupPids(); -- -- /** -- * Restores a backup, replacing the current OSGI configuration with the backup and -- * disabling Tamaya for this PID. -- * @param pid the PID, not null. -- * @return true, if a backup has been restored successfully. -- */ -- boolean restoreBackup(String pid); -- -- /** -- * Stores the current OSGI configuration as a backup (only if no backup is existing). -- * @param pid the target PID, not null. -- * @return true, if a backup has been stored successfully. -- */ -- boolean createBackup(String pid); -- -- /** -- * Deletes a backup, if existing. -- * @param pid the target PID, not null. -- * @return true, if a backup has been restored successfully. -- */ -- boolean deleteBackup(String pid); -- -- /** -- * Sets the maximum getHistory size. -- * @param maxHistory the max getHistory size. {@code 0} disables the getHistory function. -- */ -- void setMaxHistorySize(int maxHistory); -- -- /** -- * Get the max getHistory size. -- * @return the max getHistory size. {@code 0} means the getHistory function is disabled. -- */ -- int getMaxHistorySize(); -- -- /** -- * Access the current (full) change getHistory. -- * @return the current getHistory, never null. -- */ -- List<ConfigHistory> getHistory(); -- -- /** -- * Clears the getHistory. -- */ -- void clearHistory(); -- -- /** -- * Clears the getHistory for a PID. -- * @param pid the target PID, not null. -- */ -- void clearHistory(String pid); -- -- /** -- * Get the getHistory for a PID. -- * @param pid the target PID, not null. -- * @return the PID's getHistory, never null. -- */ -- List<ConfigHistory> getHistory(String pid); -- -- /** -- * Access the current OSGI configuration for a PID. -- * @param pid the target PID, not null. -- * @param section a subsection to be filter (using startsWith). -- * @return the (optionally filtered) OSGI configuration. -- */ -- Dictionary<String,Object> getOSGIConfiguration(String pid, String section); -- -- /** -- * Checks if a backup exists. -- * @param pid the target PID, not null. -- * @return true, if a backup exists. -- */ -- boolean containsBackup(String pid); --} ------------------------------------------------- -- -- --==== The Tamaya OSGI Configuration Service -- --Finally Tamaya also provides support for using Tamaya's injection API with your OSGI project. To enable injection --you must install a few additional bundles: -- --[source, xml] ------------------------------------------------- --<dependency> -- <groupId>org.apache.tamaya.ext</groupId> -- <artifactId>tamaya-osgi-injection</artifactId> -- <version>${tamaya.version}</version> --</dependency> --<dependency> -- <groupId>org.apache.tamaya.ext</groupId> -- <artifactId>tamaya-injection</artifactId> -- <version>${tamaya.version}</version> --</dependency> --<dependency> -- <groupId>org.apache.tamaya.ext</groupId> -- <artifactId>injection-api</artifactId> -- <version>${tamaya.version}</version> --</dependency> ------------------------------------------------- -- --Given that you can inject configuration entries -- --* on your services by -- ** setting +tamaya-config-inject=true+ in your service properties. -- ** setting +Tamaya-Config-Inject: true+ in your bundle's manifest. --* or by using the registered +ConfigInjectionService+: -- --[source, java] ------------------------------------------------- --public interface ConfigInjectionService { -- /** The manifest entry to enable Tamaya injection. */ -- String TAMAYA_INJECTION_ENABLED_MANIFEST = "Tamaya-Config-Inject"; -- /** The OSGI config entry to enable Tamaya injection. */ -- String TAMAYA_INJECTION_ENABLED_PROP = "tamaya-config-inject"; -- -- /** -- * Checks if injection is enabled on the given service. -- * @param reference the service reference, not null. -- * @return true, if enjection is enabled. -- */ -- boolean isInjectionEnabled(ServiceReference reference); -- -- /** -- * Checks if injection is enabled on the given service. -- * @param bundle the bundle, not null. -- * @return true, if enjection is enabled. -- */ -- boolean isInjectionEnabled(Bundle bundle); -- -- /** -- * Configures the passed instance. -- * @param instance the instance, not null. -- * @param <T> the input and return type. -- * @param pid the target PID, not null. -- * @param location the optional location -- * @return the configured instance. -- */ -- <T> T configure(String pid, String location, T instance); -- -- /** -- * Creates a suzpplier, which supplies events as created by the basic supplier, which are -- * automatically configured, when supplying. -- * @param supplier the base supplier, not null. -- * @param pid the target PID, not null. -- * @param location the optional location -- * @param <T> the type -- * @return a configuring supplier. -- */ -- <T> Supplier<T> getConfiguredSupplier(String pid, String location, java.util.function.Supplier<T> supplier); -- -- /** -- * Creates a template implementing the annotated methods based on current configuration data. -- * -- * @param <T> the type of the template. -- * @param templateType the type of the template to be created. -- * @param pid the target PID, not null. -- * @param location the optional location -- * @return the configured template. -- */ -- <T> T createTemplate(String pid, String location, Class<T> templateType); -- -- /** -- * Configures the passed instance. -- * @param instance the instance, not null. -- * @param <T> the input and return type. -- * @param bundle the target bundle, not null. -- * @return the configured instance. -- */ -- <T> T configure(Bundle bundle, T instance); -- -- /** -- * Creates a suzpplier, which supplies events as created by the basic supplier, which are -- * automatically configured, when supplying. -- * @param supplier the base supplier, not null. -- * @param bundle the target bundle, not null. -- * @param <T> the type -- * @return a configuring supplier. -- */ -- <T> Supplier<T> getConfiguredSupplier(Bundle bundle, java.util.function.Supplier<T> supplier); -- -- /** -- * Creates a template implementing the annotated methods based on current configuration data. -- * -- * @param <T> the type of the template. -- * @param templateType the type of the template to be created. -- * @param bundle the target bundle, not null. -- * @return the configured template. -- */ -- <T> T createTemplate(Bundle bundle, Class<T> templateType); --} ------------------------------------------------- -- --NOTE: Injection hereby is based on the OSGI ConfigAdmin values only. To use Tamaya configuration you have to additionally --install the Tamaya common OSGI support as described in the previous sections. -- --More details on Tamaya's injection API can be found in the corresponding link:mod_injection.html[API documentation]. -- --=== Special OSGI Platform support -- --==== Apache Karaf Shell -- --Apache Tamaya provides a Karaf Shell Extension providing commands for performing several actions related --to Tamaya configuration. To use them, simply add the +org.apache.tamaya.ext:tamaya-osgi-karaf-shell+ bundle --to your OSGI runtime. The extension will add the following commands to your Karaf conaole (with prefix +tamaya+): -- --[width="100%",frame="1",options="header",grid="all"] --|======= --|_Artifact_ |_Description_ |_Options_ -- --| +tm_apply_config+ --| Show the current Tamaya configuration. --| +++ --<pre> --<b>SYNTAX</b> --tamaya:tm_apply_config [options] pid --<b>ARGUMENTS</b> --<i>pid</i> The target OSGI component PID. --<b>OPTIONS</b> --<i>operationMode, -m, --opmode</i> Explicitly set (override) the operation mode to use. --<i>dryRun, -d, --dryrun</i> If set to true no OSGI configuration gets changed. --</pre> --+++ -- --| +tm_backup_create+ --| Creates a backup of a current OSGI configuration. --| +++ --<pre> --<b>SYNTAX</b> --tamaya:tm_backup_create [options] pid --<b>ARGUMENTS</b> --<i>pid</i> The target pid to backup. --<b>OPTIONS</b> --<i>--force, -f</i> Forces to (over)write a backup, even if one already exists. --</pre> --+++ -- --| +tm_backup_delete+ --| Deletes the OSGI configuration backup of Tamya. --| +++ --<pre> --<b>SYNTAX</b> --tamaya:tm_backup_delete pid --<b>ARGUMENTS</b> --<i>pid</i> Allows to filter on the given PID. '*' removes all backups. --</pre> --+++ -- --| +tm_backup_list+ --| List the backed-up OSGI configuration before Tamya applied changes. --| +++ --<pre> --<b>SYNTAX</b> --tamaya:tm_backup_list [pid] --<b>ARGUMENTS</b> --<i>pid</i> Allows to filter on the given PID. --</pre> --+++ -- --| +tm_backup_restore+ --| Restores the OSGI configuration backup of Tamya and disabled the PID for Tamaya configuration. --| +++ --<pre> --<b>SYNTAX</b> --tamaya:tm_backup_restore pid --<b>ARGUMENTS</b> --<i>pid</i> The target PID. '*' restores all backups. --</pre> --+++ -- --| +tm_config+ --| Show the current Tamaya configuration. --| +++ --<pre> --<b>SYNTAX</b> --tamaya:tm_config [options] --<b>OPTIONS</b> --<i>pi, -p, --pid</i> Apply filtering for the given OSGI component PID. --<i>section, -s, --section</i> A starting expression selecting the section to be filtered. --</pre> --+++ -- --| +tm_enable+ --| Enables or disable Tamaya by default for all bundles/services (default: enabled=false). Disabling still allows to explicitly enable -- bundles using 'tamaya-enable' manifest or OSGI config entries. --| +++ --<pre> --<b>SYNTAX</b> --tamaya:tm_enable enabled --<b>ARGUMENTS</b> --<i>enabled</i> The boolean value to enabled/disable Tamaya by default. --</pre> --+++ -- --| +tm_enabled+ --| Check if Tamaya is currently by default enabled for all bundles/services (default: enabled=false). If disabled still Tamaya allows to -- explicitly enable bundles using 'tamaya-enable' manifest or OSGI config entries. --| +++ --<pre> --<b>SYNTAX</b> --tamaya:tm_enabled --</pre> --+++ -- --| +tm_history+ --| Gets the getHistory of changes Tamaya applied to the OSGI configuration. --| +++ --<pre> --<b>SYNTAX</b> --tamaya:tm_history [options] [pid] --<b>ARGUMENTS</b> --<i>pid</i> Allows to filter on the given PID. --<i>--type, -t</i> Allows to filter the events types shown. --</pre> --+++ -- --| +tm_history_delete+ --| Deletes the getHistory of changes Tamaya applied to the OSGI configuration. --| +++ --<pre> --<b>SYNTAX</b> --tamaya:tm_history_delete pid --<b>ARGUMENTS</b> --<i>pid</i> Allows to filter on the given PID. --</pre> --+++ -- --| +tm_history_delete_all+ --| Deletes the full getHistory of changes Tamaya applied to the OSGI configuration. --| +++ --<pre> --<b>SYNTAX</b> --tamaya:tm_history_delete_all --</pre> --+++ -- -- --| +tm_history_maxsize+ --| Gets the maximal size of stored getHistory entries. --| +++ --<pre> --<b>SYNTAX</b> --tamaya:tm_history_maxsize --</pre> --+++ -- --| +tm_history_maxsize_set+ --| Sets the maximal size of Tamaya getHistory entries. --| +++ --<pre> --<b>SYNTAX</b> --tamaya:tm_history_maxsize_set size --<b>ARGUMENTS</b> --<i>size</i>: The maximum number of entries in the getHistory. --+++ -- --| +tm_info+ --| Show he current Tamaya status. --| +++ --<pre> --<b>SYNTAX</b> --tamaya:tm_info --</pre> --+++ -- --| +tm_osgi_config+ --| Show the current OSGI configuration. --| +++ --<pre> --<b>SYNTAX</b> --tamaya:tm_osgi_config [options] pid --<b>ARGUMENTS</b> --<i>pid</i> The target OSGI component PID. --<b>OPTIONS</b> --<i>section, -s, --section</i>: A starting expression selecting the keys to be filtered. --</pre> --+++ -- --| +tm_policy+ --| Get the current Tamaya overriding policy. --| +++ --<pre> --<b>SYNTAX</b> --tamaya:tm_policy --</pre> --+++ -- --| +tm_policy_set+ --| Sets the current Tamaya operation policy. --| +++ --<pre> --<b>SYNTAX</b> --tamaya:tm_policy_set tm_policy_set --<b>ARGUMENTS</b> --<i>tm_policy_set</i>: The operation policy how Tamaya intercepts OSGI configuration. --+++ -- --| +tm_propagate_updates+ --| Flag if Tamaya is automatically triggering OSGI config updates, when according Tamaya configuration changes. --| +++ --<pre> --<b>SYNTAX</b> --tm_propagate_updates --+++ -- --| +tm_propagate_updates_set+ --| Configure if Tamaya is automatically triggering OSGI config updates, when according Tamaya configuration changes. --| +++ --<pre> --<b>SYNTAX</b> --tamaya:tm_propagate_updates_set enabled --<b>ARGUMENTS</b> --<i>enabled</i>: Set to true to enable Tamaya's updating trigger. --</pre> --+++ -- --| +tm_property+ --| Get a Tamaya property. --| +++ --<pre><b>SYNTAX</b> --tamaya:tm_property [options] [key] --<b>ARGUMENTS</b> --<i>key</i>: The target property source id. --<b>OPTIONS</b> --<i>extended,e</i>: Also print extended property value attributes. --<i>propertysource, ps</i>: The target property source id. --</pre> --+++ -- --| +tm_propertysource+ --| Show the current Tamaya entries of a propertysource. --| +++ --<pre><b>SYNTAX</b> --tamaya:tm_propertysource [propertysource] --<b>ARGUMENTS</b> --<i>propertysource</i>: The target property source id. --+++ -- --| +tm_propertysources+ --| Get a list of currently registered propertysources. --| +++ --<pre> --<b>SYNTAX</b> --tamaya:tm_propertysources --</pre> --+++ -- --|======= -- --==== Apache Karaf Ferature -- --Apache Tamaya provides a Karaf feature with all required dependencies --as +org.apache.tamaya.ext:tamaya-karaf-features:{tamaya-version}:features:xml+. -- -- -- --==== Apache Felix Gogo Console -- --Apache Tamaya also provides the same commands as described for _Karaf_, but executable in --plaing Gogo console as used by Apache Felix and Equinox as --+org.apache.tamaya.ext:tamaya-gogo-shell:{tamaya-version}+. Refer to the previous sections for --a detailed command description. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_remote.adoc ---------------------------------------------------------------------- diff --cc content/documentation-new/extensions/mod_remote.adoc index fb7ffa9,fb7ffa9..0000000 deleted file mode 100644,100644 --- a/content/documentation-new/extensions/mod_remote.adoc +++ /dev/null @@@ -1,111 -1,111 +1,0 @@@ --:jbake-type: page --:jbake-status: published -- --= Apache Tamaya - Extension: Remote Configuration -- --toc::[] -- -- --[[Remote]] --== Tamaya Remote Configuration (Extension Module) -- --Tamaya _Remote_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. -- -- --=== What functionality this module provides ? -- --Tamaya _Remote_ provides support for reading configuration from remote resources. It provides --out-of-the-box support for reading scoped configuration from a Tamaya configuration server as --provided with the Tamaya _server_ module . -- -- --=== Compatibility -- --The module is based on Java 8, so it will not run on Java 8 and beyond. -- -- --=== Installation -- --To use remote support you only must add the corresponding dependency to your module: -- --[source, xml] ------------------------------------------------- --<dependency> -- <groupId>org.apache.tamaya.ext</groupId> -- <artifactId>tamaya-remote</artifactId> -- <version>{tamaya_version}</version> --</dependency> ------------------------------------------------- -- -- --=== Reading Remote configuration from a Tamaya Configuration Server -- --The remote module allows reading JSON formatted configuration as provided by the Tamaya _server_ extension . The JSON --format used looks as follows: -- --[source, json] ------------------------------------------------- --{ -- "java.vendor.url": "http://java.oracle.com/";, -- "java.vendor.url.bug": "http://bugreport.sun.com/bugreport/";, -- "java.vm.info": "mixed mode", -- "java.vm.name": "Java HotSpot(TM) 64-Bit Server VM", -- "java.vm.specification.name": "Java Virtual Machine Specification", -- "java.vm.specification.vendor": "Oracle Corporation", -- "java.vm.specification.version": "1.8", -- "java.vm.vendor": "Oracle Corporation", -- "java.vm.version": "25.45-b02", -- "sun.arch.data.model": "64", -- "sun.boot.class.path": "C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes", -- "sun.boot.library.path": "C:\apps\jdk18\jre\bin", -- "sun.cpu.endian": "little", -- "sun.cpu.isalist": "amd64", -- "sun.desktop": "windows", -- "sun.io.unicode.encoding": "UnicodeLittle", -- "sun.java.command": "com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start", -- "sun.java.launcher": "SUN_STANDARD", -- "sun.jnu.encoding": "Cp1252", -- "sun.management.compiler": "HotSpot 64-Bit Tiered Compilers", -- "sun.os.patch.level": "", -- "_class": "org.apache.tamaya.functions.FilteredConfiguration", -- "_info.filter": "java.v,sun", -- "_info.format": "application/json", -- "_info.timestamp": "1441463200571", -- "_timestamp": "1441463200571", -- "_type": "Configuration" --} ------------------------------------------------- -- --Basically there are no constraints about they keys provided. By default Tamaya uses keys prefixed with --+'_'+ to identify meta-data entries, but this is not a required precondition. -- --Finally such a remote configuration can be easily integrated by inheriting from the provided base --class. Hereby a default ordinal must be defined and the +protected Collection<URL> getAccessURLs()+ --method must be implemented to define the URL from where the configuration should be accessible. Hereby --multiple URLs can be provided, which are accesed in order as provided by the collection's iterator. The --first accessible URL determines the configuration read. -- --[source, java] ------------------------------------------------- --public class RemoteConfigSource extends BaseRemoteConfigSource{ -- -- @Override -- protected Collection<URL> getAccessURLs() { -- try { -- String configServerUrl = System.getenv("CONFIG_SERVER"); -- if(configServerUrl==null){ -- configServerUrl = System.getProperty("configServer"); -- } -- if(configServerUrl==null){ -- configServerUrl = "http://localhost:8888/config?scope=CLIENT&scopeId={clientId}&format=application/json";; -- } -- System.out.println("Reading config from " + configServerUrl.replace("{clientId}", Client.getClientId())); -- return Arrays.asList(new URL[]{new URL(configServerUrl.replace("{clientId}", Client.getClientId()))}); -- } catch (MalformedURLException e) { -- Logger.getLogger(getClass().getName()).log(Level.WARNING, "Failed to configure remote config location,", e); -- return Collections.emptySet(); -- } -- } -- --} ------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_resolver.adoc ---------------------------------------------------------------------- diff --cc content/documentation-new/extensions/mod_resolver.adoc index dac7735,dac7735..0000000 deleted file mode 100644,100644 --- a/content/documentation-new/extensions/mod_resolver.adoc +++ /dev/null @@@ -1,131 -1,131 +1,0 @@@ --:jbake-type: page --:jbake-status: published -- --= Apache Tamaya - Extension: Resolver -- --[[Resolver]] --== Tamaya Resolver (Extension Module) -- --Tamaya _Resolver_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. -- -- --=== What functionality this module provides ? -- --Tamaya _Resolver_ is an extension module. Refer to the link:../extensions.html[extensions documentation] --for further details about modules. -- --Tamaya Resolver provides a extendible dynamic resolution mechanism. It allows to use UNIX-styled (+${...}+ placeholder --expressions in your configuration values. The resolver hereby supports transitive resolution and also prevents --cycles to loop endlessly. -- -- --=== Compatibility -- --The module is based on Java 8, so it can be used with Java 8 and beyond. -- -- --=== Installation -- --To benefit from dynamic value resolution you only must add the corresponding dependency to your module: -- --[source, xml, subs="verbatim,attributes"] ------------------------------------------------- --<dependency> -- <groupId>org.apache.tamaya.ext</groupId> -- <artifactId>tamaya-resolver</artifactId> -- <version>{tamaya_version}</version> --</dependency> ------------------------------------------------- -- --The module automatically registers an according +Filter+ that is automatically called, whenever a value --is accessed. -- -- --=== Available Resolvers -- --Currently the module defines the following resolvers: -- --.Available Resolvers --[cols="<.1,<.2,<.1"] --|======= --| _Expression_ --| _Description_ --| _Example_ -- --| +conf:<configKey>+ --| Reads another configKey and replaces the expression with the value found. --| conf-ref=${conf:anotherConf.entryKey} -- --| +resource:<resourceRef>+ --| Reads a resource from the current classpath and replaces the expression with the given text content. --| cp-ref=${resource:Testresource.txt} -- --| +file:<fileRef>+ --| Reads a resource from the current classpath and replaces the expression with the given text content. --| file-ref=${file:c:\myFile.txt} -- --|+url:<url>+ --|Reads an URL and replaces the expression with the given text content. --| url-ref=${url:http://www.google.com} -- --|======= -- -- --=== SPI: Implementing your own Resolvers -- --The module also provides a small SPI for adding your own resolver implementations. Basically the --first and most important thing to do is implementing the +ExpressionResolver+ interface: -- --.Implementing a Custom Resolver --[source, java] ------------------------------------------------- --public class PwdDecrypter implements ExpressionResolver { -- -- @Override -- public String getResolverPrefix() { -- return "decrypt:"; -- } -- -- @Override -- public String evaluate(String expression) { -- return decrypt(expression); -- } -- -- private String decrypt(String s) { -- ... -- } --} ------------------------------------------------- -- --Basically that is all you must do, after having registered the class with the +ServiceLoader+ it will be found --and loaded by the implementation. With that all expressions that start with the given prefix are passed to the --resolver, so all the following expressions will be sent to the implementation: -- --[source,listing] ------------------------------------------------- --blabla ${decrypt:myname} --blabla ${decrypt:myname} foo blabla ${decrypt:myname} ------------------------------------------------- -- --Hereby evaluation is repeated until no further change of values could be detetced. In case of a endless loop --the evaluation is broken after a (configurable) number of cycles. -- -- --Under the hood instances of +ExpressionResolver+ are managed by an implementation of the +ExpressionEvaluator+ --interface: -- --[source, java] ------------------------------------------------- --public interface ExpressionEvaluator { -- /** -- * Evaluates the current expression. -- * @param key the key, not null. -- * @param value the value to be filtered/evaluated. -- * @return the filtered/evaluated value, including null. -- */ -- String evaluateExpression(String key, String value); --} ------------------------------------------------- -- --Implementing and registering this interface gives you full control, but in most cases you should be fine with --the default implementation in place.
