Geronimo Directory Structure

The directory structure created by the Geronimo installation provides a glimpse into the internal workings of Geronimo. It is within this directory structure where the Geronimo server places all the code, configuration, and persistent execution state.

In the following examination of the directory structure, you will discover how server components and components states are maintained by Geronimo.

The Installation Directory

Under this directory, you will find the following subdirectories:

• bin - Directory for binary executable.

• deploy - The hot deployer regularly scans this directory for modules to deploy. Any modules placed in this directory will be automatically deployed.

• docs - Documentation directory for Geronimo.

• lib - Location of essential libraries required for Geronimo’s operation.

• repository - Directories where Geronimo persists all installed modules, including system modules, as well as the binaries and libraries that they depend on.

• schema - XML schema for all the run-time deployment plans and deployment descriptors.

• var - Working directories for Geronimo and all the deployed modules. Artifacts are created during module run time, and may remain after server shutdown (depending on the module’s behavior).

The content of each of these directories will be examined in the subsequent sections.

Important

While it is necessary for you to be acquainted with the directory structure, there is no immediate need to commit anything to memory. As you work with Geronimo, you will be roaming extensively throughout this directory architecture. Before long, it will become second nature as to where things are located.

The bin Directory

This is the directory for the major binary executables in Geronimo. Here, you will find the executables shown in Table 5-2. They are all JAR bundles, and you can run these executables using the -jar option of Java, with the following command-line format:

 java -jar <executable name> <arguments>

Table 5-2: Contents of the bin Directory
Open table as spreadsheet

Executable	Description
client.jar	This is the executable of the Geronimo client application container.
deployer.jar	This is the executable of the Geronimo run-time deployer. See Chapter 6 for detailed description of how to use this tool.
server.jar	This is the Geronimo server executable. You have already used this executable earlier to deploy the first Geronimo application.
shutdown.jar	This executable can be used to cleanly shut down a running server instance.
upgrade.jar	The upgrader utility to automatically convert Geronimo 1.0.x deployment plans to compatible Geronimo 1.1.x plans. Geronimo 1.0.x used a now obsolete module ID scheme. In Geronimo 1.0, modules were called configurations. You may find some old literature on the Internet still referring to modules as configurations.

Options for each of the executables will be covered in detail when they are introduced in later chapters.

There are also helper batch files (.sh for *nix and .bat for Windows) in this directory to set the command-line environment variables and to simplify launching of these executables.

The deploy Directory

Any deployable archive you placed in this directory will be detected and automatically deployed to the Geronimo server. In addition, the hot deployer continues to monitor the modification date of these archives. If they should ever change (indicating that the archive has been modified), they will be redeployed to the server.

Immediately after installation, this directory is empty. This directory is most useful during testing of Geronimo applications by developers. Developers can simply configure their build tool or IDEs to generate deployable archives into this directory. Geronimo will take care of keeping the deployed module in the server up to date (and redeploy as necessary).

The docs Directory

This directory is where the documentation for Geronimo is stored. As of Release 1.1, this directory contains a single file. This file simply says that you can get all the latest related documentation at http://geronimo.apache.org.

The lib Directory

This is where Geronimo will locate its system libraries at run time. In Java terminologies, these libraries are found at the Geronimo’s system class loader.

Table 5-3 describes the library files that you will find here.

Table 5-3: Library Binaries Used by the Geronimo System
Open table as spreadsheet

Library File	Description
cglib-nodep-X.X.X.jar	The code generation library used to manipulate Java byte code by Geronimo.
commons-cli-X.X.jar	Apache commons command-line processing library, used by Geronimo command-line tools (deployer, server, client, and so on) to accept and process the command line.
commons-logging-X.X.X.jar	Apache commons logging library. Provides a uniform layer of APIs for the Geronimo code to log operational problems and exceptions. This library allows a variety of logging implementations to be plugged in. Geron-imo uses log4j for logging by default.
geronimo-common-1.X.jar	Geronimo common library.
concurrent-X.X.X.jar	Concurrency utility library used to create and manage threads and synchronization by Geronimo.
geronimo-deploy-jsr88-X.X.jar	The JSR88 specification APIs.
geronimo-deploy-tool-X.X.jar	The command-line deployer tool libraries.
geronimo-deployment-X.X.jar	Deployment support and utilities library.
geronimo-spec-j2ee-deployment-X.X.jar	The standard J2EE deployment interfaces and APIs.
geronimo-kernel-X.X.jar	The kernel of Geronimo itself.
geronimo-spec-qname-X.X.jar	The standard J2EE naming interfaces and APIs.
geronimo-system-X.X.jar	The binaries of the Geronimo system module.
Geronimo-util-X.X.jar	The binaries of utility libraries used by the system module.
log4j-X.X.X.jar	Binary implementation of the log4j logger.
mx4j-X.X.X.jar	Binary implementation of the MX4J, an Open Source clean-room implementation of JMX.
mx4j-remote-X.X.X.jar	Binary implementation of JMX remoting for use with MX4J.
xpp3-X.X.X.jar	Small, fast, and efficient XML parser (used internally by Geronimo) that implements the XmlPull API.
xstream-X.X.X.jar	XML serialization library used internally to serialize objects to and from XML representations.

