Apache Tamaya — Extension: Model Documentation and Validation

Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id EE949200BF1 for ; Mon, 19 Dec 2016 20:28:45 +0100 (CET) Received: by cust-asf.ponee.io (Postfix) id ED2DC160B21; Mon, 19 Dec 2016 19:28:45 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id A2C0E160B14 for ; Mon, 19 Dec 2016 20:28:43 +0100 (CET) Received: (qmail 58579 invoked by uid 500); 19 Dec 2016 19:28:42 -0000 Mailing-List: contact commits-help@tamaya.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@tamaya.incubator.apache.org Delivered-To: mailing list commits@tamaya.incubator.apache.org Received: (qmail 58570 invoked by uid 99); 19 Dec 2016 19:28:42 -0000 Received: from pnap-us-west-generic-nat.apache.org (HELO spamd1-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 19 Dec 2016 19:28:42 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd1-us-west.apache.org (ASF Mail Server at spamd1-us-west.apache.org) with ESMTP id 4D283C05FF for ; Mon, 19 Dec 2016 19:28:42 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd1-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: -6.219 X-Spam-Level: X-Spam-Status: No, score=-6.219 tagged_above=-999 required=6.31 tests=[KAM_ASCII_DIVIDERS=0.8, KAM_LAZY_DOMAIN_SECURITY=1, RCVD_IN_DNSWL_HI=-5, RCVD_IN_MSPIKE_H3=-0.01, RCVD_IN_MSPIKE_WL=-0.01, RP_MATCHES_RCVD=-2.999] autolearn=disabled Received: from mx1-lw-eu.apache.org ([10.40.0.8]) by localhost (spamd1-us-west.apache.org [10.40.0.7]) (amavisd-new, port 10024) with ESMTP id cPU9yB-CvwjY for ; Mon, 19 Dec 2016 19:28:36 +0000 (UTC) Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx1-lw-eu.apache.org (ASF Mail Server at mx1-lw-eu.apache.org) with SMTP id 8C83D5F1BA for ; Mon, 19 Dec 2016 19:28:33 +0000 (UTC) Received: (qmail 55844 invoked by uid 99); 19 Dec 2016 19:27:17 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 19 Dec 2016 19:27:17 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id A4A69DFBAE; Mon, 19 Dec 2016 19:27:17 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: pottlinger@apache.org To: commits@tamaya.incubator.apache.org Date: Mon, 19 Dec 2016 19:27:19 -0000 Message-Id: <85155220e5d542d48852437e3c6d275a@git.apache.org> In-Reply-To: <146a22fc32784b25aa65d434b43ef744@git.apache.org> References: <146a22fc32784b25aa65d434b43ef744@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [3/9] incubator-tamaya-site git commit: TAMAYA-178: Remove generated files from wrong branch. archived-at: Mon, 19 Dec 2016 19:28:46 -0000 http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/23530561/documentation/extensions/mod_model.html ---------------------------------------------------------------------- diff --git a/documentation/extensions/mod_model.html b/documentation/extensions/mod_model.html deleted file mode 100644 index 119c3a5..0000000 --- a/documentation/extensions/mod_model.html +++ /dev/null @@ -1,792 +0,0 @@ - - - - - - Apache Tamaya — Extension: Model Documentation and Validation - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

- - - - -

- - - -

2016-12-18

- -

Tamaya Model Documentation and Validation (Extension Module)

Overview

The Tamaya model module provides support for documenting configuration and validating configuration read and processed -against this model. Documentation and config models can be provided in different ways:

-
as separate meta-model documents
-
-
by providers that check classes/packages for configuration annotations (planned)
-

Compatibility

The module is based on Java 7, so it will not run on Java 7 and beyond.

Installation

To benefit from configuration builder support you only must add the corresponding dependency to your module:

<dependency>
-  <groupId>org.apache.tamaya.ext</groupId>
-  <artifactId>tamaya-model</artifactId>
-  <version>{tamaya_version}</version>
-</dependency>

Describing the Configuration Meta-Model

Basically configuration is modelled using key, value-pairs. Looking at a keys -a.b.c.param1 and a.b.c.param2 the following concepts can be used to defined/describe -configuration:

-
the configuration section: In our case this equals to a.b.c, which itself also includes the -transitive entries a.b and a.
-
-
the configuration parameter: Basically parameters are adressed using their fully qualified names, -which equals to the containing section name and the relative parameter name, separated by the dor separator. -In the above example a.b.c.param1 and a.b.c.param2 are the fully qualified parameter names.
-

Now with only these 2 concepts a simple configuration meta-model can be defined as

-
a meta-model’s name, used just for grouping different meta-models and entries to better separate -descriptions, e.g. in a management console or generated configuration documentation site.
-
-
a set of sections.
-
-
a set of parameters.
-
-
Both, sections (.model.target=Section) as well as parameter models (.model.target=Parameter)
-
-
- -
  can be modelled by a meta-data entry, by default _my.config.key.model.
  -
- -
  may be required, or optional (.model.required=true|false)
  -
- -
  may have an optional description
  -
-
-
-
Parameters additionally have
-
-
- -
  a type (.model.type=Classname), described by the fully qualified class name, into which any configured (String) -value must be convertable into. If no type is configured java.ui.lang.String is assumed as default.
  -
- -
  an optional regular expression that can be used to validate the String values returned from a -configuration (.model.expression=regexpression).
  -
-
-

Given these concepts a configuration can be fully described. Entries that are not contained in one of the given -sections (or its children), or parameters not described or marked as valid (e.g. for dynamic configModels of -a section), are called undefined. Undefined parameters should be grouped with its parent section. Each section, as -well as all parent sections, including transitive) of any parametet read, should similarly marked as undefined, if and -only if

