Loading, Starting, and Stopping Components


When running inside the Geronimo server, a software component often makes reference to another software component. For example, a servlet may make a call to a session EJB. The servlet in this case depends on the EJB to work properly. This creates a dependency between the two components. As the server container, it is Geronimo’s job to ensure that component dependencies are satisfied when the application runs.

Important

A component in Geronimo is actually called a GBean, which is short for Geronimo-Bean. A Geronimo server is internally composed of a collection of GBeans.

The process of deploying an application component to Geronimo can be broken down into the following sequence of events:

  1. Geronimo examines the archive for deployment descriptors and deployment plans. Geronimo configures the components from the archive according to the instructions in the descriptors and the plans. This will also involve resolving any dependencies between the components. The saved configuration of components is called a module in Geronimo.

  2. The module, consisting of configured components, is saved in a repository maintained by Geronimo.

  3. Geronimo starts the components by loading the module from the repository, allowing the application to run and start the processing of incoming requests.

Step 1 is called the configuration or building phase. During this phase, Geronimo will load the components, resolve dependencies, and configure them. The configured components are then saved in a persistent form during Step 2. Doing things this way ensures that the components can be started very quickly later.

Step 2 is called the distribution phase. You have distributed an application if it has been copied by Geronimo into Geronimo’s own managed repository.

Important

As of release 1.1, Geronimo’s configuration store is physically a directory hierarchy. In fact, if you look under the repository directory in the location where you have installed Geronimo, you will see a bunch of directories and subdirectories with names corresponding to their module IDs.

Application modules are started during Step 3. This consists of loading the persisted, preconfigured components from the repository. The components in the started module are also initialized in this step.

At any time, an administrator (that’s you) may decide to stop a set of running components. This can be done by stopping the module. Stopped modules still have their image on disk (in the repository). However, stopped component cannot process incoming user requests.

Important

To keep component configuration as flexible a possible, Geronimo 1.1 has the ability to override certain configuration parameters during the loading of the persisted modules. This occurs as part of Step 3. The configuration parameters that are changed are specified by an administrator in the var/config/config.xml file. The use of this file for configuration is covered in the section Making Basic Configuration Changes to Modules later in this chapter.

To completely remove an application from a Geronimo server, you must undeploy it (that is, uninstall it). Undeployment includes cleaning up the preloaded image of the application by removing it from the Geronimo-managed configuration store.

Geronimo comes preconfigured with certain modules already installed and running. You can see all the modules by using the following command:

 deploy --user system --password manager list-module

The list you will see is similar to Figure 2-8.

image from book
Figure 2-8: The list of modules currently deployed on the server

In Figure 2-8, all the configurations on the list have already been deployed to the server. They are persistent and can be restarted at any time. The configurations with a plus sign (+) in front of them are actually running on the server. The ones without the plus sign are deployed but not started. This means that they were not configured to start, that they were shut down previously, or that a failure condition has occurred and they are in a failed state.

For started applications, the URL to the root context of the application is also shown, after an @ sign. This URL can be used to access the component via a browser. For example, in Figure 2-8, the welcome page to Geronimo can be accessed by using http://your-e7423197eb:8080/.

The Geronimo Component Lifecycle

Figure 2-9 illustrates the lifecycle of a component in Geronimo.

image from book
Figure 2-9: The lifecycle of a Geronimo-managed module

A module is loaded (but not started) when it is first read from the repository and loaded into memory. The module is in the loaded/stopped state at this time.

Once the module is successfully loaded (including configuration and preparation for any dependent components), it can be started. This puts it through the starting state. Once the component is started successfully, the component is in the running state. In the case of a Web application, the application is ready to accept incoming requests in the running state.

If starting is unsuccessful, the module falls into the failed state. The module remains loaded but is not running in the failed state. Modules in the failed state may be stopped, restarted, or undeployed (removed from the server’s repository).

The Geronimo server manages the lifecycle of its contained applications. Each application is deployed and controlled as a module.

Important

A module is Geronimo-specific terminology that refers to a tightly bound grouping of configured software components. One of the unique properties of the components within a module is that they have a common lifecycle. From the Geronimo server’s perspective, each and every deployed J2EE application is a separate and distinct module. Incidentally, this roughly corresponds to the J2EE concept of a deployable module.

A deployed module receives a signal to start or stop whenever the following occurs:

  • You, as an administrator, start or stop the application using the deployer tool, Web console, or Ant scripting.

  • Geronimo detects a dependency while starting or shutting down another dependent module.

  • The server itself is starting up or shutting down.

Table 2-5 summarizes the states in a Geronimo module’s lifecycle, as managed by Geronimo.