You will also find two subdirectories here, containing additional standard Java extension libraries: endorsed and ext.

The endorsed Subdirectory

The endorsed subdirectory contains the XML support libraries that are part of JDK 5 but not part of JDK 1.4.2. The libraries enable applications that make use of the Java XML APIs to run without change on either JDK 5, or JDK 1.4.2. Table 5-4 describes the content of the endorsed subdirectory.

Table 5-4: Content of the endorsed libraries Subdirectory
Open table as spreadsheet

Library File	Description
xercesImpl-X.X.X.jar	The Xerces XML parser.
xmlParserAPIs-X.X.X.jar	The standard JAXP XML parser API definitions.

The ext Subdirectory

This is the directory in which to place JSE standard extension libraries that may be required by application modules. There are currently no standard extensions (with the default distribution) in this directory.

The repository Directory

As mentioned earlier in this chapter, Geronimo is actually an integrated server consisting of many individual component servers. For example, Tomcat and OpenEJB are two servers that are integrated in Geronimo. Each of these servers is an Open Source project in its own right and depends on a large set of software libraries for its own operation.

To run all the integrated component servers properly, Geronimo must manage and ensure that the dependent library files are available to the components when they run. Geronimo maintains a copy of the required libraries in the repository. As mentioned previously, a repository is a location where the binaries of the component servers (as well as their own dependent libraries) are maintained. In addition, the repository is also where you will find Geronimo’s configuration store - a place where Geronimo saves the configuration state of the installed and deployed system and application modules.

The repository consists of a large collection of artifacts. An artifact can be considered a single item that can be stored or retrieved from the repository. Each and every artifact can be located in the directory precisely via its coordinates:

• group id

• artifact id

• version

• type

If this looks familiar, it should. This is exactly the composition of a module ID. This allows modules to be stored into the repository as a type of artifact.

In general, you can find an artifact in the repository by looking into the directory:

 repository/<group id>/<artifact id>/<version>

For example, to find the Tomcat server component of the Geronimo server, which has coordinates:

• group id = geronimo

• artifact id = geronimo-tomcat

• version = 1.1

• type = jar

This means that you can find the artifact if you look under the following directory:

 repository/geronimo/geronimo-tomcat/1.1

Indeed, you will find the geronimo-tomcat-1.1.jar artifact there.

Not all artifacts are stored as archive files. Artifacts can be of different types. Some of the popular artifact types are shown in Table 5-5.

Table 5-5: Format of Artifact Storage in the Repository
Open table as spreadsheet

Artifact Type	Artifact Storage in Repository
JAR	Stored as archive in repository
WAR	Stored as archive in repository
EAR	Stored as archive in repository
RAR	Stored as archive in repository
CAR	(configuration archive) Stored as a subdirectory in repository

The artifact type of note above is CAR. In fact, when you deploy a module and you specify a deployment plan for the module, the module ID always has the type CAR. A CAR, then, consists of the configuration information for the GBeans within a module, as well as a specification of its dependencies.

By letting the repository store both code archives (such as JAR, WAR) as well as configuration information (in CAR), the repository becomes both a code store and a configuration store.

The binary code of the Geronimo server modules (as well as their dependencies) are all stored as artifacts in the repository.

Table 5-6 describes the top level subdirectories (for release 1.1) under which you find all artifacts. For tools that access the repository in the standard way, the top-level subdirectory represents the group id of the coordinate for locating an artifact uniquely.

Table 5-6: Top-Level Directories of the Geronimo Repository
Open table as spreadsheet

