devloop icon

Configuration overview

In order to facilitate the configuration of the system:

  • The core framework provides a pluggable mechanism for looking up settings
  • Most of these mechanisms allow for inheritance (general properties can be defined for the whole package, parent packages or even at the root)

The lookup process

Many parts of the framework will try to lookup values: for example when mapping an object to a data store.
The data mapper used will get a MetaInfoSource (more information on that below) to delegate this work to a method of your choosing.


All the examples below are equivalent.
The class we refer to is shown in the first example. We only use the field annotation @Unique and the class annotation Description in these examples, but the principle is the same for any class or annotation.

Annotation Source

This is the simplest form, as it does not require any external data. The metadata is stored with the data it describes.

    package somepackage;
    @Description("This is our example class")
	public	class	SomeClass {
		public	int	someField;

Preference Source

This source can only be used programmatically when creating a MetaInfoSource:

	PreferenceSource source = new PreferenceSource();
	source.setAttributeValue(Unique.class, SomeClass.class, "someField", true);
	source.setAttributeValue(Description.class, SomeClass.class, "This is our example class");

System Env Source

This source is used to pass data from outside the Java Virtual Machine using environment variables.
The methods for specifying environment variables are Operating System specific, the example below is only valid on Unix like operating systems (note how the dots are replaced with underscores to cope with shells that do not support dots in variable names):

	export somepackage_SomeClass_someField_com_metastores_system_meta_field_Unique=true
	export somepackage_SomeClass_com_metastores_system_meta_Description="This is our example class"
	java YourCodeWhichUses.SystemEnvSource

System Property Source

This source is used to pass data from outside the Java Virtual Machine using the "-D" command line switch:

	java	-D
		-D"This is our example class"

Storage Meta Info Source

This example code assumes that the MetaInfoRecord class has been previously mapped to a storage engine (obviously, since the data is made persistent, the code below should only be executed once):

	StorageMetaInfoSource storeSource = StorageMetaInfoSource.getInstance();
	storeSource.createRecord(Unique.class, SomeClass.class, "someField", true);
	storeSource.createRecord(Description.class, SomeClass.class, "This is our example class");

Properties File Source

This source uses standard java properties files to store the meta data. The location of the file is configurable, it defaults to having 'config' pre-pended to the path which contains the class. ie: for a class named SomeClass in the package somepackage, the properties file is expected to be found in config/somepackage/, with contents as follows:
	com.metastores.system.meta.Description="This is our example class"

Combined Source

The combined source will call each one of its sources in turn, the example below is used to specify a PreferenceSource and a StorageMetaInfoSource ahead of the other sources (overriding any settings they may provide):

	PreferenceSource prefSource = new PreferenceSource();
	source.setAttributeValue(Unique.class, SomeClass.class, "someField", true);
	StorageMetaInfoSource storeSource = StorageMetaInfoSource.getInstance();
	storeSource.createRecord(Description.class, SomeClass.class, "This is our example class");
	CombinedSource cs = new CombinedSource();
	cs.add(new SystemEnvSource());
	cs.add(new StorageMetaInfoSource());

JNDI Sources

The JNDI sources are best suited for expensive and external resources like database connections, for an example, see the connection configuration examples.


All the sources of settings implement the interface MetaInfoSource.
The util package provides many implementations (see below for some usage examples):

Generally, the code will interact with a CombinedSource which allows it to combine any other sources as available/required.