Table 2-5: Geronimo Module Lifecycle States
Open table as spreadsheet

State

Description

Loaded

The module has been installed on the Geronimo server but has not yet been started.

Starting

The module is in the process of starting up. During this time, it performs initialization, allocates required resources, and prepares for operation. A module may fail to start if an exception condition occurs during this process.

Running

The module has started successfully and is operating in its normal state. Applications can run indefinitely in this state. Even when encountering abnormal conditions, most modules can deal with the situation and log the details. However, when the error condition is fatal, the application may enter the failed state.

Stopping

The module is in the process of stopping. This may involve the release of resources and notifying other dependent components.

Stopped

This is indistinguishable from the loaded state. The application enters this state when it has successfully completed the stopping state or when it was first installed.

Failed

The module has failed and stalled. This state can be entered at any time when an application is starting, stopping, or running.

You will see references to these states throughout this book and in Geronimo’s documentation. Thankfully, they are quite easy to conceptualize and understand.

Important

The industry-drafted Java Specification Request, JSR-88, details the states that deployed applications can be in within a J2EE container. Geronimo strictly follows this standard in its implementation.

Making Basic Configuration Changes to Modules

Some properties of the default Geronimo modules can be changed quite simply. If you look in the var/config directory, you will find the following file: config.xml. This file is vital to the operations of the Geronimo server. It serves two very important functions:

  • As a list of installed modules that will be (optionally) started when the server (re)starts

  • As a convenient way to override some basic configuration parameters of the modules before the server starts

The following examines each of two functions of config.xml.

The config.xml as a What to Start List

The config.xml file describes the modules that are installed on this server and can be optionally launched automatically when the Geronimo server is started. The order in which modules are listed in config.xml is the order in which they start when the server starts up.

If you examine the config.xml file, you will find a root <attributes> element with many <modules> subelements. Each <modules> subelement describes an installed module. An installed module is one that has been deployed to the server - configured and saved in the repository. A load attribute of the <module> element also controls whether the module will be started. If this attribute is set to load='false', the installed module will not be started.

Since you have already deployed the default/progeron/11552985600093/car module on the server, and this module will be restarted when the server starts, you will find an entry for default/progeron/11552985600093/car module in this file. It is the last entry, highlighted in the following abbreviated listing of config.xml.

 <?xml version="1.0" encoding="UTF-8"?> <attributes xmlns="http://geronimo.apache.org/xml/ns/attributes">   <module name="geronimo/rmi-naming/1.1-SNAPSHOT/car">     <gbean name="RMIRegistry">       <attribute name="port">1099</attribute>     </gbean>     <gbean name="NamingProperties">       <attribute name="namingProviderUrl">rmi://0.0.0.0:1099</attribute>     </gbean>   </module>   ...   <module name="default/progeron/11552985600093/car">   </module> </attributes> </attributes> 

This file is part of the persistence mechanism of Geronimo - how it remembers what to start between reboots. Each <module> entry represents an installed module and can optionally be started. All of these modules are system components that make up the J2EE 1.4 personality of the server.

Anytime you start an application EAR bundle on the server, you should see the module name added to this list. This means that your application is installed and will be started automatically the next time the server starts up.

Important

It is important to realize that the Geronimo server actually writes to this file during its operation. This is the only way that the configuration that you deploy can be added to the file automatically. Because of this, you must not modify this file while the Geronimo server is running. You can, however, safely edit this file after the server shuts down.

Reconfiguring GBean Components with config.xml

The second personality of config.xml enables you to make minor attribute changes to GBean components within a listed configuration. These attributes will affect how the component behaves the next time Geronimo starts. Recall that a module consists of a group of components (GBeans are software components in Geronimo) that have the same lifecycle.

Important

Modify config.xml with great care, since editing errors in this important file can cause the server to behave erratically, or not start at all.

Some of the modules listed in config.xml may contain GBeans that have configurable attributes. These attributes may already have configured values in the persisted module image in the repository. However, if you make modifications to these attribute values in config.xml, the preconfigured value is overridden when the modules is started by the Geronimo server.