Subdirectory (group id)	Description
activeio	The IO libraries for ActiveMQ.
activemq	The binaries and libraries for ActiveMQ message broker and resource adapter.
antlr	The binaries for the Open Source antlr grammar parser generator.
asm	Binaries and library for class working toolkit.
axis	Binaries and library for the Apache Axis SOAP engine, handling Web services in Geronimo.
cglib	Binaries and library for the cglib byte code generation and manipulation library.
common-beanutils	Apache common beanutils; used by many Open Source libraries.
common-cli	Apache common library for processing command lines.
commons-collections	Apache common collections; used in many Open Source packages and libraries.
common-digester	Apache common digester; used by many Open Source libraries.
commons-discovery	Apache common discovery; used in many Open Source libraries.
commons-el	Apache common expression language; used in many Open Source products.
commons-logging	Apache common file upload library; used by many Open Source libraries.
commons-modeler	Apache commons modeler; supports JMX; used in many Open Source libraries.
concurrent	The oswego util.concurrent library, a versatile library for creating multi-threaded concurrent software.
geronimo	The core Geronimo server modules binaries and configurations.
geronimo-spec	Legacy 1.0 Geronimo J2EE specification libraries - only the CORBA library remains here in 1.1. See org/apache/Geronimo/specs below.
howl	Highspeed Object Web Logger (HOWL), used in Geronimo to support transaction.
jdom	Java DOM support.
juddi	Scout jUDDI implementation.
junit	Junit unit testing framework.
log4j	log4j de facto standard logging API.
mx4j	MX4J; an Open Source JMX implementation.
openejb	OpenEJB, the business tier container for Geronimo.
org/apache/derby	Apache Derby, the full-featured, 100 percent Java RDBMS. Included as the built-in RDBMS of Geronimo.
org/apache/Pluto	Apache Pluto, the portlet framework for creating dynamic portal; used primarily by the Web console.
org/apache/geronimo/specs	Contains standard J2EE specification API libraries.
portlet-api	Standard API for portlets.
scout	Apache Scout jUUDI library.
stax	Stax lightweight SOAP stack.
tomcat	Binaries and library for the Tomcat Web-tier container.
tranql	Flexible data persistence layer used internally by Geronimo to handle EJB CMP and also JCA 1.5 JDBC connections.
wsdl4j	Binaries and library for Web Services Definition Language (WSDL) parser.
xerces	Full-fledged XML parser and XSLT processor.
xmlbeans	Library for working processing XML files.
xpp3	Small, fast, and efficient XML parser that implements the XmlPull API.
xstream	XML serialization library used to serialize objects to and from XML representations.

Note that if you have a custom assembly (meaning that the server components making up Geronimo have been modified), you are likely to see a different set of directories in the repository.

The list of artifacts in the repository is reflective of the breadth of Geronimo. Some of the libraries are the servers in the default assembly; others are libraries that these servers depend on.

The Repository As a Configuration Store

You are likely to find most Geronimo system modules deployed in the server with the groupid = geronimo. Because of this, you will find most configuration information (CAR artifact) stored under the Geronimo subdirectory.

CAR artifacts are used to store the configuration state information from the installed and deployed modules. This collection of persisted CAR artifacts is sometimes referred to as the Geronimo configuration store.

The information is stored in an implementation-specific binary format. Although it is possible to figure out exactly how Geronimo stores this configuration information, you are strongly discouraged by the designers from modifying any of the files stored in a CAR artifact. In addition, this format can frequently change. In fact, during Geronimo’s very young life thus far, the organization of the configuration store has already changed dramatically between 1.0 and 1.1.

You should always use the deployer tool (or the Web console) in conjunction with the appropriate J2EE deployment descriptor or deployment plans to add, remove, or modify modules’ configuration parameters- and not alter the configuration store directly.

Understanding a CAR (Configuration Archive)

To understand how Geronimo stores module configuration information, take the example of the Tomcat server module. This system module is installed and started by the default Tomcat-based server (look for the Jetty server component if you have installed the Jetty version). The coordinates for this application, as a deployable Geronimo module, are:

• group id = geronimo

• artifact id = tomcat

• version = 1.1

• type = car

If you look under the following directory, you will indeed find the expected webconsole-tomcat-1.1.car. However, the car is not an archive file but actually a directory.

 repository/geronimo/ tomcat/1.1

Underneath this CAR directory, you will actually find directories that contains the unachieved configuration and resources from your module.

