Repository: incubator-tamaya-site Updated Branches: refs/heads/master e6c7fd4e0 -> c934f2f86
Updated extension documentation. Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/commit/db487e26 Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/db487e26 Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/db487e26 Branch: refs/heads/master Commit: db487e2647f1746b4a4d9d59ac43f4292fa53223 Parents: e6c7fd4 Author: anatole <[email protected]> Authored: Tue Jan 24 01:07:09 2017 +0100 Committer: anatole <[email protected]> Committed: Tue Jan 24 01:07:09 2017 +0100 ---------------------------------------------------------------------- .../documentation/extensions/mod_events.adoc | 101 +++++++++++++------ 1 file changed, 69 insertions(+), 32 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/db487e26/content/documentation/extensions/mod_events.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_events.adoc b/content/documentation/extensions/mod_events.adoc index 030d52b..512be62 100644 --- a/content/documentation/extensions/mod_events.adoc +++ b/content/documentation/extensions/mod_events.adoc @@ -32,6 +32,21 @@ To benefit from configuration event support you only must add the corresponding </dependency> ----------------------------------------------- +=== What does this module do? + +The Tamaya _events_-extension provides a mechanism to publish and subscribe to +ConfigEvent<T>+ instances. +This module implements +ConfigChange+ or +PropertySourceChange+ as possible payloads, but +the module itself is not constraint to this payload types. +These payload types describe detected changes of key/values of a +Configuration+ or a +PropertySource+. +The extension also provides a _Singleton accessor_ which allows to register/unregister +listeners for changes and the period, when configuration should be scanned for +any changes. + +Summarizing with the events module you can easily observe configuration changes, record the +state of any configuration and compare configuration states to create and publish related +change events. + + === Core Architecture The core of the module are the +ConfigEventListener+ interface and the +ConfigEvent+ class, which defines an abstraction @@ -56,23 +71,37 @@ public interface ConfigEventListener { } -------------------------------------------- -This mechanism can now be used to propagate configuration changes to all interested stakeholders. Hereby the payload -can be basically arbitrary as long as it implements the +ConfigEvent+ interface. The next sections -give more details on the the provided event types and their usage. +Hereby the payload _T_ can be basically of an arbitrary type as long as +it implements the +ConfigEvent+ interface. The next sections +give more details on the the event types provided by this extension +and their usage. + +Also the technology to be used for publishing these event types is adaptable. +In SE the module uses a simple in-memory implementation based on the +Google _Guava_ library. But users can replace this mechanism as needed. For +more details refer to the SPI section later in this guide. + +=== Modelling Changes -=== Modelling Configuration Changes +This module provides a serializable and thread-safe abstraction modelling a +configuration change, which is anything of the following -This module provides a serializable and thread-safe abstraction modlling a configuration change. A change hereby may -be +* additional, _new_ configuration entries +* _removed_ configuration entries +* _changes_ on existing entries -* additional configuration entries -* removed configuration entries -* changes on entries +A collection of changes -The most important event modelled is the +ConfigurationChange+ class, which implements the event sent for a changed -+Configuration+: +* on a +Configuration+ is modelled by the +ConfigurationChange+ class +* on a +PropertySource+ is modelled by the +PropertySourceChange+ class + + +==== Configuration Changes + +A set of changes on a +Configuration+ is described by a +ConfigurationChange+ +as follows: [source,java] ------------------------------------------------------- @@ -106,7 +135,8 @@ public final class ConfigurationChange implements ConfigEvent<Configuration>, Se ------------------------------------------------------- -New instances of this class hereby can be created using a fluent builder: +New instances of +ConfigurationChange+ hereby can be created using a +fluent +ConfigurationChangeBuilder+: [source,java] ------------------------------------------------------- @@ -116,8 +146,9 @@ ConfigurationChange change = ConfigurationChangeBuilder.of(config) .removeKeys("myRemovedKey").build(); ------------------------------------------------------- -Also it is possible to directly compare 2 instances of configurations to create +ConfigurationChange+ that -reflect the differences between the two configurations: +Also it is possible to directly compare 2 instances of +Configuration+, +which results in a +ConfigurationChange+ that +reflects the differences between the two configurations passed: [source,java] Comparing 2 configurations @@ -128,20 +159,21 @@ ConfigurationChange change = ConfigurationChangeBuilder.of(config) .addChanges(changedConfig).build(); ------------------------------------------------------- -So a +ConfigurationChange+ allows you to evaluate the changes on a configuration. This allows you to listen to changes -and react in your client code as useful, once you encounter changes that are relevant to you, e.g. by reconfiguring -your component. For listening to configuration changes you must implement the +So a +ConfigurationChange+ describes all the changes detected on a +Configuration+. +This allows you to publish instances of this class as events to all registered +listeners (observer pattern). +For listening to +ConfigurationChange+ events you must implement the +ConfigEventListener+ functional interface: [source,java] .Implementing a ConfigChangeListener ------------------------------------------------------- -public final class MyConfigChangeListener implements ConfigChangeListener<ConfigurationChange>{ +public final class MyConfigChangeListener implements ConfigEventListener<ConfigurationChange>{ private Configuration config = ConfigurationProvider.getConfiguration(); public void onConfigEvent(ConfigEvent<?> event){ - if(event.getResourceTspe()==Configuration.class){ + if(event.getResourceType()==Configuration.class){ if(event.getConfiguration()==config){ // do something } @@ -151,17 +183,24 @@ public final class MyConfigChangeListener implements ConfigChangeListener<Config } ------------------------------------------------------- -You can *register* your implementation in 2 ways: +You can *register* your implementation as illustrated below: . Manually by calling +ConfigEventManager.addListener(new MyConfigChangeListener())+ . Automatically by registering your listener using the +ServiceLoader+ under +META-INF/services/org.apache.tamaya.events.ConfigEventListener+ +Registering programmatically also allows you to define additional constraint, +to filter out all kind of events you are not interested in. + +NOTE: By default detection of configuration changes is not enabled. To enable it, call ++ConfigEventManager.enableChangeMonitoring(true)+. + -=== Modelling PropertySource Changes +=== PropertySource Changes -Beside that a whole configuration changes, also +PropertySource+ instances can change, e.g. by a configuration file -edited on the fly. This is similarly to a +ConfigurationChange+ reflected by the classes +PropertySourceChange, +Beside that a whole +Configuration+ changes, also a +PropertySource+ can change, +e.g. by a configuration file edited on the fly. This is similarly to a ++ConfigurationChange+ reflected by the classes +PropertySourceChange, PropertySourceChangeBuilder+. @@ -170,9 +209,9 @@ PropertySourceChangeBuilder+. Main entry point of the events module is the +ConfigEventManager+ singleton class, which provides static accessor methods to the extension's functionality: -* Adding/removing of +ConfigChangeListener+ instances, either globally or per event type. -* Firing configuration events synchronously or asyncronously (mostly called by framework code). -* Configuring the monitor that periodically checks for changes on the global +Configuration+ provided +* _Adding/removing_ of +ConfigChangeListener+ instances, either globally or per event type. +* _Firing configuration events_ synchronously or asyncronously (mostly called by framework code). +* _Configuring the monitor_ that periodically checks for changes on the global +Configuration+ provided by +ConfigurationProvider.getConfiguration()+. [source,java] @@ -245,10 +284,10 @@ PropertySource frozenSource = FrozenPropertySource.of(propertySource); === SPIs -This component also defines an additional SPI, which allows to adapt the implementation of the main +ConfigEventManager+ +This component also defines SPIs, which allows to adapt the implementation of the main +ConfigEventManager+ singleton. This enables, for example, using external eventing systems, such as CDI, instead of the default provided -simple SE based implementation. As normal, implementation must be registered using the current +ServiceContext+ -active, by default using the Java +ServiceLoader+ mechanism. +simple SE based implementation. By default implementations must be registered using the current +ServiceContext+ +active (by default using the Java +ServiceLoader+ mechanism). [source,java] .SPI: ConfigEventSpi @@ -273,6 +312,4 @@ public interface ConfigEventManagerSpi { -------------------------------------------------- -Summarizing with the events module you can easily observe configuration changes, record the -state of any configuration and compare configuration states to create and publish related -change events. +