The following is the content of the default config.xml file (with the default/progeron/11552985600093/car module added at the end):

 <?xml version="1.0" encoding="UTF-8"?> <attributes xmlns="http://geronimo.apache.org/xml/ns/attributes">   <module name="geronimo/rmi-naming/1.1/car">     <gbean name="RMIRegistry">       <attribute name="port">1099</attribute>     </gbean>     <gbean name="NamingProperties">       <attribute name="namingProviderUrl">rmi://0.0.0.0:1099</attribute>     </gbean>   </module>   <module name="geronimo/j2ee-server/1.1/car">   </module>   <module name="geronimo/j2ee-security/1.1/car">     <gbean name="geronimo.remoting:target=JaasLoginServiceRemotingServer">       <attribute name="host">0.0.0.0</attribute>       <attribute name="port">4242</attribute>     </gbean>     <gbean name="JMXService">       <attribute name="protocol">rmi</attribute>       <attribute name="host">0.0.0.0</attribute>       <attribute name="port">9999</attribute>       <attribute name="urlPath">/jndi/rmi://0.0.0.0:1099/JMXConnector</attribute>     </gbean>   </module>   <module name="geronimo/axis/1.1/car">   </module>   <module name="geronimo/openejb/1.1/car">     <gbean name="EJBNetworkService">       <attribute name="host">0.0.0.0</attribute>       <attribute name="port">4201</attribute>     </gbean>   </module>   <module name="geronimo/j2ee-corba/1.1/car" load="false">     <gbean name="NameServer">       <attribute name="dbDir">var/cosnaming.db</attribute>       <attribute name="port">1050</attribute>     </gbean>     <gbean name="Server">       <attribute name="args">-ORBInitRef, NameService=corbaloc::localhost:1050/NameService</attribute>     </gbean>     <gbean name="UnprotectedServer">       <attribute name="args">-ORBInitRef, NameService=corbaloc::localhost:1050/NameService</attribute>     </gbean>   </module>   <module name="geronimo/system-database/1.1/car">     <gbean name="DerbyNetwork">       <attribute name="host">0.0.0.0</attribute>       <attribute name="port">1527</attribute>     </gbean>   </module>   <module name="geronimo/activemq-broker/1.1/car">     <gbean name="ActiveMQ.tcp.default">       <attribute name="host">0.0.0.0</attribute>       <attribute name="port">61616</attribute>     </gbean>   </module>   <module name="geronimo/activemq/1.1/car">   </module>   <module name="geronimo/directory/1.1/car" load="false">     <gbean name="geronimo.server:name=DirectoryService">       <attribute name="host">0.0.0.0</attribute>       <attribute name="port">1389</attribute>     </gbean>   </module>   <module name="geronimo/ldap-realm/1.1/car" load="false">   </module>   <module name="geronimo/tomcat/1.1/car">     <gbean name="TomcatResources">     </gbean>     <gbean name="TomcatWebConnector">       <attribute name="host">0.0.0.0</attribute>       <attribute name="port">8080</attribute>       <attribute name="redirectPort">8443</attribute>     </gbean>     <gbean name="TomcatAJPConnector">       <attribute name="host">0.0.0.0</attribute>       <attribute name="port">8009</attribute>       <attribute name="redirectPort">8443</attribute>     </gbean>     <gbean name="TomcatWebSSLConnector">       <attribute name="host">0.0.0.0</attribute>       <attribute name="port">8443</attribute>     </gbean>     <gbean name="geronimo/tomcat/1.1/car?ServiceModule=geronimo/tomcat/1.1/car,j2eeType=GBean, name=TomcatWebContainer">       <attribute name="catalinaHome">var/catalina</attribute>     </gbean>   </module>   <module name="geronimo/geronimo-gbean-deployer/1.1/car">   </module>   <module name="geronimo/j2ee-deployer/1.1/car">     <gbean name="WebBuilder">       <attribute name="defaultNamespace">http://geronimo.apache.org/xml/ns/j2ee/web/tomcat- 1.1</attribute>     </gbean>   </module>   <module name="geronimo/openejb-deployer/1.1/car">     <gbean name="EJBBuilder">       <attribute name="listener">?name=TomcatWebContainer</attribute>     </gbean>   </module>   <module name="geronimo/client-deployer/1.1/car">   </module>   <module name="geronimo/axis-deployer/1.1/car">   </module>   <module name="geronimo/javamail/1.1/car" load="false">     <gbean name="SMTPTransport">       <attribute name="host">localhost</attribute>       <attribute name="port">25</attribute>     </gbean>   </module>   <module name="geronimo/sharedlib/1.1/car">     <gbean name="SharedLib">       <attribute name="classesDirs">var/shared/classes</attribute>       <attribute name="libDirs">var/shared/lib</attribute>     </gbean>   </module>   <module name="geronimo/tomcat-deployer/1.1/car">   </module>   <module name="geronimo/welcome-tomcat/1.1/car">   </module>   <module name="geronimo/ldap-demo-tomcat/1.1/car" load="false">   </module>   <module name="geronimo/servlets-examples-tomcat/1.1/car" load="false">   </module>   <module name="geronimo/jsp-examples-tomcat/1.1/car" load="false">   </module>   <module name="geronimo/webconsole-tomcat/1.1/car">   </module>   <module name="geronimo/uddi-tomcat/1.1/car" load="false">   </module>   <module name="geronimo/daytrader-derby-tomcat/1.1/car" load="false">   </module>   <module name="geronimo/remote-deploy-tomcat/1.1/car">   </module>   <module name="geronimo/hot-deployer/1.1/car">   </module>   <module name="default/progeron/11552985600093/car">   </module> </attributes> 