The most interesting files under the CAR artifact’s subdirectory are its META-INF/ subdirectory.

Table 5-7 provides a brief description of some of the files you will find in this directory.

Table 5-7: Configuration Files under the META-INF Directory of a CAR Artifact
Open table as spreadsheet

File name	Description
config.info	An information file describing the serialized configuration of a module, including the module ID, the type of component (for example, service), and a unique timestamp of serialization.
config.ser	This is the serialized version of the configuration information in a deployment plan. The Geronimo server can load modules configured in this format significantly faster than parsing XML and loading individual GBeans all over again.
config.ser.sha1	A hash of the serialized configuration, used to verify the integrity of the serialized configuration.

The Geronimo 1.0 configuration store is separate from the repository, and consists of a hierarchy of directories combined with an external index. The 1.0 configuration store has been made obsolete by the 1.1 repository.

The config.ser file is the serialized configuration. When the Geronimo kernel starts or restarts, it only has to load these serialized configuration files to get up and running. This provides Geronimo with the following:

• You experience very quick start and restart time, avoiding the tedious and time-consuming XML parsing necessary to analyze configuration plans.

• You pay the penalty of configuration building upfront once only, at module deployment time. This means that any error in module configuration will be caught during deployment, and the interaction with the user is handled there. Once a module configuration is serialized, there is no need to further validate it before running.

• You have the capability to transfer configured modules between physical processing resources (such as servers in a cluster, or computing modules in a massively parallel configuration).

Figure 5-3 show how Geronimo manages configurations.

Figure 5-3: Configuration management in Geronimo

In Figure 5-3, the Geronimo server has three configured modules running. These modules are Module A, Module B, and Module C, respectively. In the configuration store, Geronimo maintains serialized images of each of these configurations. Specifically, Module A is stored in the numeric my/a/1.1/ a-1.1.car, Module B in my/b/1.1/b-1.1.car, and Module C in my/c/1.1/c-1.1.car directory. Each of the persisted configuration information can be retrieved easily from the repository once the module ID of the module is known.

If the server is ever interrupted or restarted, the configured module can be readily loaded from the serialized images of the configuration.

When the Geronimo kernel starts up, it must know which of the configurations in the configuration store to load. It finds out by checking the var/config/config.xml file. You will learn more about this file in the section “The var Directory” later in this chapter.

As you deploy more components to Geronimo, the number of persisted module configurations managed by Geronimo grows. The Geronimo repository is designed to handle this with ease by mapping them into a hierarchy of directories. Of course, each time you undeploy an application or module, its persisted module configuration is removed from the repository. Note, however, that you can stop a component - in which case, it will not run when the server starts up, but the persisted module configuration information still stays in the repository.

Important

Once you’ve figured out how the configuration storage portion of the repository in Geronimo works, it is tempting to create some useful scripts to manipulate and/or save the stored information. Don’t do it. Future Geronimo implementation may change the way things work for storing the configuration (again!). In general, it is unwise to create utility or script files based on the details of the configuration storage implementation.

Storing Deployed Modules Associated with a Configuration

Now that you know Geronimo stores all the persisted module configuration information in the repository in serialized format, you may be wondering where the actual binary code of the deployed module is stored. In fact, it is also stored in the configuration store.

More specifically, it is stored immediately below the artifact’s CAR directory. Each archive file in the module is expanded and placed into directories with the same name. Figure 5-4 illustrates the configuration store after you have successfully deployed progeron.ear in Chapter 2. Recall that the progeron.ear is an application that contains the Web-tier components in progeron.war and business-tier EJB components in progeron-ejbs.jar.

Figure 5-4: Storing deployed modules binaries within the repository

In Figure 5-4, you can see that the progeron-ejbs.jar application archive is kept intact while the progeron.war is expanded by Geronimo in the progeron.war directory. In general, the executable code archives of a module is stored either intact, or expanded in their own directories (with matching name), while the serialized configuration is always stored under in the META-INF directory.

The schema Directory

The deployment descriptor and deployment plans, used exclusively throughout Geronimo to configure components, are all XML files.

XML files are great for configuration because they are very easily parsed, validated, and processed by computer programs. Specifically, an XML schema describes to the parsing program what is allowed in a specific deployment descriptor or plan. Essentially, an XML schema describes the grammar allowed in a specific deployment descriptor or plan. It is in this directory that the schemas used by Geronimo and all of its component servers are kept.

