Scope

This documents describes various aspects of abeans configuration.

Table of Contents

1. Overview

2. Configuration location

3. AbeansStartup.txt

4. Component configuration

5. Configuring applications

6. Code Examples

Document History

1. Overview

Abeans offer very open and flexible configuration for both dynamic configuration of deployed applications as well as powerful mechanism for implementing these designs in code.

2. Configuration location

Central configuration parameter for all abeans applications is AbeansStartup.txt file. Location of this file is defined as Abeans home location. To define specific location, pass the abeans.home variable to the JVM using the -D parameter. Otherwise, the following locations will be searched:

• Location defined by system preferences with abeans.home key. This would be the parameter passed to JVM during startup i.e. 'java -Dabeans.home=/home/abeans/config'. This parameter takes can take either URL form or local file path.
• Current directory, from which the application was started.
• 'Config' subdirectory of directory in which application was started.
• Java classpath locations will be searched for AbeansStartup.txt. If one and single location is found, this location will be used.

After AbeansStartup.txt has been located its location will be put in abeans.home, if it has not been defined specifically.

3. AbeansStartup.txt

This file defines location of various abeans resources. Each location can reside either in local filesystem or on a remote server defined by URL. Abeans access these locations through loader mechanism, where actual physical location of resource is not predefined. These loaders could be extended to read data from SQL database, web server or some other location.

Typical AbeansStartup will look something like this:

<Resources>
	<Resource NAME="Configuration" LOADER="abeans.core.defaults.FileLoader">
		<Property NAME="root.path" VALUE="$abeans.home$"/>
 	</Resource>
 	<Resource NAME="Home" LOADER="abeans.core.defaults.HomeLoader"/>
 	<Resource NAME="Simulator" LOADER="abeans.core.defaults.FileLoader">
 		<Property NAME="root.path" VALUE="$abeans.home$/Simulated"/>
 	</Resource>
 	<Resource NAME="Data" LOADER="abeans.core.defaults.FileLoader">
 		<Property NAME="root.path" VALUE="$abeans.home$/../Resources/Data"/>
 	</Resource>
</Resources>


			

Each resource entry defines a single Resource location. Unlike local file access, this location is not bound to a single type of access and can be changed without affecting the application. Each entry has two required parameters, NAME and LOADER. Name will uniquely identify this resource location within an application, Loader defines actual implementation that will access the data. Additionally, each resource location can specify additional parameters that will be passed to the Loader implementation. This data could, for example, include username and password for remote server.

Configuration and Home are special and should in most cases be configured in the same way as shown above. Data location is used for application state storage and most common user defined data accessed from application.

