| 4.2. Server Startup and Configurations | ||
|---|---|---|
 | Chapter 4. Elements of Geronimo [DRAFT (1.0-pre)] |  |
| 4.2. Server Startup and Configurations | ||
|---|---|---|
| | Chapter 4. Elements of Geronimo [DRAFT (1.0-pre)] | |
The available configuration modules are listed in the config-store/index.properties file -- again, each one may represent a service, a resource, or an application module, each of which is (under the covers) typically composed of a series of GBeans. In the absence of specific directions, when Geronimo starts, it starts all the configuration modules that were running last time the server was run. (This is controlled by var/config/config.xml, which is updated whenever there are changes to GBeans or configurations.)
The pre-configured modules shipped with Geronimo are listed below. Note that some of them are started by default, and some others should not actually be started manually (they are for internal use only). This list is from the Geronimo-Jetty stack, so a Tomcat build will have slightly different names (e.g. geronimo/welcome-tomcat/1.0/car instead of geronimo/welcome-jetty/1.0/car).
Contains the basic services required for Geronimo to operate (such as GBeans for the repository and logging services). This configuration should always be run. It is started in the default Geronimo distribution.
Handles the RMI registry and naming services, which are additional fundamental services for the J2EE server environment. It is started in the default Geronimo distribution.
Contains the services necessary for Geronimo to act as a J2EE server (such as GBeans for the web application service, EJB service, and J2EE connector service). This configuration should be run when Geronimo should be capable of hosting J2EE applications (which for the purposes of this book means "always"). It is started in the default Geronimo distribution.
Handles the core security services for Geronimo, including the administration security realm. This is required for any security features to work. It is started in the default Geronimo distribution.
Contains basic CORBA configuration that allows code running in Geronimo to act as a CORBA client (calling out to remote CORBA services) or CORBA server (being called by remote CORBA clients). This does not need to be started if CORBA features are not required, and it is not started by default. Note: Geronimo's CORBA implementation requires a Sun Java1.4.2 VM (though IBM offers a Geronimo-based product with CORBA features that run on the IBM Java VM).
Handles the basic web container, including web application hosting features, network listeners, web application deployer, etc. It is started by default.
Provides an embedded Apache Directory LDAP server. This is not used by the current Geronimo core; it is available to be used by applications, for custom security realms, etc. It is started by default, but may be safely stopped.
A sample LDAP-based security realm, to demonstrate the embedded Directory features. It is started by default, but may be safely stopped.
Starts a basic embedded Derby database and network listener. It is required in order to support features like the EJB Timer service and JMS persistence. This is started in the default Geronimo distribution.
Starts an ActiveMQ JMS server. This is started in the default Geronimo distribution (because the SystemJMS service depends on it).
Starts a JMS connection factory (that connects to the default ActiveMQ server) and two JMS queues for internal server use. This is started in the default Geronimo distribution.
Should not be started. Used internally by the J2EE application client container.
Should not be started. Used internally by the J2EE application client container.
Should not be started. Used internally by the J2EE application client container.
Should not be started. Used internally by the J2EE application client container.
Provides JavaMail features. Geronimo provides both the JavaMail framework and a simple SMTP transport. For more advanced SMTP features or POP/IMAP support, you can run a third-party transport on the basic JavaMail framework.
Handles basic deployment operations for Geronimo, including deploying new configurations. This should be running for all but the most locked-down servers. It is started by default.
Expands the geronimo-gbean-deployer to handle J2EE applications and modules (except web applications). This should be running for all but the most locked-down server configurations (or non-J2EE configurations).
Monitors the geronimo/deploy directory for activity, deploying any files copied into that directory, redeploying as the files are updated, and undeploying when the files are removed. This is an optional service, but it is started by default.
Handles deployments of web applications using the Jetty web container. It is started by default.
A sample web application, including directions for setting up the sample LDAP security realm and tests to confirm that it's working correctly. This application is optional, and it is started by default at /ldap-demo
A sample web application that listens on the server root context (e.g. http://localhost:8080/) and provides a basic sanity check and some pointers for more information. This application is optional, and it is started by default. It must be disabled if you have a different application that should listen for requests on the root context of "/".
A sample web application that shows some example servlets. This is based on the examples distributed with the Tomcat server. It is optional, and started by default at /servlets-examples
A sample web application that shows some example JSPs. This is based on the examples distributed with the Tomcat server. It is optional, and started by default at /jsp-examples
The web management console application. This provides a web-based UI for server configuration and administration. The console is recommended for all but the most locked-down server configuraitons. It is started by default at /console
A web application that browses the JMX objects available in the local Geronimo server. It presents a list of objects grouped by category. This can be used to ensure that the expected resources are actually running and debug reference failures, though the JMX names tend to be somewhat cryptic. It is started by default at /debug-tool
A web application that handles deployment requests when you run the command-line deploy tool on a machine separate from the application server. This is recommended for most configurations, though the deployment tools can still be run locally even if this is disabled. It is started by default at /remote-deploy
A JAXR/UDDI server implementation, which runs as a web application. It is optional and started by default, at /juddi
A sample application that can be used for performance testing and benchmarking. It is optional and started by default, and the web application component is available at /daytrader
The application client component of the daytrader application. It is optional and should not be started manually, only run using the application client container (see Section 14.2.2, “Running a J2EE Application Client”).
Should not be started. This is used under the covers in conjunction with the deployer.jar tool.
Should not be started. This is used under the covers in conjunction with the shutdown.jar tool.
![[Tip]](images/tip.png) | Tip |
|---|---|
You can compare the list above to the available configurations in geronimo/config-store/index.properties. That file should contain all the entries here plus any additional configurations you've deployed. | |
Individual configurations can be started and stopped using the Geronimo deploy tool (however, the deploy tool cannot manipulate specific GBeans within a configuration). For example, to start two additional modules, once the server is up and running you could issue commands such as:
java -jar bin/deployer.jar start \
geronimo/j2ee-corba/1.0/car
java -jar bin/deployer.jar start \
geronimo/javamail/1.0/carNote that these commands require an administrator login, which defaults to a username of "system" with password "manager". For detailed syntax and more information about the deploy tool, see Section 10.4, “The Deploy Tool”.
A configuration module may have both explicit and implicit dependencies. Any configuration module may have a parent and it may also import other modules, so the parent and imports make up the explicit dependencies. When starting a configuration module, the server will always ensure that its parent has been started first (and its parent and so on). Therefore one strategy for resolving dependencies between modules is to create a explicit dependencies on everything that your application needs in order to run: an EAR may have two database configurations listed as imports, etc
Example 4.1. Explicit Dependencies
This is a sample Geronimo deployment plan header for a web application. The web application uses the configuration name MyWebApp and its parent is defined as ApplicationDatabasePool and an import set for ApplicationJMSResources:
<web-app xmlns="http://geronimo.apache.org/xml/ns/web"
configId="MyWebApp"
parentId="ApplicationDatabasePool">
<import>ApplicationJMSResources</import>
...That means that the database pool and JMS resources will always be started before the web application. All Geronimo deployment plans include these same configId and parentId attributes on the main element for the file, and an import element shortly thereafter. The specific format of the Geronimo deployment plans for application modules is covered in Part III, “J2EE Applications on Geronimo”.
The explicit dependency (parentId) is optional, and if not defined, the only explicit dependency will be on the core Geronimo infrastructure.
The other type of dependencies are implicit dependencies. These are dependencies which you did not specifically configure as such, but which the server can deduce based on the resource references and EJB references declared within a J2EE application.
Example 4.2. Implicit Dependencies
Imagine a web application that uses two database connections. It declares resource references for each:
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" version="2.4">
...
<resource-ref>
<res-ref-name>jdbc/FinanceDatabase</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
<resource-ref>
<res-ref-name>jdbc/ApplicationDatabase</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
</web-app>Then in the Geronimo deployment plan maps those to two different databases, one application database pool, and one finance database pool:
<web-app xmlns="http://geronimo.apache.org/xml/ns/web"
xmlns:naming="http://geronimo.apache.org/xml/ns/naming"
configId="MyWebApp">
<resource-ref>
<ref-name>jdbc/FinanceDatabase</ref-name>
<resource-link>FinanceDatabasePool</resource-link>
</resource-ref>
<resource-ref>
<ref-name>jdbc/ApplicationDatabase</ref-name>
<resource-link>ApplicationDatabasePool</resource-link>
</resource-ref>
</web-app>Based on that deployment plan, the server knows that the database pools FinanceDatabasePool and ApplicationDatabasePool must be running in order for the web application to work. So the application has implicit dependencies on those two database pools.
Finally, if an application uses resources from other applications (or the server itself) without declaring references in its deployment descriptors, the server has no way of identifying those dependencies, period. In that case it will always be up to you to ensure that everything an application requires is up and running.
| Tip |
|---|---|
To avoid worrying about dependencies altogether, you can include all your application modules in an EAR, and configure the necessary Geronimo resources in the EAR as well. That will make sure the application modules and all the resources they require are deployed as a single unit. However, that approach also prevents the sharing of a resource (such as a database connection pool) between multiple applications. | |
The deployer tool can be used to add new configuration modules to the Geronimo server. The usual syntax looks like this:
java -jar bin/deployer.jar deploy mymodule.jar
This would deploy and start a new module defined by the archive mymodule.jar. It will prompt for a username and password, which default to "system" and "manager" respectively. This command can be run on any J2EE application module (EJB JAR, WAR, RAR, EAR, etc.) to create a configuration for it. The server must be running for this command to work.
In cases where the Geronimo-specific deployment information is stored in a file outside the application archive, an additional parameter can be used to identify the Geronimo deployment plan:
java -jar bin/deployer.jar deploy mymodule.jar \
module-geronimo-dd.xmlAnother deployment option is to copy the module to the geronimo/deploy directory and allow the hot deployer to notice it and deploy it (this does not work with a Geronimo deployment plan unless the plan is packaged in the application module). Generally the command-line deploy tool has a couple advantages: in addition to handling external plans, it also prints any deployment errors directly to the console where you ran it (as opposed to the hot deploy tool, where any errors go to the server console and server log only). However, the command-line deployer does not work when the server is not running, while the hot deploy directory can at least deploy new applications during server startup (it doesn't handle redeployment or undeployment during startup).
For more deployment options, see Section 10.4, “The Deploy Tool”.
The same deployer syntax can be used to deploy Geronimo services in addition to application modules. In this case you may not have a module archive to deploy -- if the necessary code is already in the Geronimo repository, the module arguments can be omitted and only the deployment plan specified.
The following command-line options are available when starting the server:
Suppresses the normal progress bar output while starting Geronimo. This is useful for starting from scripts or automated processes.
Instead of the progress bar format, list each configuration along with its startup time as it is started. This is also a good format for scripts.
Set the console log level to DEBUG instead of the default INFO. Most Geronimo output will still be suppressed outside of the startup process, but application DEBUG messages will be displayed on thie console, and you can also turn down the base log level of org.apache.geronimo in the Log4J configuration.
Set the console log level to TRACE.
Override the saved configuration selection and only start the configurations specifically listed on the command line. WARNING: this is quite dangerous as listing the wrong configurations can result in a non-functional server.
| |  | |
| Chapter 4. Elements of Geronimo [DRAFT (1.0-pre)] |  | 4.3. Introduction to Deployment |