-
the section itself is (directly) undefined
-
-
the section is not a super section of a defined section.
-

As en example the section definition of a.b.c also implicitly includes the sections a.b and a to be defined -sections, despite the fact that section properties, such as description and custom configModels are not inherited to -its parent, or child section.

Defining Meta-Configuration Model

The configuration meta-model is defined by simple configuration meta-data entries. The section for all model -configuration by default is called model, which results in entries such as _my.config.key.model.target=Section. -Within this section fully qualified configuration keys defines -which part of the configuration is targeted by certain entries.

Defining Sections

First we start to define some configuration sections, the example below starts with the most important -variants supported:

# Metamodel information
-_model.provider=ConfigModel Extension
-
-# org.mycompany.root (optional section)
-_org.mycompany.root.model.target=Section
-_org.mycompany.root.model.description=Root section defining my company configuration.
-
-# org.mycompany.security (required section)
-_org.mycompany.security.model.target=Section
-_org.mycompany.security.model.required=true
-_org.mycompany.security.model.description=Security related settings.\
-         refer for further details to XXX.
-
-# minmal section
-_minimal.model.target=Section
-
-# custom validated section
-_validated.model.target=Section
-_validated.model.validator=org.apache.tamaya.model.TestValidator

Above org.mycompany.root transitively defines 3 sections:

-
org
-
-
org.mycompany
-
-
org.mycompany.root
-

All sections are optional. Additionally the model above also defines a required section org.mycompany.security. -Required sections are checked so the section is not empty. It is not checked for any specific parameter hereby, -only the existance of any child parameter is validated.

The class attribute has to be defined for any section definition, because if not set a model entry is, by default, -defined to be a parameter configModel entry. Given above the entry for the section minimal shows such a minimal -entry.

validated defines a section, which is validated through a customizable validator. Hereby an ordered list of validators -can be provided, separated by commas.

Defining Parameters

Similarly parameters also can be defined:

# org.mycompany.root.name (required parameter)
-_org.mycompany.root.name.model.target=Parameter
-_org.mycompany.root.name.model.required=true
-_org.mycompany.root.name.model.description=The company's name, also used in the application's main header.
-
-# org.mycompany.security (required parameters)
-_org.mycompany.security.uid.model.required=true
-_org.mycompany.security.uid.model.description=The user id.
-_org.mycompany.security.realm.model.required=true
-_org.mycompany.security.realm.model.validator=org.apache.tamaya.model.RealmValidator
-_org.mycompany.security.realm.model.description=The security realm required.
-_org.mycompany.security.tokenid.model.description=The token id, if the token service is used (optional).
-
-# A minmal parameter
-_minimalClass.model.target=Class

Similarly as when defining section also parameter entries define transitively its containing sections. E.g. -the entry above for org.mycompany.security.realm also defines the following sections (as optional).

-
org
-
-
org.mycompany
-
-
org.mycompany.security
-