Table 5-8 gives a brief description of each of the schema or Document Type Definition (DTD) files you will find in the default release 1.1 distribution. DTD is an older validation mechanism. DTD is less expressive than schemas and provides weaker validation of document syntax.

Table 5-8: Content of the schemas Directory
Open table as spreadsheet

XML DTD or Schema	Description
application-client_1_2.dtd	DTD for client.xml used in J2EE 1.2 client JAR files deployable to the client application container.
application-client_1_3.dtd	DTD for client.xml used in J2EE 1.3 client JAR files deployable to the client application container.
application-client_1_4.xsd	Schema for client.xml used in J2EE 1.4 client JAR files deployable to the client application container.
application_1_2.dtd	DTD for application.xml used in J2EE 1.2 EAR bundles.
application_1_3.dtd	DTD for application.xml used in J2EE 1.3 EAR bundles.
application_1_4.xsd	Schema for application.xml used in J2EE 1.4 EAR bundles.
connector_1_0.dtd	DTD for JCA 1.0 resource adapters, standard J2EE deployment descriptor.
connector_1_0.xsd	Schema for JCA 1.0 resource adapters, standard J2EE deployment descriptor.
connector_1_5.xsd	Schema for JCA 1.5 resource adapters, standard J2EE deployment descriptor.
corba-css-config-2.0.xsd	Schema for CORBA CSIv2 security support. This is the schema for client-side Client Security Service (CSS).
corba-tss-config-2.0.xsd	Schema for CORBA CSIv2 security support. This is the schema for server-side Target Security Service (TSS).
ejb-jar_1_1.dtd	DTD for ejb-jar.xml used in creating EJB 1.1–compatible EJB JAR bundles.
ejb-jar_2_0.dtd	DTD for ejb-jar.xml used in creating EJB 2.0 compatible EJB JAR bundles.
ejb-jar_2_1.xsd	Schema for ejb-jar.xml used in creating EJB 3.0–compatible EJB JAR bundles.
geronimo-application-1.X.xsd	Schema for Geronimo-specific deployment plan atthe EAR level.
geronimo-application-client-1.X.xsd	Schema for the Geronimo-specific application client deployment plan.
geronimo-config-1.X.xsd	Schema for common elements in Geronimo deployment plans.
geronimo-connector-1.X.xsd	Schema for deployment plans for JCA 1.5 connectors.
geronimo-javabean-xmlattribute-1.X.xsd	Schema for JavaBean XML attributes (properties).
geronimo-jetty-1.X.xsd	Schema for a Web application deployment descriptor for use in Jetty. (Only available when the Jetty version of Geronimo is installed.)
geronimo-jetty-config-1.X.xsd	Schema for Jetty configuration of virtual hosts. (Only available when the Jetty version of Geronimo is installed.)
geronimo-login-config-1.X.xsd	Schema for definition of login modules and security realms.
geronimo-module-1.X.xsd	Schema for definition of modules, environments, and dependencies within Geronimo deployment plans.
geronimo-naming-1.X.xsd	Schema for common naming reference elements used by other Geronimo schemas.
geronimo-security-1.X.xsd	Schema for the security element used in Geronimo deployment plans.
geronimo-service-1.X.xsd	Schema for GBean-based service and dependencies in Geronimo.
geronimo-tomcat-1.X.xsd	Schema for Tomcat-specific elements that can be used when deploying applications to Tomcat. (Only available when Tomcat version of Geronimo is installed.)
geronimo-tomcat-config-1.X.xsd	Schema for Tomcat-specific configuration. (Only available when Tomcat version of Geronimo is installed.)
geronimo-web-1.X.xsd	Schema for Geronimo-specific Web-tier deployment plan.
j2ee_1_4.xsd	Sharable common descriptor elements in standard J2EE deployment descriptors.
j2ee_jaxrpc_mapping_1_1.xsd	Standard J2EE support schema to map Java language types to WSDL for Web services.
j2ee_web_services_1_1.xsd	Standard J2EE support schema to describe a Web service deployed on a J2EE server.
j2ee_web_services_client_1_1.xsd	Standard J2EE support schema.
jsp_2_0.xsd	Schema for JSP 2.0 XML syntax.
openejb-jar-2.1.xsd	Schema for openejb-jar.xml file. This is the Geronimo-specific deployment plan for EJBs.
openejb-pkgen-2.0.xsd	Schema for OpenEJB public key generation.
web-app_2_2.dtd	DTD for Web application deployment descriptor, web.xml for Servlet API 2.2.
web-app_2_3. dtd	DTD for Web application deployment descriptor, web.xml, for Servlet API 2.3.
web-app_2_4.xsd	Schema for Web application deployment descriptor, web.xml, for Servlet API 2.4.
web-jsptaglibrary_1_2.dtd	DTD for JSP Standard Tag Library (JSTL) 1.2.
web-jsptaglibrary_2_0.xsd	Schema for JSTL 2.0.
wsdl.xsd	Schema for WSDL.
xml.xsd	Schema for XML namespace.