Changing the Port and IP Address of Service Listeners

The most useful (and frequently changed) parameters are highlighted in the preceding listing. They typically represent the host adapter IP address and port number that each system service will listen for request on. The IP address 0.0.0.0 is special in that it tells the server to listen for requests on all hardware adapters. Many server machines may have two or more hardware network adapters (connecting to multiple networks at the same time-called multi-homed). Using an IP address other than 0.0.0.0 will allow you to specify the network adapter that the service should listen on for requests.

For example, as shown in config.xml, the TomcatWebConnector GBean component is configured to listen, by default, on all adapters, port 8080. Say that you change the highlighted configuration lines to the following:

 <gbean name="TomcatWebConnector">   <attribute name="host">198.0.0.1</attribute>   <attribute name="port">8081</attribute>   <attribute name="redirectPort">8443</attribute> </gbean>

This will cause the Jetty Tomcat connector to listen to incoming HTTP requests exclusively on the network adapter with IP address 198.0.0.1 and on port 8081. This new configuration will take effect the next time Geronimo starts up.

Another way to modify the basic configuration is by using the Web console. The Web console allows you to modify component configuration simply by changing some values using a GUI.

Note that, in order to use config.xml to modify the attributes of the GBean components, you must somehow know the available GBean names and attributes to modify. You can discover these components and attributes name via one or more of the following:

  • Their existence in the config.xml file

  • From the component’s documentation (for example, documentation for the Tomcat AJP connector GBean)

  • From their configuration description in this book

  • From the actual components’ deployment plan in Geronimo’s source code

In practice, there are only a limited number of GBeans and attributes of interest to administrators. Most of these configuration attributes will be covered in this book. There should be little need to actually examine the source code deployment plans.

In fact, Geronimo’s designers have ensured that the most commonly configurable GBeans and attributes have a GUI created for them - in the Geronimo Web console. You can configure these GBeans and attributes using the GUI without actually knowing the GBean and Attribute names. This is explored further in the next section.

Important-Assembly-Time versus Run-Time Configurability

By design, the components that make up a Geronimo server are highly configurable. Having adaptive and highly configurable components is a cornerstone of modern, reusable, modular software design. A constant struggle, however, at Geronimo design meetings, is determining how much of this configurability should be passed on to the administrator at deploy time. On one hand, the pro dynamic configuration pundits are insisting that tens or even hundreds of configuration parameters per component be passed to run time (when the Geronimo server starts or restarts). This enables the ultimate dynamic configurability. This, of course, will increase the configuration complexity for administrators and beginning users. And, when you figure that Geronimo starts up with at least a dozen or so modules, this complexity can escalate quickly. In addition to configuration complexity, providing too many configurable parameters also dramatically increases the possibility of erroneous configuration - resulting in a server that cannot be started or is started in a corrupted state. This affects the observed stability of the overall system. With this in mind, the designers of Geronimo make a lot of configuration choices at assembly time, leaving only a manageable number in the config.xml file. Assembly time refers to the time when the server personality is built into your binary distribution. There are many different ways of assembling the components to create different servers; the J2EE server is one of these possibilities. The Little-G minimal server, for example, is another assembly where the goal is to create the smallest functional server possible.

Modifying Configuration Attributes Using the Web Console

Many of the attributes that are contained in the config.xml file can also be changed safely through the Web console. For example, examine how you would change the IP address and port number that the Tomcat Web Connector will listen to.

This can be accomplished in the Web console by:

  • Clicking on the Web Server menu item on the left

  • Clicking on the edit action of the TomcatWebConnector component in the Network Listener portlet in the right-hand pane

You should see the configurable attributes for this listener component, as shown in Figure 2-10.

image from book
Figure 2-10: Configurable attributes for TomcatWebConnector listener component

Modifying the values on the portlet shown in Figure 2-10 and clicking Save will write them to the config.xml file. These changes will take effect the next time Geronimo is started.

Important

Some readers may notice that there is an additional attribute called max threads that is not included in the original config.xml file. This attribute is configurable via config.xml, but since its value is not modified there, it will take on the predefined default values.




Professional Apache Geronimo
Professional Apache Geronimo (Wrox Professional Guides)
ISBN: 0471785431
EAN: 2147483647
Year: 2004
Pages: 148

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net