de.aristaflow.adept2.core.registry

Class AristaFlowPlatform

java.lang.Object

de.aristaflow.adept2.core.registry.AristaFlowPlatform

Direct Known Subclasses:

TwoPhasePlatform

public class AristaFlowPlatform
extends java.lang.Object

This class represents the entry point to the AristaFlow platform. It allows for creating and starting/bootstrapping the platform as well as terminating it. The usual procedure for this is creating an instance of this class, accessing the platform and terminating the platform afterwards:

 // create and bootstrap
 AristaFlowPlatform aristaFlow = new AristaFlow();
 try
 {
   // access the platform, usually via aristaFlow.getClientService();
   ...
 }
 finally
 {
   // terminate the platform
   aristaFlow.terminate();
 }
 

With this simple bootstrapping, the configuration is expected as files in specified configuration directories and all global properties (e. g. the configuration directories) are expected as system properties. To allow for more sophisticated provision of the configuration and the properties, there are several different constructors. The global properties can be set via a ConfigurationPropertyProvider which in turn can retrieve the properties arbitrarily, e. g. from a servlet configuration. A configuration can be provided directly which can either be combined with the configuration from the configuration directories. Or it can be a complete configuration not requiring any additional configuration. For the latter just do not provide any configuration directories via the provider (or system properties).

Bootstrapping can also be a two-step procedure: Create an instance of the AristaFlowPlatform using one of the constructors accepting a eager parameter. This will prepare the root configuration of the platform. You may then access and manipulate this. Afterwards bootstrap() the platform which will respect your configuration changes. The eager-flag specifies whether to provide a complete root configuration by loading and integrating all externally referenced configuration files. Use it to get the complete configuration and not just the basic one. But note that eager loading will take some time.

 // create
 AristaFlowPlatform aristaFlow = new AristaFlow(true);
 try
 {
   Configuration conf = aristaFlow.getRootConfiguration();
   // manipulate the configuration
   ...
   // bootstrap
   aristaFlow.bootstrap();
   // access the platform, usually via aristaFlow.getClientService();
   ...
 }
 finally
 {
   // terminate the platform
   aristaFlow.terminate();
 }
 

The two-step bootstrapping should only be used for highly sophisticated requirements, e. g. you need to decide on existing configuration values which other values you need to set. For providing configuration values from outside the configuration files, just use a constructor with integrated bootstrapping (without the eager parameter) accepting a configuration.

The configuration even allows for injection of complete service objects. These services need a normal configuration specifying the data for the registry (component type, whether to export, instantiation mode). Instead of providing an implementation class, the corresponding configuration value can also be directly the corresponding instance. With this, for instance, you can inject a servlet context when running in a servlet container, thus allowing the platform to access the servlet container.

Note that only one platform should be running at the same time in one JVM. However, you can terminate the platform and restart it by creating a new instance and bootstrapping it.

Author:

Ulrich Kreher

Field Summary

Fields

Modifier and Type	Field and Description
protected UrlConfigurationManager	confMgr The configuration manager used for the bootstrapped platform.

Constructor Summary

Constructors

