org.qi4j.api.configuration

## Interface Configuration<T>

- All Known Subinterfaces:
    FileEntityStoreService, HazelcastEntityStoreService, JCloudsMapEntityStoreService, JdbmEntityStoreService, LevelDBEntityStoreService, MemcacheConfiguration, MongoMapEntityStoreService, RedisMapEntityStoreService, RiakMapEntityStoreService
  All Known Implementing Classes:
    Configuration.ConfigurationMixin

      @Mixins(value=Configuration.ConfigurationMixin.class)
      public interface Configuration<T>

  Provide Configurations for Services. A Service that wants to be configurable should inject a reference to Configuration with the Configuration type:

        * @This Configuration<MyServiceConfiguration> config;

  where MyServiceConfiguration extends `ConfigurationComposite`, which itself is an ordinary `EntityComposite`. The Configuration implementation will either locate an instance of the given Configuration type in the persistent store using the identity of the Service, or create a new such instance if one doesn't already exist.

  If a new Configuration instance is created then it will be populated with properties from the properties file whose filesystem name is the same as the identity (e.g. "MyService.properties"). If a service is not given a name via the `org.qi4j.bootstrap.ServiceDeclaration#identifiedBy(String)`, the name will default to the FQCN of the ServiceComposite type.

  The Configuration instance can be modified externally just like any other EntityComposite, but its values will not be updated in the Service until `refresh()` is called. This allows safe reloads of Configuration state to ensure that it is not reloaded while the Service is handling a request.

  The Configuration will be automatically refreshed when the Service is activated by the Zest runtime. Any refreshes at other points will have to be done manually or triggered through some other mechanism.

  The user configuration entity is part of a long running `UnitOfWork`, and to persist changes to it the `save()` method must be called. No other actions are required. Example;

       public interface MyConfiguration extends ConfigurationComposite
       {
           Property<Long> timeout();
       }

       :

       @This Configuration<MyConfiguration> config;
       :
       private void setTimeoutConfiguration( long timeout )
       {
           config.get().timeout().set( timeout );
           config.save();
       }

  And even if a separate thread is using the `timeout()` configuration when this is happening, the `UnitOfWork` isolation will ensure that the other thread is not affected. That thread, on the other hand will need to do a `refresh()` at an appropriate time to pick up the timeout change. For instance;

       @Service InventoryService remoteInventoryService;

       public void restockInventoryItem( InventoryItemId id, int itemCount )
       {
           config.refresh();
           long timeout = config.get().timeout().get();

           remoteInventoryService.restock( id, itemCount, timeout );

           :
           :
       }

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `Configuration.ConfigurationMixin<T>` Implementation of Configuration.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `T` | `get()` Retrieves the user configuration instance managed by this Configuration.
    `void` | `refresh()` Updates the values of the managed user ConfigurationComposite instance from the underlying `org.qi4j.spi.entitystore.EntityStore`.
    `void` | `save()` Persists the modified values in the user configuration instance to the underlying store.

- - ### Method Detail

    - #### get

          T get()

      Retrieves the user configuration instance managed by this Configuration.

      Even if the user configuration is initialized from properties file, the consistency rules of Zest composites still applies. If the the properties file is missing a value, then the initialization will fail with a RuntimeException. If Constraints has been defined, those will need to be satisfied as well. The user configuration instance returned will fulfill the constraints and consistency normal to all composites, and can therefor safely be used with additional checks.

      Returns:
        The fully initialized and ready-to-use user configuration instance.

    - #### refresh

          void refresh()

      Updates the values of the managed user ConfigurationComposite instance from the underlying `org.qi4j.spi.entitystore.EntityStore`. Any modified values in the current user configuration that has not been saved, via `save()` method, will be lost.

    - #### save

          void save()

      Persists the modified values in the user configuration instance to the underlying store.