If you are using a custom assembly of Geronimo, since the component servers may change, you may see a slightly different set of schemas in this directory. For example, if you have installed the Tomcat minimal server configuration (Little-G), you will see significantly fewer files in this directory.

Geronimo is backward compatible with J2EE 1.3 components. J2EE 1.3 made use of a different mechanism to validate XML deployment plans. The older validation mechanism is called Document Type Definition (DTD). DTDs are considerably less expressive than schemas and provide weaker validation. In addition to schema files, you will find the backward-compatible DTD files in the schema directory.

In general, you can observe that Geronimo supports J2EE 1.3 backward compatibility. XML-based configuration files are specified DTD in J2EE 1.3, while J2EE 1.4 has moved to use XML schemas instead. XML schemas are significantly more effective for validating XML configuration files.

For those readers who can read an XML schema, these files are the authoritative source to check the exact allowed syntax for any Geronimo configuration file. They are the exact schemas and DTD used by the Geronimo server to validate the associated XML descriptor file.

The var Directory

This subdirectoy contains many of the run-time dynamic contents of Geronimo. For example, the logs and the temporary work directory for run-time-generated code are kept in this directory.

Table 5-9 describes some of the subdirectories that you find here and their contents.

Table 5-9: The var Working Directories
Open table as spreadsheet

Subdirectory	Description
activemq	Temporary working files for ActiveMQ.
catalina	Temporary working directories for Tomcat.
config	Geronimo configuration directory. Contains config.xml.
derby	Working directories for the Apache Derby RDBMS.
log	Directories for Geronimo and its components to save logs.
shared	Shared libraries directory for Jetty and Tomcat servers. This location can be modified by modifying the classDirs and libDirs attributes of the geronimo/sharedlib/1.x/car module in config.xml.
tmp	Temporary IO (input/output) directory for the Java Virtual Machine (JVM) that runs the Geronimo server. Location is set in the geronimo.sh (or geronimo.bat) script, via the java.io.tmpdir system property.
security	Working directories for Geronimo’s security implementation.
txlog	Transaction log subdirectory for Geronimo.

Of the subdirectories described in Table 5-9, the catalina, config, derby, log, and security directories deserve further examination.

The catalina Tomcat Working Directory

If you have worked with Tomcat 5.x before, you will recognize the content of the catalina directory. You will not see this directory if you have selected the Jetty-based download.

Basically, the Tomcat integrated into Geronimo will use the subdirectories here to store all its working files. Among others, you will find the following subdirectories:

• ROOT - The root context directory for the Tomcat server

• conf - Contains the default web.xml for Web applications running in Tomcat

• logs - Location where Tomcat will place its access logs

• work - Temporary working directory for Tomcat

Note that the server.xml file used to configure Tomcat is not located in the conf subdirectory. You must modify the configuration deployment plan for the Tomcat server to make system-level changes to the Tomcat server (such as adding valves).

See Chapter 11 for more information on Geronimo’s Tomcat configuration.

The config Directory

The config directory contains the config.xml file. This configuration file is processed by the server during Geronimo server startup. The config.xml file serves two purposes:

• Lists the modules in the order that will be started when the server starts up

• Allows administrators to easily modify the configuration of modules, by changing the values of GBean attributes during the startup process

Installed Modules and Startup Order

First, the general structure of the config.xml file is:

 <attributes xmlns="http://geronimo.apache.org/xml/ns/attributes-1.1">     <module name="module name">         <gbean name="gbean name">             <attribute name="attribute name">attribute value</attribute>         </gbean>             <gbean name="...">               ...             </gbean>               ...     </module>     <module>           ...          </module>          ... </attributes>

