core/api/src/docs/configuration.txt

//////////////////////
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * http://www.apache.org/licenses/LICENSE-2.0
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
 * either express or implied.
 * See the License for the specific language governing permissions
 * and limitations under the License.
//////////////////////

[[core-api-service-configuration,Service Configuration]]
= Service Configuration =
Configuration in Polygene™ is for Polygene™ <<core-api-service>> only. The Configuration is stored in a visible Entity
Store and is therefor runtime modifiable and not static in properties or XML files as in most other dependency
injection frameworks.

The Configuration system itself will handle all the details with interfacing with reading and writing the configuration.
The normal UnitOfWork management is used, but handled internally by the configuration system.

In Polygene, Configuration are strongly typed and refactoring-friendly. Configuration is read from the entity store, but if
it can not be found, then it will try to bootstrap it from the file system, with the same name as the
ServiceDescriptor.identifiedBy(), which is set during <<core-bootstrap-assembly>> and defaults to the fully qualified
classname of the <<core-api-service>> type, followed by an extension dependent on the file type.

The following file types for default configuration is supported (listed in read priority order);

1. Java Properties
2. JSON
3. YAML
4. XML

== Defining a Configuration Type ==
The Configuration type is simply listing the properties that are available. The standard rules on @UseDefaults and
@Optional applies.
Example;

[snippet,java]
--------------
source=core/api/src/test/java/org/apache/polygene/api/configuration/MailServiceConfiguration.java
tag=configuration
--------------

== Default Configuration formats ==
The default configuration read will happen if the Entity Store backing the Configuration system does not contain the
identifiable configuration. That will trigger the reading attempts of the supported configuration formats. Once the
configuration is parsed from the file system it is written to the Entity Store, and if the Entity Store is not
ephemeral, then on the next start, any changes to the configuration will NOT be detected, and will simply be ignored.

To be able to read JSON, YAML and XML configuration, you must configure a Serialization system that supports
the configuration format that you want to use.

* extension/serialization-javaxjson supports JSON
* extension/serialization-javaxxml supports XML

== Support for Complex Types ==
Since the regular Value Serialization platform is used, for JSON, YAML and XML, the configuration can contain
arbitrary composite types. This is not true for the Java properties file format.


== Using a Configuration Type ==
It is important to remember that Configuration is not static values that are set prior to application start-up and
therefor applications should not cache the values retrieved forever, but consciously know when the configuration should
be re-read.

Configuration is injected via the @This injection scope. One reasonable strategy is to read the configuration on service
activation, so by deactivating/reactivating a service, the user have a well-defined behavior to know how configuration
changes take effect. Example;

[snippet,java]
--------------
source=core/api/src/test/java/org/apache/polygene/api/configuration/MailService.java
tag=read
--------------

== Modifying Configuration ==
Configuration is modifiable, and after the modifications have been made, the save() method on the Configuration type
must be called. Example;

[snippet,java]
--------------
source=core/api/src/test/java/org/apache/polygene/api/configuration/MailService.java
tag=write
--------------