Configurations and deployment

In this section, we will investigate some of the classes that provide the deployment and configuration management functionality of Apache Geronimo.

ConfigurationManager

A ConfigurationManager encapsulates the logic for dealing with configurations. Configurations have a lifecycle with three states: installed, loaded, and running. Installed means that the configuration is present in the server's repository. Loaded means that the configuration Gbean, including the configuration's ClassLoader, is running. Running means that all of the GBeans in the configuration are running. When a configuration is not loaded, only its ConfigurationData is available for inspection. It's normally not possible to inspect the GBeans in the configuration because there's no ClassLoader that could be used to load the classes needed by the instances of GBeanData in the configuration. Once the configuration has been loaded, its ClassLoader is available so that the instances of GBeanData can be loaded and inspected. But the GBean instances are not instantiated and started until the configuration is started.

We will now look at some of the APIs in the ConfigurationManager interface:

• isInstalled(): Returns true if a specified configuration is installed on the server.

• isLoaded(): Returns true if a specified configuration is loaded into the kernel.

• isRunning(): Returns true if a specified configuration is running.

• getInstalled(): Returns a list of installed configurations, given an artifact that's not fully resolved (for example, some parts are missing), that is, any of the matching configurations in the configuration store, regardless of whether they're loaded or running.

• getLoaded(): Returns a list of configurations, given an artifact that is not fully resolved (for example, some parts are missing), and check whether there are any instances loaded.

• getRunning(): Returns a list of configurations, given an artifact that is not fully resolved (for example, some parts are missing), and check whether there are any instances running.

• listConfigurations(): Returns a list of all of the configurations installed on the server.

• listStores(): Returns a list of abstract names of the configuration stores controlled by this configuration manager.

• getStores(): Returns an array containing all of the configuration stores known to this configuration manager.

• isConfiguration(): Returns true if a specified artifact is a configuration in the server.

• loadConfiguration(): Loads a specified configuration.

• getConfiguration(): Returns the configuration for a given artifact ID.

• unloadConfiguration(): Unloads a specified configuration.

• startConfiguration(): Starts a specified configuration and the contained GBeans. It will also start any parent configurations.

• stopConfiguration(): Stops a specified configuration and the containing GBeans. It will also stop any child configurations.

• restartConfiguration(): Restarts a specified configuration and the containing GBeans. It will also restart any child configurations.

• reloadConfiguration(): Reloads a specified configuration and the containing GBeans. It will also reload any child configurations.

• uninstallConfiguration(): Uninstalls a specified configuration from the server.

• isOnline(): Returns true if the ConfigurationManager is fully functional.

• getRepositories(): Returns a collection of repositories known to this ConfigurationManager.

• getArtifactResolver(): Returns the ArtifactResolver configured for all of the repositories known to this ConfigurationManager.

You can obtain a ConfigurationManager by calling the API ConfigurationUtil.getConfigurationManager(), with the kernel passed as a parameter.

EditableConfigurationManager

EditableConfigurationManager enables you to dynamically change the set of GBeans included in the configuration at runtime. The interface definition is as follows:

public interface EditableConfigurationManager extends ConfigurationManager {
void addGBeanToConfiguration(Artifact configID, GBeanData gbean, boolean start) throws InvalidConfigException;
void addGBeanToConfiguration(Artifact configID, String name, GBeanData gbean, boolean start) throws InvalidConfigException;
void removeGBeanFromConfiguration(Artifact configID, AbstractName gbean) throws InvalidConfigException, GBeanNotFoundException;
}

• addGBeanToConfiguration: Adds a new GBean defined by GBeanData to an existing configuration identified by the configID. The start parameter determines whether the newly-added GBean should be started or not.

• removeGBeanFromConfiguration: Removes the GBean specified by its abstract name from the configuration identified by configID.

LocalAttributeManager

ConfigurationManager uses an AttributeManager service to manage the GBean attributes of the GBeans deployed on the server. The LocalAttributeManager is configured by two files, namely, config.xml and config-substitutions.properties, which are located under the var/config directory, in order to the enable editing of GBean attribute values. The properties defined in config-substitutions.properties can be used in composing expressions for attribute values defined in config.xml. The following is an excerpt from config.xml:

<module name="org.apache.geronimo.configs/javamail/2.1.4/car">
<gbean name="SMTPTransport">
<attribute name="host">${SMTPHost}</attribute>
<attribute name="port">${SMTPPort}</attribute>
</gbean>
</module>

Here, the host attribute of the SMTPTransport GBean in the org.apache.geronimo.configs/javamail/2.1.4/car configuration are overridden by using an expression of ${SMTPHost}. The property SMTPHost is defined in config-substitutions.properties as follows:

SMTPHost=localhost

Therefore, the attribute value will evaluate to localhost. If the SMTPHost is used in multiple places in config.xml, then config-substitutions.properties provides an easy way to effect a change by making a change in only one place.

ArtifactResolver

ConfigurationManager uses the ArtifactResolver service for artifact resolution while loading configurations. The ArtifactResolver GBean is configured by the artifact_aliases.properties file, which is located under the var/config directory, in order to support the substitution of one artifact for another at runtime. This file contains entries in the format oldartifactid=newartifactId. The following is an excerpt from artifact_aliases.properties:

org.apache.geronimo.plugins/mconsole-ds//car=org.apache.geronimo.plugins/mconsole-ds/2.1.4/car
org.apache.geronimo.framework/geronimo-gbean-deployer/2.1/car=org.apache.geronimo.framework/geronimo-gbean-deployer/2.1.4/car

Here, all references to org.apache.geronimo.plugins/mconsole-ds//car, where the version is not specified, will be resolved to org.apache.geronimo.plugins/mconsole-ds/2.1.4/car, and any reference to org.apache.geronimo.framework/geronimo-gbean-deployer/2.1/car will be resolved to org.apache.geronimo.framework/geronimo-gbean-deployer/2.1.4/car. The artifact-aliases.properties file comes in handy when you have deployed configurations pointing to an explicit version of a JAR that you will want to upgrade to, without having to redeploy the configuration. Although overwriting the older JAR with a newer version could be a crude way of resolving the problem, artifact aliasing offers a cleaner way of achieving the same thing. Note that in the entries, the version number can be omitted from the left-hand side but not from the right-hand side.