To illustrate these features we create an TravelPlan service, which allows clients to find and make Reservations to Destinations. For the sake of simplicity, we are leaving out the domain details…

public interface TravelPlan
{
    // Domain methods, which are beyond the discussion at hand.
}

So, then there is the ServiceComposite…

// The package is relevant to the Initial Values discussed later.
package org.qi4j.manual.travel;
  [...snip...]

@Mixins( { TravelPlanMixin.class } )
public interface TravelPlanService extends TravelPlan, ServiceComposite
{}

And then in the Mixin we actually need to connect to a foreign system to obtain the various details that the service can provide to the clients. For instance, it needs a host name and port and a protocol to use. We put these into a configuration interface.

public interface TravelPlanConfiguration
{
    Property<String> hostName();

    @Range( min=0, max=65535 )
    Property<Integer> portNumber();

    @Matches( "(ssh|rlogin|telnet)" )
    Property<String> protocol();
}

We used the recommended type-safe Property subtype pattern, and for each PortNumber and Protocol we have defined a Constraint required.

Now we can access this configuration in the TravelPlanMixin like this;

import org.qi4j.api.configuration.Configuration;

public class TravelPlanMixin implements TravelPlan
{
    @This
    Configuration<TravelPlanConfiguration> config;

    private void foo()
    {
        TravelPlanConfiguration tpConf = config.get();
        String hostName = tpConf.hostName().get();
        // ...
    }
      [...snip...]

}

And from the Service point of view, it doesn’t need to worry about where the configuration really comes from. But it may want to control when the Configuration should be refreshed, to ensure that atomic changes are happening. This is done with the refresh() method in the Configuration interface;

public void doSomething()
{
    // Refresh Configuration before reading it.
    config.refresh();

    TravelPlanConfiguration tpConf = config.get();
    // ...
}

This ensures that any updates to the Configuration that has occurred will be retrieved and available to the Service. Since Configuration instance is an Entity, the UnitOfWork system will ensure that the Configuration is consistent and not in the middle of value changes.

# Hostname to the TravelPlan service
hostName=niclas.hedhman.org

# Port number to use for the connection
portNumber=5439

# Protocol to use; Valid options "ssh", "rlogin", "telnet"
protocol=ssh

public void assemble(ModuleAssembly module) throws AssemblyException
{
    module.addServices(TravelPlanService.class).instantiateOnStartup();
}

If you need to use multiple instances of the same service, or that the service has a non-default Identity, then you need to name the properties file according to the Identity of the service declaration, but the file will still need to be in the same package as the ServiceComposite sub type, the TravelPlanService in the above example. For instance;

public void assemble(ModuleAssembly module) throws AssemblyException
{
    module.addServices(TravelPlanService.class)
            .instantiateOnStartup()
            .identifiedBy("ExpediaService");

    module.addServices(TravelPlanService.class)
            .instantiateOnStartup()
            .identifiedBy("OrbitzService");
}

And the two files for configuration,

# Hostname to the TravelPlan service
hostName=expedia.hedhman.org

# Port number to use for the connection
portNumber=9251

# Protocol to use; Valid options "ssh", "rlogin", "telnet"
protocol=ssh

File: org/qi4j/manual/travel/ExpediaService.properties

# Hostname to the TravelPlan service
hostName=orbitz.hedhman.org

# Port number to use for the connection
portNumber=7412

# Protocol to use; Valid options "ssh", "rlogin", "telnet"
protocol=rlogin

File: org/qi4j/manual/travel/OrbitzService.properties

Unlike most frameworks, the Configuration in Zest™ is an active Entity, and once the properties file has been read once at the first(!) startup, it no longer serves any purpose. The Configuration will always be retrieved from the EntityStore. Changes to the properties file are not taken into consideration if the Configuration entity is found in the entity store.

But that also means that applications should not cache the configuration values, and instead read them from the Configuration instance every time needed, and do a refresh() method call when it is safe to update the Configuration Entity with new values.