http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8951b7be/content/documentation-new/extensions/mod_osgi.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_osgi.adoc b/content/documentation-new/extensions/mod_osgi.adoc new file mode 100644 index 0000000..d075ac1 --- /dev/null +++ b/content/documentation-new/extensions/mod_osgi.adoc @@ -0,0 +1,814 @@ +: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. \ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8951b7be/content/documentation-new/extensions/mod_remote.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_remote.adoc b/content/documentation-new/extensions/mod_remote.adoc new file mode 100644 index 0000000..9c234f1 --- /dev/null +++ b/content/documentation-new/extensions/mod_remote.adoc @@ -0,0 +1,111 @@ +: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 7, so it will not run on Java 7 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 RemotePropertySource extends BaseRemotePropertySource{ + + @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/8951b7be/content/documentation-new/extensions/mod_resolver.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_resolver.adoc b/content/documentation-new/extensions/mod_resolver.adoc new file mode 100644 index 0000000..ad95d14 --- /dev/null +++ b/content/documentation-new/extensions/mod_resolver.adoc @@ -0,0 +1,131 @@ +: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 dynamic resolution mechanism, which 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 7, so it can be used with Java 7 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 +PropertyFilter+ 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 but powerful 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. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8951b7be/content/documentation-new/extensions/mod_resources.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_resources.adoc b/content/documentation-new/extensions/mod_resources.adoc new file mode 100644 index 0000000..2e06053 --- /dev/null +++ b/content/documentation-new/extensions/mod_resources.adoc @@ -0,0 +1,167 @@ +:jbake-type: page +:jbake-status: published + += Apache Tamaya - Extension: Resources + +[[Resources]] +== Tamaya Resources (Extension Module) + +Tamaya _Resources_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. + + +=== What functionality this module provides ? + +Tamaya _Resources_ defines some additional tools to locate resources in your classpath or file system based on +descriptive ant-styled resource patterns. + + +=== Compatibility + +The module is based on Java 7, so it can be used with Java 7 and beyond. + + +=== Installation + +To use this module add the following dependency: + +[source, listing, subs="verbatim,attributes"] +----------------------------------------------- +<dependency> + <grooupId>org.apache.tamaya.ext</groupId> + <artifactId>tamaya-resources</artifactId> + <version>{tamaya_version}</version> +</dependency> +----------------------------------------------- + + +=== Usage + +The module's main entry point is the singleton class +org.apache.tamaya.resource.ConfigResources+. This class +provides access to a +ResourceResolver+ instance: + +[source,java] +----------------------------------------------- +ResourceResolver resolver = ConfigResources.getResourceResolver(); +----------------------------------------------- + +[source,java] +----------------------------------------------- +public interface ResourceResolver { + Collection<URL> getResources(Collection<String> expressions) {...} + Collection<URL> getResources(String... expressions) {...} + Collection<URL> getResources(ClassLoader classLoader, String... expressions){...} + Collection<URL> getResources(ClassLoader classLoader, Collection<String> expressions); +} +----------------------------------------------- + +Hereby the methods allow to resolve expressions to a collection of URLs. In case the expression is also targeting the +current classpath the target +ClassLoader+ to be used can be passed additionally. + +The default implementation provides resource resolution mechanism similar to the functionality offered by Spring. +So by default resources can be looked up + +* from files +* from the classpath +* optionally ant-styled expressions can be used. + + +=== Examples + +There are numerous ways how a resource pattern can be defined. Following the most important variants +are listed: + +[source,listing] +----------------------------------------------- +// explicitly searching the file system +file:myroot/aa?a/*.file +file:myroot/b*/b?/*.file +file:myroot/**/*.file + +// explicitly searching the classpath +classpath:myroot/**/*.file +classpath:javax/annotation/*.class +classpath:javax/**/sql/*.class +classpath:javax/annotation/**/R*.class +classpath:javax/annotation/R?so*.class +classpath:META-INF/maven/org.apache.geronimo.specs/**/* + +// search both classpath and files +javax/annotation/*.class +javax/**/sql/*.class +javax/annotation/**/R*.class +javax/annotation/R?so*.class +META-INF/maven/org.apache.geronimo.specs/**/* +myroot/**/*.file +myroot/aa?a/*.file +myroot/b*/b?/*.file +----------------------------------------------- + +Summarizing the resources module provides useful functionality that helps to locate resources on the file system and +in the classpath. This can be used to implement +PropertySourceProvider+ implementations that are based on +corresponding resource path patterns instead of concrete files. + + +=== Overall Usage Example + +Given the functionality we can easily implement a +PropertySourceProvider+ that reads all files from a classpath +location, hereby traversing down all folders: + + +[source, java] +------------------------------------------------------------- +public class PathBasedPropertySourceProvider implements PropertySourceProvider { + + @Override + public Collection<PropertySource> getPropertySources() { + List<PropertySource> propertySources = new ArrayList<>(); + Collection<URL> resources = ConfigResources.getResourceResolver().getResources("META-INF/cfg/**/*.properties"); + for(URL url:resources){ + Properties props = new Properties(); + try(InputStream is = url.openStream()){ + props.load(is); + propertySources.add(new PropertiesBasedPropertySource(url.toString(), props)); + } + catch(Exception e){ + e.printStackTrace(); + } + } + + return propertySources; + } + + private final static class PropertiesBasedPropertySource implements PropertySource { + private String name; + private Map<String,String> properties = new HashMap<>(); + + public PropertiesBasedPropertySource(String name, Properties props) { + this.name = name; + props.forEach((k,v) -> this.properties.put(k.toString(), v.toString())); + } + + @Override + public String getName() { + return name; + } + + @Override + public String get(String key) { + return properties.get(key); + } + + @Override + public Map<String, String> getProperties() { + return properties; + } + } +} +------------------------------------------------------------- + + +=== SPI + +The +ResourceResolver+ that is returned by the +ConfigResources+ singleton is determined by the +current +ServiceContext+, by default you can replace the default implementation by registering an +alternate implementation with an overriding +@Priority+ annotation added using the +ServiceLoader+. + +Additionally a +BaseResourceResolver+ class can be used to reduce the amount of code to be written +on your own. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8951b7be/content/documentation-new/extensions/mod_server.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_server.adoc b/content/documentation-new/extensions/mod_server.adoc new file mode 100644 index 0000000..52081b6 --- /dev/null +++ b/content/documentation-new/extensions/mod_server.adoc @@ -0,0 +1,239 @@ +:jbake-type: page +:jbake-status: published + += Apache Tamaya - Extension: Configuration Server + +toc::[] + + +[[Server]] +== Tamaya Configuration Server (Extension Module) + +Tamaya _Server_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. + + +=== What functionality this module provides ? + +The Tamaya _Server_ module provides support for providing scoped configuration using a http server serving JSON formatted +configuration properties. + + +=== Compatibility + +The module is based on Java 7, so it will not run on Java 7 and beyond. + + +=== Installation + +To benefit from configuration server support you only must add the corresponding dependency to your module: + +[source, xml] +----------------------------------------------- +<dependency> + <groupId>org.apache.tamaya.ext</groupId> + <artifactId>tamaya-server</artifactId> + <version>{tamaya_version}</version> +</dependency> +----------------------------------------------- + + +=== Providing configuration using the Tamaya Built-in Configuration Server + +The most simple way for providing configuration is to start the internal server: + +[source, java] +----------------------------------------------- +// using context path: '/', port 8085 +org.apache.tamaya.server.Server.start(); + +// optionally pass the root context path and/or port: +// org.apache.tamaya.server.Server.start(8088); +// org.apache.tamaya.server.Server.start("/appconf", 7787); +----------------------------------------------- + +This will start a simple server instance that serves the following URL patterns: + +* +GET ${CONTEXT}/config+ provides access to the full configuration tree. +* +GET ${CONTEXT}/config/filtered/${path}+ let you filter the configuration returned using regular expression (comma separated). + E.g. +${CONTEXT}/config/filtered/java,sun+ will return all configuration entries starting with _java_ and _sun_. + +Additionally the server module has the following options implemented, which can be passed as additional, optional +parameters: + +* +format+ allows to define the target format. By default the +ACCEPT+ header of the http request is checked, but this + setting can be explicitly controlled by passing this parameter explicitly. The value is the expected MIME type to be + returned. By default the service supports the following types: + ** text/html + ** text/plain + ** application/xml + ** application/json + + +=== Using the Configuration Servlets + +You can also register a servlet, e.g. as follows; + +---------------------------------------------------------- +<servlet> + <servlet-name>config-servlet</servlet-name> + <servlet-class>org.apache.cxf.jaxrs.servlet.CXFNonSpringJaxrsServlet</servlet-class> + <init-params> + <init-param key="javax.ws.rs.Application">org.apache.tamaya.server.Server$ResourceLoader</init-param> + </init-params> +</servlet> +---------------------------------------------------------- + + +==== Formatting used by Default + +The server module formats the configuration returned by default in the following variants: + +.Formatting for +text/json+ + +[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" +} +----------------------------------------------- + + +.Formatting for +application/xml+ + +[source, xml] +----------------------------------------------- +<configuration> + <entry key="java.vendor.url">http://java.oracle.com/</entry> + <entry key="java.vendor.url.bug">http://bugreport.sun.com/bugreport/</entry> + <entry key="java.vm.info">mixed mode</entry> + <entry key="java.vm.name">Java HotSpot(TM) 64-Bit Server VM</entry> + <entry key="java.vm.specification.name">Java Virtual Machine Specification</entry> + <entry key="java.vm.specification.vendor">Oracle Corporation</entry> + <entry key="java.vm.specification.version">1.8</entry> + <entry key="java.vm.vendor">Oracle Corporation</entry> + <entry key="java.vm.version">25.45-b02</entry> + <entry key="sun.arch.data.model">64</entry> + <entry key="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</entry> + <entry key="sun.boot.library.path">C:\apps\jdk18\jre\bin</entry> + <entry key="sun.cpu.endian">little</entry> + <entry key="sun.cpu.isalist">amd64</entry> + <entry key="sun.desktop">windows</entry> + <entry key="sun.io.unicode.encoding">UnicodeLittle</entry> + <entry key="sun.java.command">com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start</entry> + <entry key="sun.java.launcher">SUN_STANDARD</entry> + <entry key="sun.jnu.encoding">Cp1252</entry> + <entry key="sun.management.compiler">HotSpot 64-Bit Tiered Compilers</entry> + <entry key="sun.os.patch.level"></entry> + <entry key="_class">org.apache.tamaya.functions.FilteredConfiguration</entry> + <entry key="_info.filter">java.v,sun</entry> + <entry key="_info.format">application/xml</entry> + <entry key="_info.timestamp">1441463383687</entry> + <entry key="_timestamp">1441463383687</entry> + <entry key="_type">Configuration</entry> +</configuration> +----------------------------------------------- + + +.Formatting for +text/plain+ + +[source, text] +----------------------------------------------- + +Configuration: + 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: text/plain, + _info.timestamp: 1441463082020, + _timestamp: 1441463082021, + _type: Configuration +----------------------------------------------- + + +.Formatting for +application/html+ + +[source, html] +----------------------------------------------- +<html> +<head><title>System Configuration</title></head> +<body> +<h1>Sysem Configuration</h1> +<p>This view shows the system configuration of devbox-win at Sat Sep 05 16:30:59 CEST 2015.</p><pre> +Configuration: + 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: text/html, + _info.timestamp: 1441463459653, + _timestamp: 1441463459654, + _type: Configuration +</pre> +</body> +</html> +----------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8951b7be/content/documentation-new/extensions/mod_spring.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_spring.adoc b/content/documentation-new/extensions/mod_spring.adoc new file mode 100644 index 0000000..798431b --- /dev/null +++ b/content/documentation-new/extensions/mod_spring.adoc @@ -0,0 +1,176 @@ +:jbake-type: page +:jbake-status: published + += Apache Tamaya - Extension: Spring Integration + +toc::[] + + +[[Spring]] +== Tamaya Spring Integration (Extension Module) + +Tamaya _Spring_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. + + +=== What functionality this module provides ? + +Tamaya _Spring_ currently provides full integration with Spring and Spring Boot: + +* A Spring +@Configuration+ implementation that also provides a Tamaya based version of + +org.springframework.context.support.PropertySourcesPlaceholderConfigurer+. +* +org.apache.tamaya.integration.spring.TamayaEnvironment+ is the Tamaya based implementation of the Spring + +Environment+ interface. +* +TamayaSpringPropertySource+ implements an additional Spring +PropertySource+. +* Finally +org.apache.tamaya.integration.spring.SpringConfigInjectionPostProcessor+ implements a Bean +PostProcessor+, + which adds all the fully fledged Tamaya configuration capabilities to Spring. + + +=== Compatibility + +Both modules are based on Java 8, so they will run on Java 8 and beyond. The extension shown here works in +Spring Framework as well as Spring Boot. + + +=== Installation + +To benefit from Tamaya Spring integration add the following dependencies to your module: + +[source, xml] +----------------------------------------------- +<dependency> + <groupId>org.apache.tamaya.ext</groupId> + <artifactId>tamaya-spring</artifactId> + <version>{tamaya_version}</version> +</dependency> +----------------------------------------------- + + +=== Registering Tamaya Spring Configuration + +Basically to activate the Tamaya Spring support the most simple thing is to a enable the Tamaya package for being +scanned for Spring components, e.g. using by annotation: + +[source, java] +-------------------------------------------------------- +@SpringBootApplication +@ComponentScan({"org.apache.tamaya.integration.spring"}) +public class SampleWebFreeMarkerApplication { + + public static void main(String[] args) throws Exception { + SpringApplication.run(SampleWebFreeMarkerApplication.class, args); + } + +} +-------------------------------------------------------- + +Of course, you can still use Spring's XML configuration in a similar way: + +[source, xml] +-------------------------------------------------------- +<beans xmlns="http://www.springframework.org/schema/beans"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xmlns:context="http://www.springframework.org/schema/context"; + xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd";> + + <context:annotation-config /> + <context:component-scan base-package="org.apache.tamaya.integration.spring"/> + + ... + +</beans> +-------------------------------------------------------- + + +Though not recommended you can explicitly register the Tamaya related beans in your context configuration by hand: +files: + +[source, xml] +-------------------------------------------------------- +<bean id="tamayaInjectionProcessor" name="tamayaInjectionProcessor" class="org.apache.tamaya.integration.spring.SpringConfigInjectionPostProcessor"/> +<bean id="tamayaConfigProvider" name="tamayaConfigProvider" class="org.apache.tamaya.integration.spring.TamayaSpringConfig"/> +-------------------------------------------------------- + + +=== Configuring your Context + +After activation you can use Tamaya as a backend for property resolution, e.g. +propertyValue+ +is resolved from the current Tamaya configuration. See example below: + +[source, xml] +-------------------------------------------------------- +<bean id="configuredBean" name="configuredBean" class="org.apache.tamaya.integration.spring.ConfiguredSpringBean"> + <property name="message" value="${propertyValue}"/> +</bean> +-------------------------------------------------------- + + +=== Configuring your Beans + +Similarly you can inject any kind of configuration as supported by Tamaya into your Spring managed beans: + +[source, java] +-------------------------------------------------------- +@ConfigDefaultSections("app.root") // optional <1> +@Component +public class ConfiguredSpringBean { + + @Value("${application.message:Hello World}") <2> + private String message; + + @Autowired + private Environment env; + + @Config(value = "alternateMessage", required = false) <3> + private String anotherMessage = "N/A"; + + @Config("java.version") + private String javaVersion; + + @Config(value={"number", "testNum", "[notavailable]"}, defaultValue="23") <4><5> + private int testNumber; + + ... +} +-------------------------------------------------------- + +<1> You can configure default section prefixes. This is an optional feature. +<2> Tamaya does not require you to change your code. You can still work with + Spring injection for your configuration, but Tamaya will override Spring + configuration by default. +<3> You can also define entries as optional, which allows you to perform + default inialization using Java idoms. +<4> Tamaya allows you to define an ordered list of key candidates, which are + combined with the section prefix, if present, to the full keys. Keys added + in brackets ([]) are interpreted as absolute keys, so the example above + the key candidate list evaluates to +app.root.number", "app.root.testNum", + "notavailable"+. +<5> You can configure default values used, if no other value can be evaluated + for the given keyset. + +Summarizing you get all the nice features of Tamaya out of the box running +with your Spring code. + +=== Working with Dynamic Values + +Integration into Spring also includes for support for _dynamic values_: + +[source, java] +-------------------------------------------------------- +@Config(value = "foreground.color", required = false, defaultValue = "#DDDDDD") +private DynamicValue<Color> foregroundColor; +-------------------------------------------------------- + +Dynamic values are a very flexible mechanism for managing configuration changes. +You can even use an update policy to define how you want to handle configuration +changes for your configuration parameter: + +[source, java] +-------------------------------------------------------- +foregroundColor.setUpdatePolicy(UpdatePolicy.IMMEDEATE); +foregroundColor.addPropertyChangeListener(() -> { + System.out.println("New forground color: " + foregroundColor.get(); +}); +-------------------------------------------------------- + +IMPORTANT: For a full description of Tamaya's injection API please + refer to the link:extensions/mod_injection.html[corresponding documentation]. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8951b7be/content/documentation-new/extensions/mod_usagetracker.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_usagetracker.adoc b/content/documentation-new/extensions/mod_usagetracker.adoc new file mode 100644 index 0000000..e0bd8c7 --- /dev/null +++ b/content/documentation-new/extensions/mod_usagetracker.adoc @@ -0,0 +1,161 @@ +:jbake-type: page +:jbake-status: published + += Apache Tamaya - Extension: Usage Tracking + +toc::[] + + +[[UsageTracker]] +== Tamaya Usage Tracking (Extension Module) + +Tamaya _UsageTracker_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. + + +=== What functionality this module provides ? + +Tamaya _UsageTracker_ allows to record and count the configuration access and consumer locations in your local +VM. + + +=== Compatibility + +The module is based on Java 7, so it can be used with Java 7 and beyond. + + +=== Installation + +To use Tamaya _usagetracker_ you only must add the corresponding dependency to your module: + +[source, xml] +----------------------------------------------- +<dependency> + <groupId>org.apache.tamaya.ext</groupId> + <artifactId>tamaya-usagetracker</artifactId> + <version>{tamaya_version}</version> +</dependency> +----------------------------------------------- + + +=== 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). + +[source,java] +----------------------------------------------------------- +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: + +[source,java] +----------------------------------------------------------- +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 Stacktrace 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): + +[source,listing] +----------------------------------------------------------- +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 + +----------------------------------------------------------- + + +=== 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). + + +== UsageTracker Module SPI + +=== 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. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8951b7be/content/documentation-new/extensions/mod_validation.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_validation.adoc b/content/documentation-new/extensions/mod_validation.adoc new file mode 100644 index 0000000..5b239cb --- /dev/null +++ b/content/documentation-new/extensions/mod_validation.adoc @@ -0,0 +1,104 @@ +:jbake-type: page +:jbake-status: published + += Apache Tamaya - Extension: Configuration Validation + +toc::[] + + +[[Validation]] +== Tamaya Validation: Validating Configuration (Extension Module) + +Tamaya _Validation_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. + + +=== Overview + +Tamaya _Validation_ adds support to validate a configuration against a set of rules +defined in a Tamaya Metaconfiguration XML file. + + +=== Compatibility + +The module is based on Java 7, so it will run on Java 7 and beyond. + + +=== Installation + +To activate configuration _validation_ you only must add the corresponding dependency to your module: + +[source, xml] +----------------------------------------------- +<dependency> + <groupId>org.apache.tamaya.ext</groupId> + <artifactId>tamaya-validation</artifactId> + <version>{tamaya_version}</version> +</dependency> +----------------------------------------------- + +The component will extend Tamaya's +tamaya-metamodel+ module and adds an additional meta provider ruleset +so validation rules can also be added to the default meta configuration XML file as separate sections. + + +=== Usage + +This module expects meta-configuration to be located at the following locations. Hereby multiple files +are supported: + +[source, text] +----------------------------------------------- +-Dtamaya-validation=<an URL> // any resolvable URL +./tamaya-validation-*.xml // file +META-INF/tamaya-validation-*.xml // classpath (multiple entries-possible) +----------------------------------------------- + + +=== The Validation XML Format + +The configuration validation is defined by simple configuration meta-data entries. + +[source, xml] +----------------------------------------------- +<configuration-validation> + ... + <provider>The Validation Provider</provider> <!-- optional --> + <section name="org.mycompany"> + <section name="security" required="true"> + <description>The description of ma area.</description> + </section> + </section> + <section name="minimal"/> + <section name="validated.sections" at-least="1"> + <section name="customValidated" validator="myFQValidatorClassName"/> + <section name="withParams" > + <param name="int" type="int"/> + <param name="aText" expression="[a|b|c]" required="true"/> + <param name="aValidatedText" validator="myValidatorClass"> + <description>This kind of params are more complex...</description> + </param> + </section> + </section> + <validator class="a,b,c,MyGlobalValidator"/> +</configuration-validation> +----------------------------------------------- + + +==== The Example Explained + +* The *provider* entry is used for generating validation message, when a validation fails. +* Section itself can be recursively defined, where each level can have it's own validations. +* Sections added, but without validation rules are _defined_ section. Configuration outside of + defined sections can be flagged out using WARNING messages. +* Sections can be _reuired_ and additionally also _validated_. +* There is also the possibility to register global validators, which are called by the validation + logic once a configuration has been completely loaded. + +Similar to sections also parameters can be validated: + +* they can be marked as _required_ +* they can have a certain type, meaning they must be convertible to the given type +* they can have an additional custom validator. +* they can have an optional description for error analysis and error output. + +Similar to section parameters that are not defined, but encountered may be flagged out with +a WARNING message. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8951b7be/content/documentation-new/extensions/mod_vertx.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_vertx.adoc b/content/documentation-new/extensions/mod_vertx.adoc new file mode 100644 index 0000000..eef576b --- /dev/null +++ b/content/documentation-new/extensions/mod_vertx.adoc @@ -0,0 +1,188 @@ +:jbake-type: page +:jbake-status: published + += Apache Tamaya - Extension: Integration for Vertx + +toc::[] + + +[[JNDI]] +== Integration with Vertx (Extension Module) +Tamaya _JNDI_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. + +=== What functionality this module provides ? + +Tamaya _Vertx_ provides configuration services that can be used in a Vertx environment: + +* +AbstractConfiguredVerticle+ defines a subclass extending +AbstractVerticle+, which allows you to + use Tamaya Injection API. +* Additionally you deply a +ConfigVerticle+, which registers services to access configuration + using asynchronous event bus. + + +=== Compatibility + +The module requires Java 8, so it will not run on Java 7. + + +=== Installation + +To use Tamaya's _Vertx_ support you only must add the corresponding dependency to +your module: + +[source, xml] +----------------------------------------------- +<dependency> + <groupId>org.apache.tamaya.ext</groupId> + <artifactId>tamaya-vertx-alpha</artifactId> + <version>{tamaya_version}</version> +</dependency> +----------------------------------------------- + + +=== The Functionality Provided + +NOTE: This module is in alpha state. Please give feedback via our JIRA, so we can improve it. + + +==== Extending AbstractConfiguredVerticle + +Main artifact is the +AbstractConfiguredVerticle+ class, which implements a +base verticle class for Vertx: + +[source, java] +----------------------------------------------- +public abstract class AbstractConfiguredVerticle extends AbstractVerticle{ + + private Configuration configuration; + + public AbstractConfiguredVerticle() { + configure(); + } + + public Configuration getConfiguration(){ + if(this.configuration==null){ + this.configuration = ConfigurationProvider.getConfiguration(); + } + return this.configuration; + } + + public void setConfiguration(Configuration configuration){ + this.configuration = configuration; + configure(); + } + + protected void configure(){ + ConfigurationInjection.getConfigurationInjector().configure(this, getConfiguration()); + } + + protected final String getConfigProperty(String key); + protected final String getConfigPropertyOrDefault(String key, String defaultValue); + protected final <T> T getConfigProperty(String key, Class<T> type); + protected final <T> T getConfigPropertyOrDefault(String key, Class<T> type, T defaultValue); +} +----------------------------------------------- + +Using this verticle as a superclass, provides you + +* embedded convenience methods for programmatic configuration access (+getConfigProperty*+ methods). +* support for configuration injection based on link:../mod_injection.html[Tamaya's injection API]. + + +The following code snippet gives you an example, what you can do with this functionality: + +[source, java] +----------------------------------------------- +public cllass MyVerticle extends AbstractConfiguredVerticle{ + + @Override + public void start(){ + String configuredValue = getConfigPropertyOrDefault("myKey"); + [...] + BigDecimal bd = getConfigureddPropertyOrDefault("MyNum", BigDecimal.ZERO); + [...] + } +} +----------------------------------------------- + + +As menioned you can also use the injection API: + +[source, java] +----------------------------------------------- +public cllass MyVerticle extends AbstractConfiguredVerticle{ + + @Config("myKey") + private String configuredValue; + + @Config(value="MyNum", defaultValue="0.0") + private BigDecimal bd; + + + @Override + public void start(){ + [...] + } +} +----------------------------------------------- + + +==== Accessing Configuration using the Vertx event bus + +Additionally the extension allows to access configuration values from the event bus: + +[source, java] +----------------------------------------------- +@Override +public void start(){ + // the selector allows to apply a regex on the configuration key to select a + // a configuration sub set. + String selector = "user."; + vertx().eventBus().send( + "CONFIG-MAP", // event bus address + selector, + new Handler<AsyncResult<Message<String>>>() { + @Override + public void handle(AsyncResult<Message<String>> reply) { + testContext.assertNotNull(reply.result()); + testContext.assertNotNull(reply.result().body()); + Map<String,String> config = Json.decodeValue(reply.result().body(), + Map.class); + // do something with the config + // ... + } + }); +----------------------------------------------- + + +Similar only single values can be accessed: + +[source, java] +----------------------------------------------- +@Override +public void start(){ + vertx().eventBus().send( + "CONFIG-VAL", // event bus address + "user.home", // property key + new Handler<AsyncResult<Message<String>>>() { + @Override + public void handle(AsyncResult<Message<String>> reply) { + String value = reply.result().body(); + // do something with the config value + // ... + } + }); +----------------------------------------------- + + +Finally the event bus targets to be used can be configured using Tamaya configuration, +see the code snippet from the implementation: + +[source, java] +----------------------------------------------- +@Config(value = "tamaya.vertx.config.map", defaultValue = "CONFIG-MAP") +private String mapBusTarget; + +@Config(value = "tamaya.vertx.config.value", defaultValue = "CONFIG-VAL") +private String valBusTarget; +----------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8951b7be/content/documentation-new/extensions/mod_yaml.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_yaml.adoc b/content/documentation-new/extensions/mod_yaml.adoc new file mode 100644 index 0000000..ceef59a --- /dev/null +++ b/content/documentation-new/extensions/mod_yaml.adoc @@ -0,0 +1,118 @@ +:jbake-type: page +:jbake-status: published + += Apache Tamaya - Extension: Builder + +toc::[] + + +[[YAML]] +== Tamaya YAML (Extension Module) + +Tamaya _YAML_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. + + +=== Overview + +Tamaya _YAML_ provides support for reading configuration using the YAML format (yaml.org). YAML hereby +use intendation for expressing hierarchy, which makes yaml configuration files very easily readable and compact. + + +=== Compatibility + +The YAML module is based on Java 7, so it will run on Java 7 and beyond. + + +=== Installation + +To use YAML as configuration format you must add the corresponding dependency to your module: + +[source, xml] +----------------------------------------------- +<dependency> + <groupId>org.apache.tamaya.ext</groupId> + <artifactId>tamaya-yaml</artifactId> + <version>{tamaya_version}</version> +</dependency> +----------------------------------------------- + +This extension also transitively requires the +tamaya.formats+ module. + + +=== Reading configuration in YAML + +For reading YAML based onfiguration most easily a +YAMLFormat+ can be provided: + +[source, java] +----------------------------------------------- +PropertySource ps = ConfigurationFormats.createPropertySource( + getClassLoader().getResource("myFileConfig.yaml"), new YAMLFormat())); +----------------------------------------------- + + +=== Examples + +The YAML module adds instances of +ConfigurationFormat+ so YAML configuration can be read and mapped to the +according property values. E.g. the following file is a simple and correct YAML configuration: + +[source,yaml] +---------------------------------------------------------------- +invoice: 34843 +date : 2001-01-23 +bill-to: &id001 + given : Chris + family : Dumars + address: + lines: | + 458 Walkman Dr. + Suite #292 + city : Royal Oak + state : MI + postal : 48046 +ship-to: *id001 +product: + - sku : BL394D + quantity : 4 + description : Basketball + price : 450.00 + - sku : BL4438H + quantity : 1 + description : Super Hoop + price : 2392.00 +tax : 251.42 +total: 4443.52 +comments: + Late afternoon is best. + Backup contact is Nancy + Billsmer @ 338-4338. +---------------------------------------------------------------- + +Hereby the above file, by default is mapped as follows into +Map<String,String>+ typed properties: + +[source,listing] +---------------------------------------------------------------- +invoice -> 34843 +date -> Tue Jan 23 01:00:00 CET 2001 +bill-to.family -> Dumars +bill-to.given -> Chris +bill-to.address.state -> MI +bill-to.address.postal -> 48046 +bill-to.address.city -> Royal Oak +bill-to.address.lines -> 458 Walkman Dr. +Suite #292 + +ship-to.given -> Chris +ship-to.address.state -> MI +ship-to.family -> Dumars +ship-to.address.postal -> 48046 +ship-to.address.city -> Royal Oak +ship-to.address.lines -> 458 Walkman Dr. +Suite #292 + +product -> {sku=BL394D, quantity=4, description=Basketball, price=450.0},{sku=BL4438H, quantity=1, description=Super Hoop, price=2392.0} +_product.collection-type -> List + +tax -> 251.42 +total -> 4443.52 +comments -> Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338. +----------------------------------------------------------------