There are two most commonly used loaders: abeans.core.defaults.FileLoader and abeans.core.defaults.URLLoader. Each of them accepts single parameter with name root.path which defines resource location. This can be either absolute path (/home/user) or relative ($config.root$/files) for FileLoader and absolute only (http://config.server.org/localconfig) for URLLoader. Any text enclosed within $ will be considered to be a variable, similar to environment variable. These variables can be changed or defined within an application or by passing them via JVM -D parameter. Such approach ensures that any resource location can be changed at any time without recompiling any code.

4. Component configuration

Apart from global configuration, each component that implements abeans.core.defaults.Configurable can be configured individually. These include most services and by default all applications. For a comprehensive list of all policy and configuration values see Abeans Services Configuration

One aspect of configuration is defined by Configurable interface. Such configuration class based configuration and serves to define configuration defaults. This means if object B extends A, where each object has its own configuration in B.txt and A.txt respectively, object B will receive configuration from A.txt as well as B.txt. Additionally, any parameters for B will override same parameters for A. These files are stored in abeans.home/Default location and indexed in index.txt file in the same directory. Index file contains class - configuration file pairs, defining which file contains configuration for which class.

Other aspect is instance configuration. This configuration is bound to the Identifiable interface, meaning it can be used to configure only classes implementing abeans.core.Identifiable interface. Each such objects defines a name independant from class, that can be changed during runtime. In contrast to type based configuration, this approach allows different instances of same class to have differenct configurations. On example for this would be abeans.models.Abean class. Type based configuration from Abean.txt would define parameters common to all Abean objects. Assuming that each Abean representing device is Identifiable which declares name of the device, specific configuration could be provided for each device. Any configuration obtained in such way will be merged with type based configuration. Example: Devices are implemented using abeans.models.Abean class which implements abeans.core.Identifiable interface. Each device will have unique name (DEV_01, DEV_02, ...) that will be reflected in Identifiable.getIdentifier().getName(). Individual configurations could now be provided using DEV_01.txt, DEV_02.txt configuration files. These configuration files are stored at abeans.home location.

Third way is using specific named configuration. In this case, an object requests a specific configuration with a name indepenant from above methods.

5. Configuring applications

This section describes some of the common abeans application configuration files along with their default locations.

abeans.home/AbeansStartup.txt - Contains information about resource location and loaders. Resource elements defines unique name of the resource location and loader that will be used to access it. Each such resource can have have a list of property elements, that define name-value pair resource location parameters. Example:

<Resources>
	<Resource NAME="Files" LOADER="abeans.core.defaults.URLLoader">
		<Property NAME="root.path" VALUE="http://config.server.org/~user"/>
 	</Resource>
</Resources>


			

abeans.home/PolicyManager.txt - Defines global policies that affect global application behaviour. Each line defines a policy and its value. Following is the list of most common policies:

• abeans.core.defaults.DebugPolicy - If set to true, debug output will be generated by all components that support it. Default value is false.
• abeans.framework.LogReportsPolicy - Specifies if the report service should forward the reports to the logging service as well. Default value is true.
• abeans.core.defaults.ConsoleLogPolicy If set in the logger supporting this policy, it will cause log messages with level equal or greater to the level specified by this policy to be output to the console stream. Levels are defined by java java.util.logging.Level level names (i.e. INFO, CONFIG, FINER, OFF, ALL)
• abeans.framework.HomeDirectoryResourcePolicy Determines the location for the resource files. If set to 'true', loaders will load resources from the user's home directory. If set to 'false', the resource specified in the bootstrap configuration file will be used.
• abeans.models.ConnectionSyncPolicy Controls how connections are established If set to 'true', the connect call will block until the connection completes. If set to 'false', the connect will enqueue the connection request to be performed in another thread.
• abeans.models.DefaultTimeoutPolicy. This policy specifies the default time period in milliseconds during which single-response requests to the remote server must complete. This value can be overridden either on models or pluggable layer.
• DefaultPlugPolicy Returns the default plug that will be used by the application, if no plug is specified explicitly in creation of 'RemoteInfo' objects.

These policies may be reconfigured in abeans.home/Default/ApplicationContext.txt or in default application configuration files.

Example:

abeans.models.DefaultTimeoutPolicy=2000
abeans.models.ConnectionSyncPolicy=true
abeans.core.defaults.ConsoleLogPolicy=INFO

					

abeans.home/AbeansConfig.txt - Defines model and plugs used by application. This file defines which model applications use and which plugs will be made available to applications. Only a single model may be defined, but an arbitrary number of plugs. This file merely declares this information, each application must still select which plug it will use and whether it relies on model. This is configured in abeans.home/Default/ApplicationContext.txt Example:

model.Channel=abeans.models.channel.ChannelLibrary
plug.Simulator=abeans.pluggable.simulator.SimulatorPlug

					

In most cases it is not neccessary to modify this configuration.

abeans.home/Default/ApplicationContext.txt - Defines default policies for all applications. Each abeans application will extend this class, so any policy set here will affect all applications. These settings also allow overriding of abeans core policies as defined in abeans.home/PolicyManager.txt. Example: if PolicyManager defines ConsoleLogPolicy to OFF and ApplicationContext to ALL, then no logs produced by abeans core will be displayed, but all by application. This file must also contain declaration of plugs the application wishes to use, by reffering to plug declarations in abeans.home/AbeansConfig.txt Plugs used by application are separated by spaces and refer to names declared in AbeansConfig.txt, not actual class names. These names are also used within application to identify plugs and should be equal to Plug.getName() Example:

plugs=Simulator ACS
abeans.core.defaults.ConsoleLoggingPolicy=ALL

				

This example shows declaration of plugs and overriding ConsoleLoggingPolicy for application. Two plugs are made available to all applications (Simulator and ACS) and sets that all logs produced by application should be displayed in console.

abeans.home/Default/index.txt - defines default configuration files for individual classes. Each line contains class name - configuration file pair. Note that configuration names are specified without extension. Example:

abeans.framework.ApplicationContext=ApplicationContext

				

6. Code Examples

Loading configuration from an identifiable class.

abeans.home/SimpleApplication.txt has the following contents:
key=value
another_key=another_value

abeans.home/Default/ApplicationContext.txt has the following contents:
key=default_value
some=default_value

then application 'SimpleApplication' would read this information in the following way:

import abeans.core.*;
import abeans.core.defaults.*;

ComponentManager cm = Root.getComponentManager();
ConfigurationService cs = (ConfigurationService)cm.getComponent(ConfigurationService.class);
AbeansProperties conf = cs.getConfiguration(this, null);

// instance configuration
String a = conf.get("key");  // has value of 'value'
String b = conf.get("another_key"); // has value of 'another_value'
String c = conf.getDefaults().get("key"); // has value of 'default_value'; 

Loading files from resource location.

if abeans.home/AbeansStartup.txt contains the following:

<Resources>
	...
	<Resource NAME="Files" LOADER="abeans.core.defaults.URLLoader">
		<Property NAME="root.path" VALUE="http://config.server.org/~user"/>
 	</Resource>
	...
</Resources>

and 'http://config.server.org/~user' contains files 'file1.dat' and 'file2.dat',
they would be obtained in the following manner:

import java.io.*;
import abeans.core.*;

// java activation framework is part of Abeans distribution
import javax.activation.*;

	try {
		LoaderManager lm = Root.getLoaderManager();
		ResourceLocation rl = lm.getResourceLocation("Files");
		DataSource ds = lm.getDataSource(rl, "file1.dat");
		
		InputStream is = ds.getInputStream();
		
		// Read contents from input stream
		
	} catch (Exception e) {
	}

			

Document History