Modifier	Constructor and Description
	AristaFlowPlatform() Bootstraps AristaFlow using system properties which also provide the configuration directories (or the default .
	AristaFlowPlatform(boolean eager) Partially bootstraps AristaFlow using system properties which also provide the configuration directories (or the default .
	AristaFlowPlatform(boolean eager, Configuration conf) Partially bootstraps AristaFlow using system properties which also provide the configuration directories (or the default .
	AristaFlowPlatform(boolean eager, Configuration conf, ConfigurationPropertyProvider provider) Partially bootstraps AristaFlow using the designated properties which also provide the configuration directories or URLs to load the root configuration from additionally to the designated configuration.
	AristaFlowPlatform(boolean eager, ConfigurationPropertyProvider provider) Partially bootstraps AristaFlow using the designated properties which also provide the configuration directories or URLs to load the root configuration from.
	AristaFlowPlatform(Configuration conf) Bootstraps AristaFlow using system properties which also provide the configuration directories or URLs to load the root configuration from additionally to the designated configuration.
	AristaFlowPlatform(Configuration conf, ConfigurationPropertyProvider provider) Bootstraps AristaFlow using the designated properties which also provide the configuration directories or URLs to load the root configuration from additionally to the designated configuration.
	AristaFlowPlatform(ConfigurationPropertyProvider provider) Bootstraps AristaFlow using the designated properties which also provide the configuration directories or URLs to load the root configuration from.
protected	AristaFlowPlatform(java.lang.String rootConfFileName, Configuration providedConfiguration, boolean eager, boolean singleton, ConfigurationPropertyProvider provider) Initialises the global properties and logging and creates a configuration manager.

Method Summary

Modifier and Type	Method and Description
void	bootstrap() Bootstraps the AristaFlow platform, that is, the initial services are started based on the root configuration from the configuration manager.
protected void	bootstrap(boolean dump) Creates a new bootstrap registry and initialises and starts it.
protected BootstrapRegistry	createBootstrapRegistry(UrlConfigurationManager cMgr) Creates a new bootstrap registry having the designated configuration manager.
protected UrlConfigurationManager	createConfigurationManager(java.lang.String rootConfFileName, Configuration providedConfiguration, boolean eager, ConfigurationPropertyProvider provider, LoggerManager loggerManager) Gets a configuration manager having the designated file (file name without path) as root configuration and/or the designated configuration.
protected BootstrapRegistry	getBootstrapRegistry()
ClientService	getClientService() Gets the client service providing convenient access to the services provided by the platform and needed by client components.
Registry	getRegistry() Gets the wrapper for access to the platform via the Registry -interface.
Configuration	getRootConfiguration() Gets the root configuration used for this AristaFlow platform.
void	terminate() Terminates the platform by shutting down the bootstrap registry.
protected void	terminateSafely() Terminates this platform safely, that is, all used services are terminated but they are not expected to be initialised.

Methods inherited from class java.lang.Object

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

Field Detail

confMgr

protected UrlConfigurationManager confMgr

The configuration manager used for the bootstrapped platform. This will be null after termination.

Constructor Detail

AristaFlowPlatform

public AristaFlowPlatform()
                   throws AbortServiceException

Bootstraps AristaFlow using system properties which also provide the configuration directories (or the default ./conf) or URLs to load the root configuration from.

Throws:

ConfigurationException - If

• there are problems initialising the global properties,
• one of the configuration directories cannot be accessed,
• the configuration bundle order is not defined,
• the root configuration file could not be found in any of the searched configuration directories, or
• the directory for storing the logs can not be created or it is a file,

a ConfigurationException will be thrown.

AbortServiceException - If the platform has already been bootstrapped or the initialisation or starting of the registry fails, an AbortServiceException will be thrown.

AristaFlowPlatform

public AristaFlowPlatform(ConfigurationPropertyProvider provider)
                   throws AbortServiceException

Bootstraps AristaFlow using the designated properties which also provide the configuration directories or URLs to load the root configuration from.

Parameters:

provider - The provider for the global properties including the configuration directories to load the root configuration from.

Throws:

ConfigurationException - If

• there are problems initialising the global properties,
• one of the configuration directories cannot be accessed,
• the configuration bundle order is not defined,
• the root configuration file could not be found in any of the searched configuration directories, or
• the directory for storing the logs can not be created or it is a file,

a ConfigurationException will be thrown.

AbortServiceException - If the platform has already been bootstrapped or the initialisation or starting of the registry fails, an AbortServiceException will be thrown.

AristaFlowPlatform

public AristaFlowPlatform(Configuration conf)
                   throws AbortServiceException

Bootstraps AristaFlow using system properties which also provide the configuration directories or URLs to load the root configuration from additionally to the designated configuration. If no configuration directories or URLs are provided. the designated configuration is expected to be complete. Especially no default configuration directory (./conf) will be used.

Parameters:

conf - The configuration to be integrated with the set configuration directories or URLs or a complete root configuration.

Throws:

ConfigurationException - If

• there are problems initialising the global properties,
• the provided configuration is not valid,
• one of the configuration directories cannot be accessed,
• the configuration bundle order is not defined,
• the root configuration file could not be found in any of the searched configuration directories, or
• the directory for storing the logs can not be created or it is a file,

a ConfigurationException will be thrown.

AbortServiceException - If the platform has already been bootstrapped or the initialisation or starting of the registry fails, an AbortServiceException will be thrown.

AristaFlowPlatform

public AristaFlowPlatform(Configuration conf,
                          ConfigurationPropertyProvider provider)
                   throws AbortServiceException

Bootstraps AristaFlow using the designated properties which also provide the configuration directories or URLs to load the root configuration from additionally to the designated configuration. If no configuration directories or URLs are provided. the designated configuration is expected to be complete.

Parameters:

conf - The configuration to be integrated with the set configuration directories or URLs or a complete root configuration.

provider - The provider for the global properties including the configuration directories to load additional configurations for the root configuration from.

Throws:

ConfigurationException - If

• there are problems initialising the global properties,
• the provided configuration is not valid,
• one of the configuration directories cannot be accessed,
• the configuration bundle order is not defined,
• the root configuration file could not be found in any of the searched configuration directories, or
• the directory for storing the logs can not be created or it is a file,

a ConfigurationException will be thrown.

AbortServiceException - If the platform has already been bootstrapped or the initialisation or starting of the registry fails, an AbortServiceException will be thrown.

AristaFlowPlatform

public AristaFlowPlatform(boolean eager)
                   throws ConfigurationException

Partially bootstraps AristaFlow using system properties which also provide the configuration directories (or the default ./conf) or URLs to load the root configuration from.
After creation you may adapt the configuration. But you have to bootstrap afterwards!

Parameters:

eager - Whether to (transitively) load all referenced configuration files for the root configuration.

Throws:

ConfigurationException - If

• there are problems initialising the global properties,
• one of the configuration directories cannot be accessed,
• the configuration bundle order is not defined,
• the root configuration file could not be found in any of the searched configuration directories,
• the directory for storing the logs can not be created or it is a file, or
• there are problems eagerly loading the externally referenced configuration files,

a ConfigurationException will be thrown.

AristaFlowPlatform

public AristaFlowPlatform(boolean eager,
                          ConfigurationPropertyProvider provider)
                   throws ConfigurationException

Partially bootstraps AristaFlow using the designated properties which also provide the configuration directories or URLs to load the root configuration from.
After creation you may adapt the configuration. But you have to bootstrap afterwards!

Parameters:

eager - Whether to (transitively) load all referenced configuration files for the root configuration.

provider - The provider for the global properties including the configuration directories to load the root configuration from.

Throws:

ConfigurationException - If

• there are problems initialising the global properties,
• one of the configuration directories cannot be accessed,
• the configuration bundle order is not defined,
• the root configuration file could not be found in any of the searched configuration directories,
• the directory for storing the logs can not be created or it is a file, or
• there are problems eagerly loading the externally referenced configuration files,

a ConfigurationException will be thrown.

AristaFlowPlatform

public AristaFlowPlatform(boolean eager,
                          Configuration conf)
                   throws ConfigurationException

Partially bootstraps AristaFlow using system properties which also provide the configuration directories (or the default ./conf) or URLs to load the root configuration from additionally to the designated configuration.
After creation you may adapt the configuration. But you have to bootstrap afterwards!

Parameters:

eager - Whether to (transitively) load all referenced configuration files for the root configuration.

conf - The configuration to be integrated with the set configuration directories or URLs or a complete root configuration.

Throws:

ConfigurationException - If

• there are problems initialising the global properties,
• the provided configuration is not valid,
• one of the configuration directories cannot be accessed,
• the configuration bundle order is not defined, or
• the root configuration file could not be found in any of the searched configuration directories,
• the directory for storing the logs can not be created or it is a file, or
• there are problems eagerly loading the externally referenced configuration files,

a ConfigurationException will be thrown.

AristaFlowPlatform

public AristaFlowPlatform(boolean eager,
                          Configuration conf,
                          ConfigurationPropertyProvider provider)
                   throws ConfigurationException

Partially bootstraps AristaFlow using the designated properties which also provide the configuration directories or URLs to load the root configuration from additionally to the designated configuration. If no configuration directories or URLs are provided. the designated configuration is expected to be complete.
After creation you may adapt the configuration. But you have to bootstrap afterwards!

Parameters:

eager - Whether to (transitively) load all referenced configuration files for the root configuration.

conf - The configuration to be integrated with the set configuration directories or URLs or a complete root configuration.

provider - The provider for the global properties including the configuration directories to load additional configurations for the root configuration from.

Throws:

ConfigurationException - If

• there are problems initialising the global properties,
• the provided configuration is not valid,
• one of the configuration directories cannot be accessed,
• the configuration bundle order is not defined,
• the root configuration file could not be found in any of the searched configuration directories,
• the directory for storing the logs can not be created or it is a file, or
• there are problems eagerly loading the externally referenced configuration files,

a ConfigurationException will be thrown.

AristaFlowPlatform

protected AristaFlowPlatform(java.lang.String rootConfFileName,
                             Configuration providedConfiguration,
                             boolean eager,
                             boolean singleton,
                             ConfigurationPropertyProvider provider)
                      throws ConfigurationException

Initialises the global properties and logging and creates a configuration manager. This is the first part of bootstrapping AristaFlow. After this constructor you may adapt the configuration. But you have to bootstrap afterwards!

Parameters:

rootConfFileName - The name of the file (relative to the configuration directory/directories) containing the root configuration that is searched for in the configuration directories specified by the designated provider. This may be null but then the designated configuration has to be a complete root configuration.

providedConfiguration - The configuration provided when bootstrapping. This may either be a complete root configuration (without additional configuration directories), a delta configuration complementing or overriding the configurations from the configuration directories or even null. If this is null, only configurations from the configuration directories will be used but this requires a valid rootConfFileName.

eager - Whether to (transitively) load all referenced configuration files for the root configuration.

singleton - Whether this platform should be singleton or allow multiple instantiations of the platform. Usually singleton ( true) is the best, with multiple instantiations the global properties and the configuration may be arbitrary since they rely on static methods and fields.

provider - The provider for the global properties including the configuration directories to load additional configurations for the root configuration from. This must not be null.

Throws:

ConfigurationException - If

• there are problems initialising the global properties,
• there is no root configuration file name and no valid provided configuration,
• there is no valid provided configuration and no configuration directory has been set,
• one of the configuration directories cannot be accessed,
• the configuration bundle order is not defined,
• the designated root configuration file name could not be found in any of the searched configuration directories,
• the directory for storing the logs can not be created or it is a file, or
• there are problems eagerly loading the externally referenced configuration files,

a ConfigurationException will be thrown.

Method Detail

createConfigurationManager

protected UrlConfigurationManager createConfigurationManager(java.lang.String rootConfFileName,
                                                             Configuration providedConfiguration,
                                                             boolean eager,
                                                             ConfigurationPropertyProvider provider,
                                                             LoggerManager loggerManager)
                                                      throws ConfigurationException

Gets a configuration manager having the designated file (file name without path) as root configuration and/or the designated configuration.
Note that the root configuration does not contain the default values added by the configuration description of a service. Additionally, it is not validated yet, that is, some required values may be missing leading to problems when starting the corresponding service.

Parameters:

rootConfFileName - The name of the file (relative to the configuration directory/directories) containing the root configuration that is searched for in the configuration directories specified by the designated provider. This may be null but then the designated configuration has to be a complete root configuration.

providedConfiguration - The configuration provided when bootstrapping. This may either be a complete root configuration (without additional configuration directories), a delta configuration complementing or overriding the configurations from the configuration directories or even null. If this is null, only configurations from the configuration directories will be used but this requires a valid rootConfFileName.

eager - Whether to (transitively) load all referenced configuration files for the root configuration.

provider - The provider for the global properties including the configuration directories to load additional configurations for the root configuration from. This must not be null.

loggerManager - The logger manager providing and configuring the loggers for the platform. Logging is initialised right after the root configuration has been initialised.

Returns:

The configuration manager created with the designated values.

Throws:

ConfigurationException - If

• there is no root configuration file name and no valid provided configuration,
• there is no valid provided configuration and no configuration directory has been set,
• one of the configuration directories cannot be accessed,
• the configuration bundle order is not defined,
• the designated root configuration file name could not be found in any of the searched configuration directories,
• the directory for storing the logs can not be created or it is a file, or
• there are problems eagerly loading the externally referenced configuration files,

a ConfigurationException will be thrown.

createBootstrapRegistry

protected BootstrapRegistry createBootstrapRegistry(UrlConfigurationManager cMgr)
                                             throws AbortServiceException

Creates a new bootstrap registry having the designated configuration manager. This is just a factory method.

Parameters:

cMgr - The initial configuration manager that provides the root configuration and configurations for the loaded component instances.

Returns:

The created bootstrap registry.

Throws:

ConfigurationException - If the registry configuration is invalid, a ConfigurationExceptionwill be thrown.

AbortServiceException - If the initialisation or starting of the registry fails, an AbortServiceException will be thrown.

getRootConfiguration

public final Configuration getRootConfiguration()

Gets the root configuration used for this AristaFlow platform. This allows to change configuration values before bootstrapping. Afterwards only a clone of the root configuration will be returned to prevent inconsistencies due to changes.
Note that for the root configuration to contain all configuration values for changes, you should load it eagerly. Otherwise configurations from referenced configuration files will not be part of the root configuration.
Note that the root configuration does not contain the default values added by the configuration description of a service. Additionally, it is not validated yet, that is, some required values may be missing leading to problems when starting the corresponding service.

Returns:

The root configuration object that may be changed via side-effects before bootstrapping, a clone of the root configuration after bootstrapping and null after terminating.

bootstrap

protected void bootstrap(boolean dump)
                  throws AbortServiceException

Creates a new bootstrap registry and initialises and starts it. This in turn bootstraps the AristaFlow platform, by parsing the root configuration and starting the initial services appropriately.

Parameters:

dump - Whether the configuration manager should dump the root configuration after bootstrapping. This also reflects the changes that may have been applied between initialising the configuration manager and bootstrapping.

Throws:

ConfigurationException - If there are problems loading the externally referenced configuration files for dumping, a ConfigurationException will be thrown.

AbortServiceException - If the platform has already been bootstrapped, the initialisation or starting of the registry fails or the platform has already been terminated, an AbortServiceException will be thrown.

bootstrap

public void bootstrap()
               throws AbortServiceException

Bootstraps the AristaFlow platform, that is, the initial services are started based on the root configuration from the configuration manager. Only one platform may be running at a time. You need to terminate a platform before you can bootstrap another one.

Throws:

ConfigurationException - If there are problems loading the externally referenced configuration files for dumping, a ConfigurationException will be thrown.

AbortServiceException - If the platform has already been bootstrapped or the initialisation or starting of the registry fails, an AbortServiceException will be thrown.

getClientService

public ClientService getClientService()
                               throws AbortServiceException

Gets the client service providing convenient access to the services provided by the platform and needed by client components.

Returns:

The client service for usage by client components.

Throws:

ServiceNotKnownException - If there are problems retrieving the client service, a ServiceNotKnownException will be thrown.

AbortServiceException - If the platform has not been bootstrapped or terminated, an AbortServiceException will be thrown.

getRegistry

public Registry getRegistry()
                     throws AbortServiceException

Gets the wrapper for access to the platform via the Registry -interface. This is used by (server) services to access the registry. Clients should always use an appropriate client service. Only use this registry for very special purposes.

Returns:

The registry providing generic access to the platform.

Throws:

ServiceNotKnownException - If there are problems loading the model factory registry, a ServiceNotKnownException will be thrown.

AbortServiceException - If the platform has not been bootstrapped or terminated, an AbortServiceException will be thrown.

terminateSafely

protected void terminateSafely()

Terminates this platform safely, that is, all used services are terminated but they are not expected to be initialised. They are not even expected to be set at all. This method does not and must not throw an exception! It may be called from within the constructor in case of problems. Throwing an exception here would hide the actual problem in the constructor.
When overriding this method make absolutely sure that you comply to these rules. Usually you override terminate which can expect the platform to be properly started.

terminate

public void terminate()

Terminates the platform by shutting down the bootstrap registry. You have to call this method before exiting the JVM. Otherwise the services will not be terminated correctly and may have inconsistent persisted data.
Terminating the platform several times will be ignored. The same applies to terminating before loading.

getBootstrapRegistry

protected BootstrapRegistry getBootstrapRegistry()
                                          throws AbortServiceException

Throws:

AbortServiceException