Additional entries for section, e.g. configModels to be done, can be added as described in the previous section, -but are optional.

Since the parameter is the default type for model entries, a minmal parameter model entry only only needs it’s -parameter type to be defined. In the example above we define a parameter minimalClass of type Class. -Types hereby are fully qualified class names, whereas as 'java.ui.lang' for built-in language types can be -ommitted.

Model Locations

By default the configuration model can be defined at the following locations:

-
classpath*:META-INF/configmodel.properties, separate to the current Configuration. This functionality is enabled -by default, but can be disabled by adding org.apache.tamaya.model.default.enabled=false to your current -Configuration.
-
-
implicitly as part of the current +Configuration. THis can be disabled by setting -the org.apache.tamaya.model.integrated.enabled configuration poarameter to false.
-
-
customized by configuring the org.apache.tamaya.model.resources in the current Configuration. This -parameter allows to define the locations from where the model extension is trying to read the -model configuration. If the resources extension is available in your system it is used to -evaluate the locations. If not the default Classloader.getResources command is issued. Also it -is required that the formats extension is available, since this is used to effectively read the -data. This extension also allows you to use alternate representation formats such as ini, xml, yml, json.
-

Tracking Configuration Access

The model module also allows tracking which code accesses configuration properties or configuration parameters. -It checks the stacktrace to evaluate the calling code location, hereby any unwanted packages can be implicitly -ommitted from the stacktrace. Also the maximal length of the stacktrace retained can be constraint in length. -The usages are recorded as Usage instances. Hereby for each parameter accessed a corresponding Usage -instance is created. It can be accessed by calling Usage ConfigUsageStats.getUsage(String key). Usage -statistics for calling Configuration.getProperties() can be obtained calling Usage getUsageAllProps();.

Usage tracking is disabled by default. It can be enabled by calling ConfigUsageStats.enableUsageTracking(true);. -ConfigUsageStats.isUsageTrackingEnabled() returns the current tracking status.

The Usage class itself provides access to further fainer grained usage data (AccessDetail) containing:

