org.atteo.evo.config

Class Configuration

java.lang.Object

org.atteo.evo.config.Configuration

public class Configuration
extends Object

Generic configuration facility based on JAXB.

Overview

Evo Config opens one or more XML files, merges their content, filters them and then converts into the tree of objects using JAXB.

Defining XML schema

To use Evo Config you need to define the schema for your configuration file. This is achieved by creating a number of classes which extend Configurable abstract class and annotating them with JAXB annotations. Let's start by defining classes for generic service and some specific database service:

 abstract class Service extends Configurable {
   public abstract void start();
 }

. @XmlRootElement(name = "database")
 class Database extends Service {
.  @XmlElement
   private String url;

   public void start() {
     System.out.println("Connecting to database: " + url);
   }
 }
 
 

Also let's create the class which will define root of the configuration schema. Here the common idiom is to create field of type List annotated with XmlElementRef. Using this JAXB will be able to unmarshal any subclass of list element type. In this way the schema is open-ended, allowing anyone to implement our Service. There is no need to list all the implementations:

 . @XmlRootElement(name = "config")
  class Config extends Configurable {
.    @XmlElementRef
.    @XmlElementWrapper(name = "services")
.    @Valid
     private List<Service> services;
 }
 
 

The above schema will match the following XML:

 <config>
   <services>
     <database>
       <url>jdbc:h2:file:/data/sample</url>
     </database>
     <database>
       <url>jdbc:h2:tcp://localhost/~/test</url>
     </database>
   </services>
 </config>
 
 

Reading configuration files

    Configuration configuration = new Configuration();
    configuration.combine("first.xml");
    configuration.combine("second.xml");
    configuration.filter(properties);
    Root root = configuration.read(Root.class);
 

The following actions will be performed:

• JAXBContext will be created for all the classes extending Configurable, those classes are indexed at compile-time using ClassIndex facility,
• provided XML files will be parsed and combined using XmlCombiner facility,
• any property references in the form of ${name} will be substituted with the value using registered PropertyResolver, see Filtering for details,
• the result will be unmarshalled using JAXB into provided root class,
• finally the unmarshalled object tree will be validated using JSR 303 - Bean Validation framework.

Constructor Summary

Constructors

Constructor and Description
Configuration() Create Configuration by discovering all Configurables.
Configuration(Iterable<Class<? extends Configurable>> klasses) Create Configuration by manually specifying all Configurables.

Method Summary

Methods

Modifier and Type	Method and Description
void	combine(InputStream stream) Parse an XML file and combine it with the currently stored DOM tree.
void	filter(Properties properties) Filter ${name} placeholders using given properties.
void	filter(PropertyResolver resolver) Filter ${name} placeholders using values from given PropertyResolver.
void	generateSchema(File filename) Generate an XSD schema for the configuration file.
Element	getRootElement() Get root XML Element of the combined configuration file.
<T extends Configurable> T	read(Class<T> rootClass) Unmarshals stored configuration DOM tree as object of the given class.
<T extends Configurable> T	read(Class<T> rootClass, InputStream... streams) Combines several input XML documents and reads the configuration from it.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Configuration

public Configuration()

Create Configuration by discovering all Configurables.

Uses ClassIndex.getSubclasses(Class) to get Configurables.

Configuration

public Configuration(Iterable<Class<? extends Configurable>> klasses)

Create Configuration by manually specifying all Configurables.

Parameters:

klasses - list of Configurable classes.

Throws:

JAXBException - when JAXB context creation fails

Method Detail

generateSchema

public void generateSchema(File filename)
                    throws IOException

Generate an XSD schema for the configuration file.

Parameters:

filename - file to store the schema to

Throws:

IOException - when IO error occurs

filter

public void filter(Properties properties)
            throws IncorrectConfigurationException

Filter ${name} placeholders using given properties.

This method wraps given properties into PropertiesPropertyResolver and calls filter(PropertyResolver).

Parameters:

properties - properties to filter into configuration files

Throws:

IncorrectConfigurationException

filter

public void filter(PropertyResolver resolver)
            throws IncorrectConfigurationException

Filter ${name} placeholders using values from given PropertyResolver.

Parameters:

resolver - property resolver used for filtering the configuration files

Throws:

IncorrectConfigurationException

See Also:

CompoundPropertyResolver

combine

public void combine(InputStream stream)
             throws IncorrectConfigurationException,
                    IOException

Parse an XML file and combine it with the currently stored DOM tree.

Parameters:

stream - stream with the XML file

Throws:

IncorrectConfigurationException - when configuration file is invalid

IOException - when the stream cannot be read

read

public <T extends Configurable> T read(Class<T> rootClass)
                            throws IncorrectConfigurationException

Unmarshals stored configuration DOM tree as object of the given class.

Type Parameters:

T - type of the rootClass

Parameters:

rootClass - the class to which unmarshal the DOM tree

Returns:

unmarshalled class tree, or null if no streams were provided

Throws:

IncorrectConfigurationException - if configuration is incorrect

getRootElement

public Element getRootElement()

Get root XML Element of the combined configuration file.

Returns:

root Element

read

public <T extends Configurable> T read(Class<T> rootClass,
                              InputStream... streams)
                            throws IncorrectConfigurationException,
                                   IOException

Combines several input XML documents and reads the configuration from it.

This is equivalent to executing combine(InputStream) for each stream and then read(Class) for rootClass.

Type Parameters:

T - type of the rootClass

Parameters:

rootClass - the class to which unmarshal the DOM tree

streams - input streams with the configuration to combine

Returns:

unmarshalled class tree, or null if no streams were provided

Throws:

IncorrectConfigurationException - if configuration is incorrect

IOException - when cannot access configuration files