The root element is an <attributes> element. Within the <attributes> element are one or more <module> elements. Within each <module> element are one or more <gbean> elements. And within each <gbean> element are one or more <attribute> elements that provides the attribute name to over-ride, and the value that it should be overridden to. By specifying the module name, gbean name, and attribute name, the configuration of a module started up by the server can be changed.

Each module named in this file is an installed module on the Geronimo server instance. The order in which they are listed in this file is the order in which the Geronimo server will load and start these modules when the server starts up.

Preventing Installed Modules from Starting

Not every installed module must be loaded and started when the server starts. Modules that should not be loaded should have its load XML attribute, on the <module> element, set to False. For example, to avoid loading the JavaMail transport support module, the module may be specified as follows:

 <module name="geronimo/javamail/1.1/car" load="false"/>

In fact, when you use the Web console or the deploy tool to stop a module, this is exactly what the Geronimo server will do: Set the load attribute of the <module> element to “false.” Since the Geronimo server must write to the config.xml file to change its content, it must be ensured exclusive access to the config.xml file while the server is running. Therefore, it is of paramount importance that you do not write to the config.xml file while the server is running.

Only modify config.xml file when the Geronimo server is not running.

In addition, when the Geronimo server reads in the config.xml file, it does not track or maintain comments that may be original file. As a result, any comments in the config.xml file will be lost. If you absolutely need to put comments in the config.xml file, ensure that you always make a copy of it at some other location.

Changing Module Configuration by Overriding GBean Attributes

When you examine the config.xml file that comes with Geronimo, you will see many <attribute> elements inside <GBean> elements, within <modules> elements that you can change.

They are appropriately named to identify the actual module configuration value that may be modified.

For example, the Tomcat server module has the following highlighted attributes that may be modified.

 <module name="geronimo/tomcat/1.1/car">    <gbean name="TomcatEngine">      <reference name="TomcatValveChain"/>    </gbean>    <gbean load="false" name="FirstValve"/>    <gbean name="TomcatResources"/>    <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/car,j2eeType=GBean,name=TomcatWebContainer">      <attribute name="catalinaHome">var/catalina</attribute>    </gbean>  </module> 

The first set of attributes allows you to modify the network address (if you have more than one network card on your system, use this to select the network card to use), the TCP port, and the redirect port for the Web HTTP connector. The second set can be used to change the port used by the AJP connector - for connecting to external Web servers such as the Apache Web Server. The third highlighted set can be modified for the SSL connector. The last configurable attribute sets the location of CATALINA_HOME directory, used by the Tomcat server to find the ROOT and working directory tree.

Attributes for configuration of other module are also available in the config.xml. Just remember that if a module has a load="false" attribute, it will not be started, and modifying any GBean attribute will not have any effect.

You should only modify config.xml when the Geronimo server is not running. The file is only scanned once during server startup. This means that any changes that you make to config.xml will only be effective with the next server reboot.

The Derby Database Directory

Users who are familiar with Derby or IBM Cloudscape should recognize the content of this directory. The log file for the database is located in derby.log, while each subdirectory represents a separate Derby relational database instance. The data for each database instance is stored in a subdirectory underneath the derby directory. By default, you will see the system database instance (used internally by Geronimo) located in the SystemDatabase subdirectory.

The Log Directory

This is where most server components in Geronimo will be logging in to. You will also find the logging properties file to configure logging for the various server components in this log directory. Both the level of logging (from fatal - sparse to info - verbose), as well as the location to log to (console, file, and so on), can be controlled through these log properties files.

Some of the more common log files you will encounter in this directory include the following:

• geronimo.log - General Geronimo server log. Some components may also log within this file.

• deployer.log - The log for the run-time deployer command-line tool.

• client.log - The log for the Geronimo client application container.

• jetty_XXX.log - The log created by the Jetty Web-tier component.

Note that the Tomcat Web-tier container does not log in to this directory by default. Instead, it logs to its own log directory under the catalina/logs directory.

The Geronimo Security Directory

In this security directory, you will find the property files used by the various properties file-based security realm instances in Geronimo. This default security realm looks into the users.properties file and uses entries in this file.

The following is the only line in users.properties:

 system=manager 

This is the security realm used by the run-time deployer and is precisely why you need to use --user system and --password manager command-line options to access it.

Other files you will find in this directory include SSL keystore and other security properties files for demonstration applications.

For more information on security realms and Geronimo’s security implementation, see Chapter 15.