-
the access point (fqn.ClassName#method(line: xxx)).
-
-
the number of accesses
-
-
the first an last access
-
-
the values read
-
-
the access stacktrace (filtered by ignored packages).
-

public final class Usage {
-    [...]
-    public String getKey();
-    public void clearMetrics();
-    public int getReferenceCount();
-    public int getUsageCount();
-    public Collection<AccessDetail> getAccessDetails(Class type);
-    public Collection<AccessDetail> getAccessDetails(Package pack);
-    public Collection<AccessDetail> getAccessDetails(String lookupExpression);
-    public Collection<AccessDetail> getAccessDetails();
-    public void trackUsage(String value);
-    public void trackUsage(String value, int maxTraceLength);
-
-
-    public static final class AccessDetail {
-        [...]
-        public void clearStats();
-        public long trackAccess(String value);
-        public long getAccessCount();
-        public String getAccessPoint();
-        public long getFirstAccessTS();
-        public long getLastAccessTS();
-        public String[] getStackTrace();
-        public Map<Long, String> getTrackedValues();
-    }
-
-}

With ConfigUsageStats.clearUsageStats() the collected statistics can be reset at any time. Summarizing the main -singleton for configuration statistics is defined as follows:

public final class ConfigUsageStats{
-    public static Set<String> getIgnoredUsagePackages();
-    public static void addIgnoredUsagePackages(String... packageName);
-    public static void enableUsageTracking(boolean enabled);
-    public static Usage getUsage(String key);
-    public static Collection<Usage> getUsages();
-    public static void clearUsageStats();
-    public static Usage getUsageAllProperties();
-    public static boolean isUsageTrackingEnabled();
-    public static String getUsageInfo();
-}

Customizing the Stacktrage for Usage Reporting

The stacktrace tracked by the system can be customized in several ways:

-
ConfigUsageStats.addIgnoredPackageNames(String...) allows to add additional ignored package names.
-
-
With Usage.setMaxTraceLength(int) the maximal size of the stacktraces logged can be set. Setting a -negative value will disable stacktrace logging completelely.
-

Accessing Usage Statistics

Bascially usage statistics are available in two forms:

-
The Usage/AccessDetail object tree can be accessed programmatically from the ConfigUsageStats -singleton.
-
-
With ConfigUsageStats.getUsageInfo() also a textual representation of the usage statistics -can be obtained, as illustrated below (a snipped from the current test output):
-

Apache Tamaya Configuration Usage Metrics
-=========================================
-DATE: Sat Apr 30 21:51:09 CEST 2016
-
-220    <<all>>:
-  - 220   <unknown/filtered/internal>                       , first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016
-3      java.version:
-  - 2     test.model.TestConfigAccessor#readProperty(line:43), first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016
-  - 1     <unknown/filtered/internal>                       , first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016

Programmatic API

Basically the configModel module provides a simple API to access the defined ConfigModel instances and -validating the current Configuration against the models as follows:

public final class ConfigModelManager {
-
-    private ConfigModelManager() {}
-
-    public static Collection<ConfigModel> getModels();
-    public static Collection<ConfigModel> findModels(ModelType type, String namePattern);
-    public static <T extends ConfigModel> T getModel(String name, Class<T> modelType);
-    public static Collection<ConfigModel> findModels(String namePattern);
-
-    public static Collection<ValidationResult> validate();
-    public static Collection<ValidationResult> validate(boolean showUndefined);
-    public static Collection<ValidationResult> validate(Configuration config);
-    public static Collection<ValidationResult> validate(Configuration config, boolean showUndefined);
-
-    public static void registerMBean();
-    public static void registerMBean(String context);
-
-}

This singleton allows to validate the current or any Configuration instance. All the ConfigModels read also are -available from the getModels method. This models can be used to provide documentation, e.g. as part of a CLI interface -or shown on a documentation web server.

A ConfigModel hereby is defined as one single part of configuration, typically corresponding to a specific concern -of your system. As an example you can define different models for different modules or products plugged together. -With resolution mechanism in place you can also define a shared module that is targeted by multiple modules as a -single configuration source (e.g. for configuring the machine’s IP address and subnet settings only once.

public interface ConfigModel {
-
-    ModelTarget getType();
-    String getName();
-    String getProvider();
-    boolean isRequired();
-    String getDescription();
-    Collection<ValidationResult> validate(Configuration config);
-}

Hereby ModelTarget defines more details on the kind of model:

public enum ModelTarget {
-    /**
-     * A configuration section.
-     */
-    Section,
-    /**
-     * A configuration paramter.
-     */
-    Parameter,
-    /**
-     * ConfigModel that is a container of other validations.
-     */
-    Group
-}

A ValidationResult models one validation executed by a ConfigModel on a certain Configuration instance:

public final class ValidationResult {
-
-    public static ValidationResult ofValid(ConfigModel configModel);
-    public static ValidationResult ofMissing(ConfigModel configModel);
-    public static ValidationResult ofMissing(ConfigModel configModel, String message);
-    public static ValidationResult ofError(ConfigModel configModel, String error);
-    public static ValidationResult ofWarning(ConfigModel configModel, String warning);
-    public static ValidationResult ofDeprecated(ConfigModel configModel, String alternateUsage);
-    public static ValidationResult ofDeprecated(ConfigModel configModel);
-    public static ValidationResult ofUndefined(final String key);
-    public static ValidationResult of(ConfigModel configModel, ValidationState result, String message);
-
-    public ConfigModel getConfigModel();
-    public ValidationState getResult();
-    public String getMessage(),
-}

The result of a complete validation on a concrete Configuration instance finally is mapped as a -Collection<ValidationResult>, refer to the methods on ConfigModelManager.

Auto-Documentation of Classes with Configuration Injection

A special feature of this module is that it observes ConfigEvent published through Tamaya’as event channel -(tamaya-events module). If no metaconfiguration model is found the model manager by default automatically creates -models for all injected instances on the fly. In the case of CDI integration this happens typically during deployment -time, since CDI initializes during deployment time. Other runtime platforms, such as OSGI, may have rather different -behaviour. Nevertheless this means that after your system has been started you should have access to a complete -set of ConfigModel instances that automatically document all the classes in your system that consume configuration -(through injection).

Model SPI

Registering Configuration Models

The model extension also provides an SPI where customized functionality can be added. The main abstraction hereby is -the ModelProviderSpi interface, which allows any kind of additional config models to be added to the system:

public interface ModelProviderSpi {
-
-    Collection<ConfigModel> getConfigModels();
-
-}

New instances implementing this interface must be registered into the current ServiceContext, by default the -ServiceLoader is used.

The ConfigUsageStatsSpi

The methods for managing and tracking of configuration changes are similarly delegated to an -implementation of the org.apache.tamaya.model.spi.ConfigUsageStatsSpi SPI. -By implementing this SPI and registerting it with the ServiceContext the usage tracking -logic can be adapted or replaced.

Other Utility Classes

The module also provides further utility classes that may be useful for implementing models or testing:

-
AbstractModel provides a base class that can be extended, when implementing ConfigModel.
-
-
AreaConfigModel provides a ConfigModel implementation (with a corresponding Builder) to model the -requirement of certain configuration sections being present, or opionally present, in the model.
-
-
ParameterModel provides an implementation base class for validating parameters on existence and compliance -with a regular expression.
-
-
ConfigDocumentationMBean is the MBean registered that models similar functionality as ConfigModelManager.
-
-
ConfigModelGroup provides a ConfigModel that groups several child models.
-
-
ConfigModelReader allows to read ConfigModels from properties files as described at the beginning of this -document.
-

Switches to enable/disable functionality

The model module provides different switches that can be used to activate or deactivate features:

-
tamaya.model.integrated.enabled allows to deactivate reading inline metaconfiguration delivered with -the normal Tamaya Configuration. By default inline entries (_.abcd.model.*) are evaluated.
-
-
tamaya.model.default.enabled allows to deactivate reading metamodel information from -classpath:META-INF/configmodel.properties. By default it is active.
-
-
tamaya.model.resources allows to define additional resources (loaded through the resources extension), -that can be used to read metamodel information in any format using Tamaya’s format module.
-
-
the system property tamaya.model.autoModelEvents allows to activate/deactivate the automatic -documentation of classes configured and published by Tamaya ConfiguredType event instances (e.g. published by -Tamaya’s injection modules).
-

- -

- Disclaimer - Apache Tamaya (incubating) is an effort undergoing - incubation at - The Apache Software Foundation (ASF), sponsored by - the name of Apache Incubator. Incubation is required of - all newly accepted projects until a further review indicates - that the infrastructure, communications, and decision making - process have stabilized in a manner consistent with other - successful ASF projects. While incubation status is not - necessarily a reflection of the completeness or stability of - the code, it does indicate that the project has yet to - be fully endorsed by the ASF.
- -

- - - - - - - -

- - http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/23530561/documentation/extensions/mod_mutable_config.html ---------------------------------------------------------------------- diff --git a/documentation/extensions/mod_mutable_config.html b/documentation/extensions/mod_mutable_config.html deleted file mode 100644 index 2485b7b..0000000 --- a/documentation/extensions/mod_mutable_config.html +++ /dev/null @@ -1,505 +0,0 @@ - - - - - - Apache Tamaya — Extension: Mutable Configuration - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

- - - - -

- - - -

2016-12-18

- -

Tamaya Mutable Configuration (Extension Module)

Overview

Tamaya Configuration by default is read-only, which covers must of the use cases. But there are many legit scenarios -where configuration should be written back to some backend systems or the local file system. This module adds this -functionality.

Compatibility

The module is based on Java 7, so it can be used with Java 7 and beyond.

Installation

To benefit from configuration mutability support you only must add the corresponding dependency to your module:

<dependency>
-  <groupId>org.apache.tamaya.ext</groupId>
-  <artifactId>tamaya-mutable-config</artifactId>
-  <version>{tamaya_version}</version>
-</dependency>

Core Architecture

Accessing MutableConfiguration

The core of the module is the MutableConfigurationProvider singleton, which provides access to MutableConfiguration -instance, which extends Configuration. This interface adds additional methods to add/update or remove property values. -Hereby changes applied are managed in a transaction like context, called ConfigChangeContext. Each context defines -a UUID that identifes a change. -Backends for writing changes applied are of type MutablePropertySource, similarly extending the PropertySource -SPI with methods for writing changes back. Registrations and ordering policies are like with ordinary property sources, -with one important difference. Mutable property source can be targeted by write operations.

The example below shows how a MutableConfiguration can be obtained the simplest way:

Accessing and changing configuration

MutableConfiguration config = MutableConfigurationProvider
-                                      .createMutableConfiguration();
-config.put("newKey", "newValue")
-      .put("anotherKey", "updatedValue")
-      .remove("valueNotValid")
-      .store();

In the above scenario we use the overall system’s configuration as the backend to be used. -We can also pass any Configuration to render it into a mutable instance, e.g.

Explicitly passing the backing configuration

Configuration config = ...;
-MutableConfiguration config = MutableConfigurationProvider
-                                       .createMutableConfiguration(config);

- - - - - -

Note

-If a configuration does not contain any MutablePropertySource instances, - a MutableConfiguration built from it will not be able to accept any changes. -

Following you see the options how to create a MutableConfiguration using the -MutableConfigurationProvider singleton:

public final class MutableConfigurationProvider {
-
-    private MutableConfigurationProvider(){}
-
-    public static MutableConfiguration createMutableConfiguration();
-    public static MutableConfiguration createMutableConfiguration(
-                                               ChangePropagationPolicy changePropgationPolicy);
-    public static MutableConfiguration createMutableConfiguration(Configuration configuration);
-    public static MutableConfiguration createMutableConfiguration(
-                                                   Configuration configuration,
-                                                   ChangePropagationPolicy changePropgationPolicy);
-
-    [...]
-}

Hereby MutableConfiguration is defined as follows:

public interface MutableConfiguration extends Configuration {
-
-    void store();
-
-    ConfigChangeRequest getConfigChangeRequest();
-    ChangePropagationPolicy getChangePropagationPolicy();
-
-    MutableConfiguration put(String key, String value);
-    MutableConfiguration putAll(Map<String, String> properties);
-    MutableConfiguration remove(Collection<String> keys);
-    MutableConfiguration remove(String... keys);
-
-}

Targeting the right MutablePropertySources

A Configuration may have multiple MutablePropertySource instances present. These are members of Tamaya’s oredered list of -PropertySources to evaluate the configuration. Nevertheless writing back changes requires additional aspects to -be considered: -* Should changes being written back to all mutable property sources? Or should a key that could be added or removed - on a more significant instance not be written/removed on less significant property source instances? -* Should a change be applied only to a specific mutable property source, regardless its position in the - processing chain?

Therefore a ChangePropagationPolicy can be set on a MutableConfiguration instance, which allows to control -this aspect:

Explicitly passing the backing configuration

public interface ChangePropagationPolicy {
-    /**
-     * Method being called when a multiple key/value pairs are added or updated.
-     * @param propertySources the property sources, including readable property sources of the current configuration,
-     *                        never null.
-     * @param configChange the configuration change, not null.
-     */
-    void applyChange(ConfigChangeRequest configChange, Collection<PropertySource> propertySources);
-}

By default, changes are applied to all registered MutablePropertySources similarly.

Also the MutableConfigurationProvider provides access to the most commonly used change propagation policies:

public final class MutableConfigurationProvider {
-
-    [...]
-
-    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. Nevertheless -changing or adding value is very easy:

Changing a configuration

MutableConfiguration config = MutableConfigurationProvider.createMutableConfiguration();
-config.put("newKey", "newValue");
-config.remove("mycluster.myapp.myKey");
-config.store();

Configuration Changes

This module does not handle detection of changes to the overall system’s Configuration. 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 MutableConfigurationBackendSpi may inform/update any affected PropertySource, -PropertySourceProvider instances about the changes applied.
-

Supported Backends

Multiple backends are supported. E.g. the etcd integration module of Tamaya also registers -corresponding SPI implementations/backends. By default this module comes with -the following MutablePropertySource implementations:

-
MutablePropertySource resources, targeting local .properties files, using the java.util.Properties -format.
-
-
MutableXmlPropertySource resources, targeting local .xml property files, using the java.util.Properties -XML format.
-

Refreshable Property Sources

Somehow similar to configuration changes applied explicitly is the case, where values of underlying -configuration backends change and must be reflected in the new configuration tree. Examples are:

-
Configuration files being edited, added or removed.
-
-
Changes on remote servers like etcd, consul
-
-
etc.
-

For having a common API for refreshable items a Refreshable interface is defined:

Refreshable interface

/**
- * Interface to be implemented by items that can be refreshed. By default
- * these are property sources, but more types may be supported at a later
- * point in time.
- */
-public interface Refreshable {
-
-    /**
-     * Refreshes the item by reloading its internal state.
-     */
-    void refresh();
-
-}

Refreshable Property Sources

- -

SPIs

The module defines MutableConfigurationProviderSpi, that is used as a delegate by the MutableConfigurationProvider -singleton accessor:

SPI: MutableConfigurationProviderSpi

public interface MutableConfigurationProviderSpi {
-    /**
-     * Creates a new {@link MutableConfiguration} 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.
-     */
-    MutableConfiguration createMutableConfiguration(Configuration 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/23530561/documentation/extensions/mod_optional.html ---------------------------------------------------------------------- diff --git a/documentation/extensions/mod_optional.html b/documentation/extensions/mod_optional.html deleted file mode 100644 index cdd5427..0000000 --- a/documentation/extensions/mod_optional.html +++ /dev/null @@ -1,225 +0,0 @@ - - - - - - Apache Tamaya — Extension: Optional Tamaya Configuration - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

- - - - -

- - - -

2016-12-18

- -

Tamaya Optional Configuration (Extension Module)

Overview

The Tamaya optional module provides contains three types only. It 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 artofacts. -It automatically checks the availability of Tamaya on the classpath and only if available 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 7, so it will not run on Java 7 and beyond.

Installation

To benefit from configuration builder support you only must add the corresponding dependency to your module:

<dependency>
-  <groupId>org.apache.tamaya.ext</groupId>
-  <artifactId>tamaya-optional</artifactId>
-  <version>{tamaya_version}</version>
-</dependency>

Reading configuration using the Tamaya Optional Module

The optional module allows reading configuration with a small subset of functionality only. For extended of full -featured config please consider using the Apache Tamaya as a full configuration backend.

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/23530561/documentation/extensions/mod_osgi.html ---------------------------------------------------------------------- diff --git a/documentation/extensions/mod_osgi.html b/documentation/extensions/mod_osgi.html deleted file mode 100644 index 4ee782a..0000000 --- a/documentation/extensions/mod_osgi.html +++ /dev/null @@ -1,315 +0,0 @@ - - - - - - Apache Tamaya — Extensions: OSGI Integrations - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

- - - - -

- - - -

2016-12-18

- -

Tamaya OSGI Support

Overview

Tamaya provides also support for integration with OSGI. Hereby several options are available how Tamaya can be used in -an OSGI context:

-
All Tamaya modules, its API and core library are actually valid OSGI bundles. So adding them into your OSGI modules -and using Tamaya is basically directly supported. Nevertheless OSGI works rather differently from a class- and -resource loading perspective. As long as you rely on Tamaya’s mechanisms for resource loading things should work -out of the box. In the back Tamaya’s core module actually comes with implicit OSGI support, which is automatically -activated, if Tamaya is running in an OSGI context. This support actually
-
-
- -
  Listens on deployed bundles and actively reads all resources configured as java.util.ServiceLoader services and -registers them as OSGI services. Hereby integration is complete meaning you can also register Tamaya services -as normal OSGI services, e.g. your own PropertySource instances.
  -
- -
  Uses the OSGI bundle to resolve for resources, because accessing them from the classloader directly -typically fails in an OSGI context.
  -
-
-
-
Adding Tamaya’s OSGI integration module replaces the existing OSGI ConfigAdmin service with an istance based on -Tamaya. Hereby several aspects can be configured using system properties:
-
-
- -
  org.tamaya.integration.osgi.cm.ranking (int) allows to configure the OSGI service ranking used by the Tamaya -BundleActivator to register Tamaya’s ConfigAdmin service. In OSGI higher ranking precede lower rankings. By default -Tamaya’s OSGI extending service registration mechanism is reusing any annotated @Priority priority values as -corresponsing rankings.
  -
- -
  org.tamaya.integration.osgi.cm.override (boolean) allows to configure if Tamaya is overriding any existing -values from the default ConfigAdmin instance, or only extending them. In other words this setting allows you to -define, which configuration subsystem has precedence for evaluating the final values, either Tamaya based -configuration (default) or the configuration mechanisms provided by default from your OSGI container (when this flag -is set to false).
  -
- -
  org.tamaya.integration.osgi.cm.inject allows you to deactivate injection of configuration values into your -OSGI services (by default injection is enabled). In all cases accessing the OSGI ConfigAdmin service to -read your configuration is working as usual. But Tamaya adds additional injection functionality, which allows -to inject typed configuration as described by the Tamaya injection api.
  -
-
-

It is also possible to combine things, e.g. when you only define a low ranking for Tamaya’s configuration service and -the same time allow injection to be active, you will have Tamaya’s injection support based on your default -OSGI configuration.

Compatibility

All module described are based on Java 7, so it will run on Java 7 and beyond. -The modules are built against OSGI Compendium version 5.0.

Installation

To benefit from Tamaya in an OSGI context you must deploy at least the following modules to your OSGI runtime -environment:

# API and core
-org.apache.tamaya:tamaya-api:{tamaya_version}
-org.apache.tamaya:tamaya-core:{tamaya_version}
-org.apache.geronimo.specs:geronimo-annotation_1.2_spec:1.0-alpha-1
-# injection API. SE injection module and dependencies
-org.apache.tamaya.ext:tamaya-injection-api:{tamaya_version}
-org.apache.tamaya.ext:tamaya-injection:{tamaya_version}
-org.apache.geronimo.specs:geronimo-atinject_1.0_spec:1.0
-org.apache.geronimo.specs:geronimo-el_2.2_spec:1.0.4
-org.apache.geronimo.specs:geronimo-interceptor_1.1_spec:1.0
-org.apache.geronimo.specs:geronimo-jcdi_1.1_spec:1.0
-# OSGI integration and dependencies
-org.apache.tamaya.ext:tamaya-osgi:{tamaya_version}
-org.apache.tamaya.ext:tamaya-functions:{tamaya_version}

Usage

As an example, what is possible you can implement an OSGI service as a normal POJO and publish it as an OSGI service. -Given that configuration can be injected very easily:

public class HelloServiceImpl implements HelloService{
-
-    @Config("example.message")
-    @ConfigDefault("A Tamaya default.")
-    private String message;
-
-    @Override
-    public String sayHello() {
-        System.err.println("HELLO: " + message);
-        return message;
-    }
-}

SPI

By default the OSGI pid or factory pid is mapped to a corresponding root section in Tamaya’s configuration. We are -well aware that this might not always be the desired approach. Therefore there as an SPI service provided that allows -to determine this mapping:

OSGIConfigRootMapper

public interface OSGIConfigRootMapper {
-
-    String getTamayaConfigRoot(String pid, String factoryPid);
-}

Registering your own implementation as an OSGI service allows you to redefine the key mapping. -By default a configuration mapping for pid/factoryPid==myBundle is mapped to [bundle:myBundle]. -This mapping is used as a prefix when collecting the corresponding entries for the OSGI configuration.

- -

- - - - - - - -

- -

Apache Tamaya&#8201;&#8212;&#8201;Extension: Model Documentation and Validation

Tamaya Model Documentation and Validation (Extension Module)

Overview

Compatibility

Installation

Describing the Configuration Meta-Model

Defining Meta-Configuration Model

Defining Sections

Defining Parameters

Model Locations

Tracking Configuration Access

Customizing the Stacktrage for Usage Reporting

Accessing Usage Statistics

Programmatic API

Auto-Documentation of Classes with Configuration Injection

Model SPI

Registering Configuration Models

The ConfigUsageStatsSpi

Other Utility Classes

Switches to enable/disable functionality

Apache Tamaya&#8201;&#8212;&#8201;Extension: Mutable Configuration

Tamaya Mutable Configuration (Extension Module)

Overview

Compatibility

Installation

Core Architecture

Accessing MutableConfiguration

Targeting the right MutablePropertySources

Some Aspects to consider

Configuration Changes

Supported Backends

Refreshable Property Sources

Refreshable Property Sources

SPIs

Apache Tamaya&#8201;&#8212;&#8201;Extension: Optional Tamaya Configuration

Tamaya Optional Configuration (Extension Module)

Overview

Compatibility

Installation

Reading configuration using the Tamaya Optional Module

Apache Tamaya&#8201;&#8212;&#8201;Extensions: OSGI Integrations

Tamaya OSGI Support

Overview

Compatibility

Installation

Usage

SPI

Apache Tamaya — Extension: Model Documentation and Validation

Apache Tamaya — Extension: Mutable Configuration

Apache Tamaya — Extension: Optional Tamaya Configuration

Apache Tamaya — Extensions: OSGI Integrations