* @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 );

     :
     :
 }