Package de.aristaflow.adept2.core.registry

Class AristaFlowPlatform

  • Direct Known Subclasses:
    TwoPhasePlatform
    public class AristaFlowPlatform
extends 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 Description
      protected UrlConfigurationManager confMgr
      The configuration manager used for the bootstrapped platform.

    • Constructor Summary

      Constructors 
      Modifier Constructor 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, ConfigurationPropertyProvider provider)
      Partially bootstraps AristaFlow using the designated properties which also provide the configuration directories or URLs to load the root configuration from.
        AristaFlowPlatform​(boolean eager, org.apache.commons.configuration2.Configuration conf)
      Partially bootstraps AristaFlow using system properties which also provide the configuration directories (or the default .
        AristaFlowPlatform​(boolean eager, org.apache.commons.configuration2.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​(ConfigurationPropertyProvider provider)
      Bootstraps AristaFlow using the designated properties which also provide the configuration directories or URLs to load the root configuration from.
      protected AristaFlowPlatform​(String rootConfFileName, org.apache.commons.configuration2.Configuration providedConfiguration, boolean eager, boolean singleton, ConfigurationPropertyProvider provider)
      Initialises the global properties and logging and creates a configuration manager.
        AristaFlowPlatform​(org.apache.commons.configuration2.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​(org.apache.commons.configuration2.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.

    • 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​(org.apache.commons.configuration2.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​(org.apache.commons.configuration2.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,
                          org.apache.commons.configuration2.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,
                          org.apache.commons.configuration2.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​(String rootConfFileName,
                             org.apache.commons.configuration2.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​(String rootConfFileName,
                                                             org.apache.commons.configuration2.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 org.apache.commons.configuration2.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.