These are a selection of the projects that Geronimo depends upon.

In order to get a version of Geronimo more current that the latest release, the source code can be checked out from Subversion, the version-control system used for Geronimo. Then the Geronimo build scripts can be used to create a custom distribution of Geronimo, using the same procedure as to build from an official source code release. The tools required to check out and build Geronimo include:

The source code can be checked with a command like this:

svn co https://svn.apache.org/repos/asf/geronimo/trunk geronimo

This will create a new directory called geronimo containing the Geronimo source code. From there, you can run various Maven commands to download dependencies, build Geronimo and the projects it requires, run tests, etc. This process is documented in greater detail on the Geronimo Wiki (http://wiki.apache.org/geronimo/Building).

Once Geronimo has been built from source, the directories under geronimo/modules/assemblies/ contain the same files that would ordinarily be present in the various release options (typically under a target/geronimo-version/ subdirectory). That directory can be copied elsewhere and generally treated similarly to a release.

To begin with, download the .tar.gz or .zip package.

Unpack the Geronimo install package to create a new geronimo-1.0/ installation directory. On Windows, a tool like WinZip can be used to unpack the ZIP file. On Mac or Linux, a command like tar -xzvf geronimo-1.0-jetty.tar.gz can be used to unpack the TAR file. This results in the directory structure shown in Figure 2.1, “Quick Start: Install Directory” (see Chapter 3, Installing Geronimo [DRAFT (M4)] for more details).

Figure 2.1. Quick Start: Install Directory

Open a command prompt and change to the Geronimo installation directory. Make sure Java 1.4.2 is on the current PATH. To start the server, run the command java -jar bin/server.jar (see Section 3.6, “Starting the Server” for more details).

geronimo-1.0> java -jar bin/server.jar
Booting Geronimo Kernel (in Java 1.4.2_10)...
Starting Geronimo Application Server
[*************************] 100%  37s Startup complete
  Listening on Ports:
    1099 0.0.0.0   RMI Naming
    1389 0.0.0.0   Apache Directory LDAP
    1527 0.0.0.0   Derby Connector
    4201 0.0.0.0   ActiveIO Connector EJB
    4242 0.0.0.0   Remote Login Listener
    8019 127.0.0.1 Jetty Connector AJP13
    8080 0.0.0.0   Jetty Connector HTTP
    8443 0.0.0.0   Jetty Connector HTTPS
   61616 0.0.0.0   ActiveMQ Message Broker Connector

  Started Application Modules:
    EAR: geronimo/daytrader-derby-jetty/1.0/car
    EAR: geronimo/uddi-jetty/1.0/car
    EAR: geronimo/webconsole-jetty/1.0/car
    RAR: geronimo/activemq/1.0/car
    RAR: geronimo/system-database/1.0/car
    WAR: geronimo/jmxdebug-jetty/1.0/car
    WAR: geronimo/jsp-examples-jetty/1.0/car
    WAR: geronimo/ldap-demo-jetty/1.0/car
    WAR: geronimo/remote-deploy-jetty/1.0/car
    WAR: geronimo/servlets-examples-jetty/1.0/car
    WAR: geronimo/welcome-jetty/1.0/car

  Web Applications:
    http://localhost:8080/
    http://localhost:8080/console
    http://localhost:8080/console-standard
    http://localhost:8080/daytrader
    http://localhost:8080/debug-tool
    http://localhost:8080/jsp-examples
    http://localhost:8080/juddi
    http://localhost:8080/ldap-demo
    http://localhost:8080/remote-deploy
    http://localhost:8080/servlets-examples

Geronimo Application Server started

Geronimo shows a text-based progress bar while it's starting, followed by a list of network ports it's listening on, applications that were started, and URLs to web applications that were started.

The ports in Figure 2.2, “Quick Start: Startup Output” are the standard set for Geronimo. If any of them are already taken by other programs (for example, 8080 for Tomcat), stop Geronimo, edit the file var/config/config.xml and search for the port number that's a problem, replace it with a new port number, and start Geronimo again (see Chapter 5, Core Configuration [EMPTY] for more details). Figure 2.3, “Quick Start: Editing Ports in config.xml” shows a section of config.xml where the standard HTTP listen port of 8080 has been changed to 8180.

...
  <configuration name="geronimo/jetty/1.0/car">
    <gbean name="JettyWebConnector">
      <attribute name="host">0.0.0.0</attribute>
      <attribute name="port">8180</attribute>
      <attribute name="redirectPort">8443</attribute>
    </gbean>
...

Once Geronimo has started, point a web browser to http://localhost:8080/console (or use the host name for the machine Geronimo is installed on, if not localhost). This brings up the login screen for the Geronimo management console:

Figure 2.4. Quick Start: Console Login

Enter the username "system" and password "manager". The default administrator account is set in the files var/security/users.properties and var/security/groups.properties in the Geronimo installation (see Chapter 9, Security Configuration [DRAFT (1.0-pre)] for more details). Hit the Login button to start the console.

The console has navigation options on the left, and a content area on the right.

Figure 2.5. Quick Start: Database Pools

To create a new database pool, Geronimo needs a JDBC driver. Geronimo ships with a JDBC driver for its embedded Apache Derby database, and can automatically download JDBC drivers for several popular open source databases (such as MySQL and PostgreSQL). For this quick start, we'll assume you create a Derby database pool, but you can also try configuring a pool pointing to a database of your own if you like (see Chapter 6, Database Configuration [DRAFT (1.0-pre)] for more details on creating custom database pools).

	Tip
	If you need to manually install a JDBC driver, create a directory named for the product under the repository/ directory and then a directory named jars/ under that, and copy the JDBC driver there (for example, for Oracle, create repository/oracle/jars/ and then copy the Oracle JDBC driver into there). For more information, see Section 6.1, “JDBC Drivers”.

To create a new Derby database:

To create a new database pool:

	Warning
	Derby lets you create a database on the fly by manipulating the connection URL, but due to a bug in Geronimo 1.0, it's not possible to configure this from the management console when the Tomcat web container is used (however, it does work in Jetty).

After creating the database pool, run the following SQL script to create sample tables to use to create a SQL security realm:

create table TEST_USER (
    username varchar(20) not null primary key,
    password varchar(20) not null,
    name varchar(50));
create table TEST_USER_GROUPS (
    username varchar(20) not null,
    group_name varchar(20) not null,
    primary key (username, group_name));
insert into TEST_USER values ('jdoe','secret','John Doe');
insert into TEST_USER_GROUPS values ('jdoe','Employees');
insert into TEST_USER_GROUPS values ('jdoe','Administrators');

	Tip
	If you're using the embedded Derby database, you can select the DB Manager entry in the console to run the SQL script. Select TestDatabase under Use DB, paste the script above into the SQL Command/s window, and then click Run SQL.

The next step is to create a sample security realm. We'll create a SQL security realm based on the database pool created above (for more details on creating security realms, see Chapter 9, Security Configuration [DRAFT (1.0-pre)]). To create the new SQL security realm:

This step walks through deploying a very simple web application (no additional configuration required), as well as a secure web application that needs to be hooked up to the security realm created in the previous step. If you have a simple web application (with no EJB references or resource references, etc.) to use as a test, you can try that (more details on the deployment options can be found in Chapter 10, Development & Deployment Overview [DRAFT (1.0)]), you can try that (and likewise, a simple web application that uses security but no resource references).

Otherwise, you can download a copy of the Geronimo Welcome web application and the Geronimo LDAP Demo web application (basically the same as you'd see at http://localhost:8080/ and http://localhost:8080/ldap-demo/ for a typical Geronimo install). The welcome application has no security and can be deployed as-is, while the LDAP demo application uses security so we can test the security realm created above. These applications are available at: http://cvs.apache.org/repository/geronimo/wars/geronimo-welcome-1.0-SNAPSHOT.war and http://cvs.apache.org/repository/geronimo/wars/geronimo-ldap-demo-1.0-SNAPSHOT.war.

First, you can try deploying the Welcome application with no additional Geronimo customization:

java -jar bin/deployer.jar deploy \
    geronimo-welcome-1.0-SNAPSHOT.war

To make sure this is running, try connecting to http://localhost:8080/geronimo-welcome-1.0-SNAPSHOT/. This is a very small web app, so if the page comes up at all, then it worked (and that's all there is to see).

Next, create a geronimo-web.xml deployment plan that configures a custom URL prefix and security for the LDAP Demo web application. This web application is normally used to demonstrate the functionality of an LDAP security realm, but will work just as well to demonstrate the test realm created above. The plan should look like this (and see Chapter 11, Web Applications (WARs) [DRAFT (1.0)] for more details on the web application Geronimo deployment plan):

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.0"
         configId="TestWebApplication">
    <context-root>/test-web</context-root>
    <context-priority-classloader>
        true
    </context-priority-classloader>
    <security-realm-name>TestRealm</security-realm-name>
    <security>
        <default-principal>
            <principal name="anonymous" class="org.
apache.geronimo.security.realm.providers.GeronimoUserPrincipal"
            />
        </default-principal>
        <role-mappings>
            <role role-name="content-administrator">
                <principal name="Administrators" class="org.
apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"
                />
            </role>
        </role-mappings>
    </security>
</web-app>

This plan:

	Warning
	Make sure to remove the whitespace in the principal class names in the plan listed above (2 places). The fully-qualified class names are only split across lines in that listing to fit the margins of the book -- they won't really work if entered that way.

To deploy the LDAP demo web application with this plan, use a command like this:

java -jar bin/deployer.jar deploy \
    geronimo-ldap-demp-1.0-SNAPSHOT.war geronimo-web.xml

To test the security realm, try connecting to http://localhost:8080/test-web/. From the front page there, click the Protect link to force a login (and use the username "jdoe" and password "secret" if you set up the sample security realm using the SQL in this quick start). You can also try the Forbidden link to make sure that pages you can't access are properly rejected with a 403 error.

That's it for the quick start. If you followed the whole thing, you:

If there are certain areas in the quick start that you want to investigate in more detail, you can follow the cross-references in the text. Otherwise, the following chapters will introduce you to each of the features of Geronimo in more depth.

When starting Geronimo, there are several options you may pass on the command line:

Additionally, it's possible to pass specific configuration names on the command line, such that Geronimo only starts with the listed configurations enabled. However, this is quite risky as if certain required configurations aren't listed, the server may not start properly or it may not be possible to deploy applications to the server. It's best to avoid this except in extreme circumstances.

Most server startup problems result in one or more stack traces. They also include a line like this:

16:26:01,753 ERROR [GBeanInstanceState] Error while starting;
   GBean is now in the FAILED state: objectName="geronimo.server:
   J2EEApplication=null,J2EEModule=org/apache/geronimo/Server,
   J2EEServer=geronimo,j2eeType=GBean,name=JettyWebConnector"

The "GBean is now in the FAILED state" message means that one of the services failed to start. The problem that caused this is usually in the stack trace after that. The most common problem is:

java.net.BindException: Address already in use
        at java.net.PlainSocketImpl.socketBind(Native Method)
        at java.net.PlainSocketImpl.bind(PlainSocketImpl.java:331)
        ...

This message means that one of the network ports that Geronimo is attempting to use is already in use. This often happens for port 8080, or possibly port 1099. If you can't shut down the product listening on the port in question, the best workaround is to reinstall Geronimo using the custom install process and pick different network ports for Geronimo on the main configuration screen. See Section 5.1, “Network Configuration” for a more detailed discussion of the network ports used by Geronimo.

Every component managed by the kernel is a Geronimo bean, or GBean. Further, some components are broken down and deployed as multiple GBeans, for more fine-grained monitoring and management. For example, when a J2EE application is deployed, a number of GBeans are deployed representing (among other things):

While GBeans representing application components are automatically created and deployed by the server, most GBeans can be configured and deployed manually. GBeans can declare read/write attributes, allowing the administrator to configure the GBean (for example, setting a port for the web application service to listen on). In addition, all GBeans can handle lifecycle events, implementing certain logic that should be run during startup or shutdown (for example, each web listener service starts an HTTP listener during startup, and stops it during shutdown). With these configuration and runtime features defined, GBeans can be monitored, configured, started, and stopped through the standard Geronimo management interface.

If you want to write additional components that should run in Geronimo, you can deploy new GBeans. You may encounter this, for example, if you want to deploy a custom JMS server configuration (see Section 7.5.2, “Message Broker GBean Configuration”), or if you want to add a brand new service. GBeans can be deployed as part of an application configuration, or as top-level standalone components in the Geronimo server. The same tools are used to deploy and manage GBeans as to deploy and manage J2EE applications.

The most important GBeans included with Geronimo are described in detail in Chapter 19, Overview of Core Geronimo Services [EMPTY].

When GBeans communicate with each other, they are not actually interacting directly. Instead, the kernel inserts a proxy in between, and the proxy provides only the methods that the destination GBean wants to expose. (In the case where there's an interface declaring the methods to be exposed, the proxy implements that interface.) So the actual communication looks more like this:

Figure 4.2. Communication Between GBeans

In this case, the EJB service needs a reference to a transaction manager, and the kernel gives it a proxy that implements the same interface as the actual TransactionManager GBean. This makes it easy to substitute transaction manager implementations, and gives the kernel the chance to manage the communication process between the two GBeans (including allowing one component to restart without forcing everything that depends on it to restart at the same time).

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

<web-app xmlns="http://geronimo.apache.org/xml/ns/web"
         configId="MyWebApp"
         parentId="ApplicationDatabasePool">
    <import>ApplicationJMSResources</import>
    ...

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.

<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>

<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>

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.xml

Another 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:

Every service, application, or resource in Geronimo is configured with an XML deployment plan. For application modules, there's typically one standard J2EE deployment descriptor (such as WEB-INF/web.xml or META-INF/ejb-jar.xml) and one Geronimo deployment plan (such as WEB-INF/geronimo-web.xml or META-INF/openejb-jar.xml). In some cases (particularly for simple application modules in an EAR) the default values are sufficient, in which case no Geronimo deployment plan actually needs to be present. However, this tends to be the exception rather than the rule.

	Tip
	You may be used to thinking of the Geronimo deployment plan as a "server-specific deployment descriptor". However, J2EE 1.4 and the J2EE Application Deployment specification introduced the term "deployment plan" to refer to this, and Geronimo has adopted that terminology.

A Geronimo deployment plan contains configuration information such as:

Like the J2EE deployment descriptors in J2EE 1.4, Geronimo deployment plans are defined by XML Schemas (as opposed to DTDs). Schemas are more flexible than DTDs, and can provide more validation than DTDs (for example, by identifying values that should be numeric). While the basic XML file structure is unchanged, the header of an XML document controlled by a Schema looks slightly different than a similar document controlled by a DTD.

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE web-app
  PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
  "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>
  ...
</web-app>

<?xml version="1.0" encoding="ISO-8859-1"?>

<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
             http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
         version="2.4">
  ...
</web-app>

Looking at Example 4.3, “Web Application Deployment Descriptor: Schema vs. DTD”, several things are apparent:

Like packages in Java, namespaces in XML are a way to separate XML element definitions by content area, or to avoid collisions between vendors who might use the same names for their elements. For example, all the J2EE elements are defined in the namespace http://java.sun.com/xml/ns/j2ee while Geronimo elements are in several namespaces, generally of the form http://geronimo.apache.org/xml/ns/... (there are separate namespaces for each Geronimo deployment plan type).

In many cases each XML file is controlled by a single Schema covering a single namespace. However, it's also possible to build a document including content from several namespaces -- typically one or more namespaces containing shared content, and a single namespace specific to the document in question. In that case, an element might declare a new prefix and indicate what namespace that prefix identifies. The element itself or any content within that element that uses the same prefix would be controlled by the Schema that defines the namespace for that prefix (see Example 4.4, “Nested Schemas in a Geronimo Deployment Plan”). Geronimo deployment plans sometimes use this, when common elements defined in a common schema are used in module-specific deployment plans.

<?xml version="1.0" encoding="ISO-8859-1"?>

<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.0"
         xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.0"
         configId="MyWebApp"
         parentId="MyEJBJar">
    <context-root>/MyWebApp</context-root>
    <context-priority-classloader>
      true
    </context-priority-classloader>
    <naming:resource-ref>
        <naming:ref-name>jdbc/DataSource</naming:ref-name>
        <naming:resource-link>
          DefaultDatasource
        </naming:resource-link>
    </naming:resource-ref>
</web-app>

Tip

When writing Geronimo deployment plans, you can omit the prefixes for the nested namespaces. In Example 4.4, “Nested Schemas in a Geronimo Deployment Plan”, for example, all the naming: prefixes could have been omitted. This can be useful when writing deployment plans by hand, and Geronimo will accept the plans using that syntax. However it is not actually valid XML. Therefore it's often better to use the proper namespace prefixes, as most XML tools or IDEs that support J2EE 1.4 can validate the structure of the properly-formatted deployment plan.

Geronimo can deploy any J2EE application module, either on its own or packaged into a J2EE application, including:

Each module includes a standard J2EE deployment descriptor, packaged into the module. In order to deploy a J2EE module in Geronimo, you typically need to provide a Geronimo deployment plan in addition. A Geronimo deployment plan can be provided in two ways:

Table 4.1, “Geronimo Deployment Plan File Names” summarizes the file names that should be used if a Geronimo deployment plan is packaged into a J2EE application module.

To deploy an application module with a deployment plan packaged in the module (in this case, WEB-INF/geronimo-web.xml), you could use a command like this:

java -jar bin/deployer.jar deploy mywebapp.war

To deploy the same with the deployment plan in a separate file (in this case mywebapp-plan.xml) you could use a command like this:

java -jar bin/deployer.jar deploy mywebapp.war \
       mywebapp-plan.xml

For more information on deployment options and what goes into the Geronimo deployment plan for each module, see Part III, “J2EE Applications on Geronimo”.

JDBC resources are implemented using a J2EE Connector, which means they are configured and deployed like any other application components. The Connector for a database connection pool can be deployed as a top-level module in the server, or included within an application EAR. Chapter 6, Database Configuration [DRAFT (1.0-pre)] has full details on configuring and deploying JDBC connection pools.

JMS resources are slightly different. A JMS Server must be running for any JMS resources to work. The JMS Server is implemented using GBeans, so it is configured and deployed like a custom service. Geronimo includes a configuration for a default JMS Server, so usually you can just leave that active and you don't need to worry about customizing GBeans.

JMS application resources like connection factories, topics, and queues are implementing using a J2EE Connector, which can be configured and deployed like any other application component, with the restriction that it depends on a running JMS Server. The Connector for JMS resources can be deployed as a top-level modules in the server, or included within an application EAR.

Chapter 7, JMS Configuration [DRAFT (1.0)] has full details on configuring and deploying a JMS Server and JMS resources.

Every service in Geronimo is deployed as a group of one or more GBeans. Typically, it is not necessary to customize or deploy any GBeans in order to run a J2EE application (Geronimo automatically creates GBeans for the application components, and you don't normally need to add any custom GBeans to an application). However, you might deploy custom GBeans to add new services to Geronimo. For example, you could deploy a GBeans that runs a more advanced scheduler than the EJB timer service. Chapter 18, GBeans: Adding New Services to Geronimo [EMPTY] describes how to construct GBeans to add new services to Geronimo.

In addition to deploying new services, it is also possible to reconfigure some of the basic GBeans provided with Geronimo. For example, Section 7.5.2, “Message Broker GBean Configuration” shows how to deploy a JMS Server with a nonstandard configuration.

Deploying GBeans involves creating a Geronimo deployment plan just like anything else you might deploy. For example, a deployment plan to add a scheduler might look like this:

scheduler-plan.xml

<deployment xmlns="http://geronimo.apache.org/xml/ns/deployment-1.0"
            configId="Scheduler">
  <dependency>
    <uri>scheduler/scheduler/1.5/jar</uri>
  </dependency>

  <gbean name="geronimo.server:type=Scheduler"
         class="com.example.SchedulerGBean">
    <attribute name="configDB" type="java.lang.String">
      MySchedulerDatabase
    </attribute>
  </gbean>  
</deployment>

To deploy the scheduler with the deploy tool, you could use a command like this:

java -jar bin/deployer.jar deploy scheduler-plan.xml

While deploying a database pool through the console, Geronimo can automatically download certain JDBC drivers and install them into the repository. This is limited to drivers that can be directly downloaded without logins, license agreements, etc. Currently that includes drivers for:

Also, note that Geronimo ships with drivers for the Derby database (both JDBC and XA).

This process is used for normal JDBC drivers, which will not be used in an XA/two-phase commit environment. It works with any database that has a JDBC driver available (though some drivers that are not "type 4" may also require native libraries to be configured before they work).

To begin the process of creating a new JDBC pool, select Database Pools from the left navigation bar of the console, to bring up the database pool list screen:

Figure 6.2. Console: List Database Pools

Click the create a new database pool Using the Geronimo database pool wizard link to begin the process.

6.3.1.1. Step 1: Basic Settings

This screen lets you select the pool name and basic database type:

Figure 6.3. Console: Database Pool -- Basic Settings

The fields here are:

Field	Description
Name of Database Pool	The name that applications will use to refer to this database pool. It should be different than the name used for any other resource in the server.
Database Type	If the correct database type is listed here, select it. (Note that some XA drivers are present in the list, but that's covered in the next section.) If the database type is not listed, select "Other" (and see Section 6.3.1.5, “Detailed Pool Edit Screen”).

Select Next to continue.

6.3.1.2. Step 2: Connection Properties

This screen handles the basic settings for the database pool:

Figure 6.4. Console: Database Pool -- Connection Properties

The fields here are:

Field	Description
JDBC Driver Class	The fully-qualified name of the JDBC driver class. Geronimo selects a default based on the database product selected. If unsure, refer to the JDBC driver documentation.
Driver JAR	A JAR in the Geronimo repository that holds the JDBC driver class. This will be added to the ClassPath of the database pool. The list here includes JARs available under the repository/ directory. If the correct driver JAR is not listed, either copy it into the repository and reload the page, or use the Download a Driver button to have Geronimo download a driver JAR for you.
DB User Name	The login name used to connect to the database.
DB Password	The password used to connect to the database.
Typical JDBC URL	The JDBC URL specifies the parameters needed to connect to the correct database. The form of the JDBC URL is different for every database product. This shows the outline of a normal JDBC URL for the database selected on the previous screen. Some values within the JDBC URL may need to be substituted, and the following fields on the screen let you enter values for those.

The rest of the fields are different depending on which database was selected -- if unsure, consult the JDBC driver documentation. However, many databases use some or all of the following common fields:

Field	Description
Host	The host name or IP address of the database server.
Port	The network port that the database server is listening on.
Database	The name of the database to connect to, if the server hosts multiple databases.

Select Next to continue. Note that if the select driver cannot be loaded from the selected JAR, then you'll be returned to this page with an error:

Figure 6.5. Console: Database Pool -- Driver Error

6.3.1.3. Step 3: Pool Properties

This screen confirms the JDBC URL based on the properties from the previous screen, and handles pool settings:

Figure 6.6. Console: Database Pool -- Pool Settings

The fields here are:

Field	Description
JDBC Connect URL	Confirms the JDBC URL that will be used to connect to the database. This is based on the standard URL format for this database and the values entered on the previous screen. You can tweak or override it here.
Driver Status	Confirms that the selected driver class could be loaded from the selected driver JAR.
Pool Min Size	The smallest number of connections that the database pool should have open at any time. The default is 0.
Pool Max Size	The largest number of connections that the database pool should have open at any time. If there are more clients than open connections, the pool will grow to its maximum size, and after that some clients will simply wait for a connection to be returned to the pool. The default is 10.
Blocking Timeout (milliseconds)	How long a client will wait for a connection to become available, if all connections in the pool are in use and the pool is at its maximum size. After this amount of time elapses with no connection available, the client will receive a SQLException indicating that no connections are available. The default is 5000.
Idle Timeout (minutes)	If a connection in the pool has gone this long without being used, it will be closed and the pool will shrink. The default is 15.

There are three paths forward from here:

• Test Connection: Attempts to open a database connection using the supplied values, to make sure the server can connect successfully.

• Skip Test and Deploy: Saves the connection pool without testing it first. After deploying, the console returns to the database pool list screen, where the new pool should be listed.

• Skip Test and Show Plan: Shows the RAR deployment plan that Geronimo will use for this pool. This is normally used if you don't want to deploy the pool server-wide, but want to copy the plan to use in an application-scoped or client-scoped pool. See Section 6.3.4, “Generate a Plan for an Application or Client Scoped Pool”.

6.3.1.4. Step 4: Test Pool

The test screen may show up one of two ways, depending on whether the test was successful.

Figure 6.7. Console: Database Pool -- Test Successful

If successful, you can select Deploy to deploy the pool and return to the database pool list screen, or select Show Plan to see the Geronimo deployment plan that will be used for the pool (see Section 6.3.4, “Generate a Plan for an Application or Client Scoped Pool”).

Figure 6.8. Console: Database Pool -- Test Failed

If the test failed, you have three options:

• Deploy Anyway: in case the database is just temporarily unavailable (deploys the pool and returns to the database pool list screen)

• Edit Settings: goes to the full edit screen to adjust the pool configuration (see Section 6.3.1.5, “Detailed Pool Edit Screen”)

• Test Again: in case you fixed something unrelated to the pool configuration and now the connection should work (reloads this same test screen)

6.3.1.5. Detailed Pool Edit Screen

If you select a database type of "Other" or choose to edit setting after a test failure, the console loads a single screen where you can edit all the settings for the pool:

Figure 6.9. Console: Database Pool -- Detailed Edit

The fields here are similar to the options available from the 4-step process:

Field	Description
Pool Name	The name that applications will use to refer to this database pool. It should be different than the name used for any other resource in the server.
Pool Type	Indicates which resource adapter will be used for this pool. For standard JDBC connection pools, this should be "TranQL Generic JDBC Resource Adapter" (it will be different for XA pools, and they will also have different configuration settings available on this screen).
JDBC Driver Class	The fully-qualified name of the JDBC driver class. Geronimo selects a default based on the database product selected. If unsure, refer to the JDBC driver documentation.
Driver JAR	A JAR in the Geronimo repository that holds the JDBC driver class. This will be added to the ClassPath of the database pool. The list here includes JARs available under the repository/ directory. If the correct driver JAR is not listed, either copy it into the repository and reload the page, or use the Download a Driver button to have Geronimo download a driver JAR for you.
JDBC Connect URL	Confirms the JDBC URL that will be used to connect to the database. This is based on the standard URL format for this database and the values entered on the previous screen. You can tweak or override it here.
DB User Name	The login name used to connect to the database.
DB Password	The password used to connect to the database.
Pool Min Size	The smallest number of connections that the database pool should have open at any time. The default is 0.
Pool Max Size	The largest number of connections that the database pool should have open at any time. If there are more clients than open connections, the pool will grow to its maximum size, and after that some clients will simply wait for a connection to be returned to the pool. The default is 10.
Blocking Timeout (milliseconds)	How long a client will wait for a connection to become available, if all connections in the pool are in use and the pool is at its maximum size. After this amount of time elapses with no connection available, the client will receive a SQLException indicating that no connections are available. The default is 5000.
Idle Timeout (minutes)	If a connection in the pool has gone this long without being used, it will be closed and the pool will shrink. The default is 15.

There are three paths forward from here:

• Test Connection: Attempts to open a database connection using the supplied values, to make sure the server can connect successfully. Continues to the test screen (see Section 6.3.1.4, “Step 4: Test Pool”).

• Skip Test and Deploy: Saves the connection pool without testing it first. After deploying, the console returns to the database pool list screen, where the new pool should be listed.

• Skip Test and Show Plan: Shows the RAR deployment plan that Geronimo will use for this pool. This is normally used if you don't want to deploy the pool server-wide, but want to copy the plan to use in an application-scoped or client-scoped pool. See Section 6.3.4, “Generate a Plan for an Application or Client Scoped Pool”.

Many databases support two-phase commit, also known as XA transactions. XA allows you to use more than one database, JMS connection, or other resource in a single transaction. However, this support is provided through an XADataSource, not the traditional JDBC driver. As a result, the configuration process is somewhat different.

Geronimo includes separate XA packages for each supported database (though the driver JAR is also required). The supported databases as of M5 are:

To configure a new XA database pool, start Geronimo, log in to the console and click the Database Pools link in the left navigation bar.

6.3.2.1. Create New Database Pool

Figure 6.10. Console: Database Pool List View

From the list of database pools on the right, select Add new database pool.

6.3.2.2. Step 1: Select Database Type

Figure 6.11. Console: Database Pool -- Select XA Database

The fields here are:

Field	Description
Name of Database Pool	The name that applications will use to refer to this database pool. It should be different than the name used for any other resource in the server.
Database Type	Select the database type, with "XA" in the name. If the XA driver for the database is not listed here, you will need to get both an XA driver for the database and a Geronimo integration package for it, and deploy the database pool at the command line.

Select Next to continue.

6.3.2.3. Step 2: Edit XA Database Pool Settings

This brings up the detailed database pool edit screen, configured for the selected XA driver:

Figure 6.12. Console: Database Pool -- New XA Database Pool

The fixed fields here (everything except the Basic Connection Properties) are:

Field	Description
Pool Name	The name that applications will use to refer to this database pool. It should be different than the name used for any other resource in the server. The value here is what you entered on the previous screen.
Pool Type	Indicates which Geronimo resource adapter will be used for this pool. This will normally be different for each XA driver.
Pool Min Size	The smallest number of connections that the database pool should have open at any time. The default is 0.
Pool Max Size	The largest number of connections that the database pool should have open at any time. If there are more clients than open connections, the pool will grow to its maximum size, and after that some clients will simply wait for a connection to be returned to the pool. The default is 10.
Blocking Timeout (milliseconds)	How long a client will wait for a connection to become available, if all connections in the pool are in use and the pool is at its maximum size. After this amount of time elapses with no connection available, the client will receive a SQLException indicating that no connections are available. The default is 5000.
Idle Timeout (minutes)	If a connection in the pool has gone this long without being used, it will be closed and the pool will shrink. The default is 15.

The remaining fields on this screen are database-specific configuration settings controlled by the XA driver implementation. If the supplied property names and descriptions are not helpful enough, consult the XA driver documentation.

The options to continue from here are Deploy (deploy the pool and return to the pool list screen) and Show Plan (show the Geronimo deployment plan that would be used but don't actually deploy it yet -- see the next section for details).

Geronimo can also import database pools from other application servers. That is, if you upload or point Geronimo to a database pool configuration file for another supported server, it will let you convert the settings from that to Geronimo. The servers currently supported are:

The import process starts on the pool list screen:

Figure 6.13. Console: Database Pool -- Start Import

Select one of the links starting with Import from... to begin the import.

6.3.3.1. Import File Selection

Most products let you upload a product-specific configuration file to Geronimo to begin the import. For example here is the import screen for JBoss:

Figure 6.14. Console: Database Pool -- JBoss Import

Simply choose the correct database pool or server configuration file (noted above the Next button) and hit Next to continue. For JBoss, this is a JBoss database pool deployment file, named something-ds.xml and usually in the deploy directory.

WebLogic has an additional configuration option. Uploading the config.xml as above strips out the database connection passwords. The alternative is to point the console to the WebLogic server/lib directory and WebLogic domain directory, and then Geronimo can recover the passwords along with the rest of the connectivity information. Of course, this only works if Geronimo and WebLogic are on the same machine, and if the WebLogic directory is readable to the user that started Geronimo. The WebLogic import screen looks like this:

Figure 6.15. Console: Database Pool -- WebLogic Import

In this case either select the config.xml file (top) or enter the directory paths (bottom) and click the corresponding Next button to continue.

6.3.3.2. Import Status

Once the configuration files have been identified and/or uploaded, Geronimo lists all the database pools it found on the import status screen:

Figure 6.16. Console: Database Pool -- Import Status

This screen shows all the pools that were found for import on the top, then the database pools configured in Geronimo already, then any messages generated during the import (usually related to content in the configuration file that was not processed). In Figure 6.16, “Console: Database Pool -- Import Status”, 6 pools were identified. One is listed as "Ignored" because it is an XA database pool but Geronimo does not have a corresponding XA driver (in this case, for Oracle). One is listed as "Deployed as..." because it was already processed when the screen shot was taken. The others have links to Confirm and Deploy, which is how you complete the import process for a database pool.

The confirm and deploy process loads the database pool edit screen (see Section 6.3.1.5, “Detailed Pool Edit Screen”) with all the settings Geronimo found in the imported database pool. Some settings may be missing if they could not be imported, and you may need to massage the imported data in any case (for example, if a WebLogic pool used the BEA driver for Oracle, it would need to be changed to the standard Oracle JDBC driver). Once you save the pool or cancel the editing process, the console returns to the import status screen.

When you've imported all the pools you're interested in, click Finish or Skip Remaining Pools to return to the main database pool list screen.

The database pool features in the console can't update an application or client configuration. However, they can generate a deployment plan that can be used elsewhere to either deploy the pool with the command-line tools, or to include the plan in an application or client module. This works for both standard JDBC and XA database pools.

To do this, follow the normal process to create a pool outlined in Section 6.3.1, “Create a new JDBC Pool” or Section 6.3.2, “Create a new XA Database Pool”. From the edit, pool properties, or test screens, select the command to Show Plan to bring up the plan screen.

6.3.4.1. Plan View

Figure 6.17. Console: Database Pool -- Show Plan

This screen shows the deployment plan that was generated based on the selections made on the previous screens. It also provides a command that could be used to deploy the pool on the command line, as well as providing a simple procedure to add the database pool to an EAR as an application-scoped pool.

The main step to take from this screen is to copy the entire contents of the Deployment Plan text area (using Ctrl-A or a similar shortcut to be sure). The next three sections discuss the different ways to use this plan.

	Tip
	If you plan to deploy more than one pool in the same server using this plan, be sure to change the configId attribute in the top connector element, and the name specified in the connectiondefinition-instance element.

6.3.4.1.1. Deploy via Command-Line Deploy Tool

To deploy via the command-line deploy tool, save the plan to a file on disk. Then that file can be used along with the listed RAR file to deploy the pool. (Note that the RAR file may be different for different types of pools, but the RAR file displayed on the screen in Figure 6.17, “Console: Database Pool -- Show Plan” is always the correct one based on the way the pool was configured.)

For example, if the plan was saved as GERONIMO_HOME/database-pool.xml, and it was a standard JDBC pool using the RAR file tranql/rars/tranql-connector-1.1.rar, then a deploy command might look like this:

java -jar GERONIMO_HOME/bin/deployer.jar deploy \
    GERONIMO_HOME/database-pool.xml \
    GERONIMO_HOME/repository/tranql/rars/tranql-connector-1.1.rar

6.3.4.1.2. Deploy as Application-scoped Pool

To deploy the pool as part of an EAR, save the plan to a file in the EAR, and copy the RAR file into the EAR as well. Again, note that the RAR file may be different for different types of pools, but the RAR file displayed on the screen in Figure 6.17, “Console: Database Pool -- Show Plan” is always the correct one based on the way the pool was configured.

The next step is to create or update the J2EE deployment descriptor and Geronimo EAR deployment plan to include the new module. The Geronimo deployment plan will also use an alt-dd element to indicate that the deployment plan for the RAR is actually in the EAR but not in the RAR file itself. For full details on this procedure, see Section 6.4.2.2, “Deploying an Application-Scoped Database Pool”.

6.3.4.1.3. Deploy as Client-scoped Pool

To deploy the pool as part of an application client module, you'll need to copy the database plan content into the client deployment plan, and refer to the correct RAR file from the client deployment plan as well. Again, note that the RAR file may be different for different types of pools, but the RAR file displayed on the screen in Figure 6.17, “Console: Database Pool -- Show Plan” is always the correct one based on the way the pool was configured.

For full details on this procedure, see Section 6.4.2.3, “Deploying a Client-Scoped Database Pool”.

To edit an existing database pool (either JDBC or XA), start Geronimo, log in to the console, and select Database Pools from the left navigation bar of the console. This brings up the database pool list screen:

6.3.5.1. Select Database Pool to Edit

Figure 6.18. Console: Database Pool List View

From the list of database pools on the right, select the edit link next to the database pool to edit. The edit screen will be configured slightly differently depending on whether this is a JDBC pool or an XA pool; these screens are described in the next two sections.

6.3.5.2. Edit JDBC Database Pool

The JDBC pool edit screen looks like this:

Figure 6.19. Console: Database Pool -- Edit JDBC Database Pool

The fields here are similar to the options available when creating a pool:

Field	Description
Pool Name	The name that applications will use to refer to this database pool. It cannot be changed after the pool has been deployed.
Pool Type	Indicates which resource adapter will be used for this pool. For standard JDBC connection pools, this should be "TranQL Generic JDBC Resource Adapter" (it will be different for XA pools, and they will also have different configuration settings as described in the next section).
JDBC Driver Class	The fully-qualified name of the JDBC driver class. The driver class or JAR cannot be changed after the pool has been deployed (the pool would need to be redeployed manually with an updated plan).
JDBC Connect URL	Confirms the JDBC URL that will be used to connect to the database. If unsure of the syntax, consult the documentation for the JDBC driver.
DB User Name	The login name used to connect to the database.
DB Password	The password used to connect to the database.
Pool Min Size	The smallest number of connections that the database pool should have open at any time.
Pool Max Size	The largest number of connections that the database pool should have open at any time. If there are more clients than open connections, the pool will grow to its maximum size, and after that some clients will simply wait for a connection to be returned to the pool.
Blocking Timeout (milliseconds)	How long a client will wait for a connection to become available, if all connections in the pool are in use and the pool is at its maximum size. After this amount of time elapses with no connection available, the client will receive a SQLException indicating that no connections are available.
Idle Timeout (minutes)	If a connection in the pool has gone this long without being used, it will be closed and the pool will shrink.

When the settings are correct, hit Save to save the new settings for the pool and return to the pool list screen. Currently there is no way for the console to test changes to an existing pool, though that should be added in a future release.

6.3.5.3. Edit XA Database Pool

The XA database pool edit screen looks like this:

Figure 6.20. Console: Database Pool -- New XA Database Pool

The fixed fields here (everything except the Basic Connection Properties) are:

Field	Description
Pool Name	The name that applications will use to refer to this database pool. It should be different than the name used for any other resource in the server. The value here is what you entered on the previous screen.
Pool Type	Indicates which Geronimo resource adapter will be used for this pool. This will normally be different for each XA driver.
Pool Min Size	The smallest number of connections that the database pool should have open at any time. The default is 0.
Pool Max Size	The largest number of connections that the database pool should have open at any time. If there are more clients than open connections, the pool will grow to its maximum size, and after that some clients will simply wait for a connection to be returned to the pool. The default is 10.
Blocking Timeout (milliseconds)	How long a client will wait for a connection to become available, if all connections in the pool are in use and the pool is at its maximum size. After this amount of time elapses with no connection available, the client will receive a SQLException indicating that no connections are available. The default is 5000.
Idle Timeout (minutes)	If a connection in the pool has gone this long without being used, it will be closed and the pool will shrink. The default is 15.

The remaining fields on this screen (the Basic Connection Properties) are database-specific configuration settings controlled by the XA driver implementation. If the supplied property names and descriptions are not helpful enough, consult the XA driver documentation.

When the settings are correct, hit Save to save the new settings for the pool and return to the pool list screen. Currently there is no way for the console to test changes to an existing pool, though that should be added in a future release.

No matter how you plan to deploy the database pool, the basic configuration format is the same. The only difference is that for server-wide and application-scoped database pools, the configuration goes in a standalone file, while for client-scoped database pools, the same configuration information is embedded in the module's Geronimo configuration file.

	Note
	Geronimo does not yet handle drivers that supply their own DataSource or ConnectionPoolDataSource; instead Geronimo uses the Driver class or XADataSource class supplied by the JDBC driver.

Since the pool is deployed as a connector, the configuration file is a connector deployment plan, using the same format covered in Chapter 13, J2EE Connectors (RARs) [DRAFT (1.0)]. For now, we'll look at the key elements of this file as far as database pools are concerned. Example 6.1, “Database Pool Deployment Plan” shows a sample database pool deployment plan. Note that the configuration information shown there may be saved to a file on its own or embedded in another file depending on how you deploy the database pool -- see Section 6.4.2, “Deploying a Database Pool” for more details.

<connector
    xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.0"
    version="1.5"
    configId="MyDatabase"
    parentId="geronimo/j2ee-server/1.0/car>

  <dependency>
    <uri>postgresql/pg74/213.jdbc3/jar</uri>
  </dependency>

  <resourceadapter>
    <outbound-resourceadapter>
      <connection-definition>
        <connectionfactory-interface>
          javax.sql.DataSource
        </connectionfactory-interface>
        <connectiondefinition-instance>
          <name>PostgreSQLDataSource</name>
          <config-property-setting name="UserName">
            dbuser
          </config-property-setting>
          <config-property-setting name="Password">
            dbpw
          </config-property-setting>
          <config-property-setting name="Driver">
            org.postgresql.Driver
          </config-property-setting>
          <config-property-setting name="ConnectionURL">
            jdbc:postgresql://localhost/mydb
          </config-property-setting>
          <config-property-setting name="CommitBeforeAutocommit">
            true
          </config-property-setting>
          <config-property-setting name="ExceptionSorterClass">
            org.tranql.connector.NoExceptionsAreFatalSorter
          </config-property-setting>
          <connectionmanager>
            <local-transaction/>
            <single-pool>
              <max-size>10</max-size>
              <min-size>0</min-size>
              <blocking-timeout-milliseconds>
                5000
              </blocking-timeout-milliseconds>
              <idle-timeout-minutes>30</idle-timeout-minutes>
              <match-one/>
            </single-pool>
          </connectionmanager>
        </connectiondefinition-instance>
      </connection-definition>
    </outbound-resourceadapter>
  </resourceadapter>
</connector>

The key attribute and elements here are:

For a more extensive discussion of the connectionmanager settings, see Section 13.3.2.2.1, “Connection Manager Configuration”.

The configuration properties for the connection pool are listed in Table 6.2, “Connection Pool Configuration Properties”. Note that the properties should always be specified exactly as listed (many databases use different names for the username and password, but Geronimo will handle that).

	Note
	It is not currently possible to pass arbitrary properties to the JDBC driver while making the connection. However, you may use a complex ConnectionURL if the driver allows additional properties to be added to the end of the URL instead.

Once the database pool deployment plan has been prepared, you can deploy the pool using one of the three methods described here. In any of these cases, you'll need the deployment plan, and the TranQL RAR file.

java -jar bin/deployer.jar deploy database-pool.xml \
     repository/tranql/rars/tranql-connector-1.1.rar

jar -tf my-app.ear
  my-web-app.war
  my-ejbs.jar
  tranql-connector-1.1.rar
  database-pool.xml
  META-INF/application.xml
  META-INF/geronimo-application.xml

<application 
       xmlns="http://java.sun.com/xml/ns/j2ee"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
       http://java.sun.com/xml/ns/j2ee/application_1_4.xsd"
       version="1.4">
    <module>
        <ejb>my-ejbs.jar</ejb>
    </module>
    <module>
        <web>
            <web-uri>my-web-app.war</web-uri>
            <context-root>/my-web-app</context-root>
        </web>
    </module>
    <module>
        <connector>tranql-connector-1.1.rar</connector>
    </module>
</application>

<application
       xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-1.0"
       configId="MyApplication">
    <module>
        <connector>tranql-connector-1.1.rar</connector>
        <alt-dd>database-plan.xml</alt-dd>
    </module>
</application>

<application-client xmlns=
  "http://geronimo.apache.org/xml/ns/j2ee/application-client-1.0"
  configId="MyClientConfig"
  clientConfigId="MyClient">
  ...
  <resource>
    <external-rar>
      tranql/tranql-connector/1.1/rar
    </external-rar>
    <connector
     xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.0"
     version="1.5"
     configId="MyDatabase">
      <dependency>
        <uri>postgresql/pg74/213.jdbc3/jar</uri>
      </dependency>

      <resourceadapter>
        <outbound-resourceadapter>
          <connection-definition>
            <connectionfactory-interface>
              javax.sql.DataSource
            </connectionfactory-interface>
            <connectiondefinition-instance>
              <name>PostgreSQLDataSource</name>
              <config-property-setting name="UserName">
                dbuser
              </config-property-setting>
              <config-property-setting name="Password">
                dbpw
              </config-property-setting>
              <config-property-setting name="Driver">
                org.postgresql.Driver
              </config-property-setting>
              <config-property-setting name="ConnectionURL">
                jdbc:postgresql://localhost/mydb
              </config-property-setting>
              <config-property-setting
                                 name="CommitBeforeAutocommit">
                true
              </config-property-setting>
              <config-property-setting
                                  name="ExceptionSorterClass">
                org.tranql.connector.NoExceptionsAreFatalSorter
              </config-property-setting>
              <connectionmanager>
                <local-transaction/>
                <single-pool>
                  <max-size>10</max-size>
                  <min-size>0</min-size>
                  <blocking-timeout-milliseconds>
                    5000
                  </blocking-timeout-milliseconds>
                  <idle-timeout-minutes>30</idle-timeout-minutes>
                  <match-one/>
                </single-pool>
              </connectionmanager>
            </connectiondefinition-instance>
          </connection-definition>
        </outbound-resourceadapter>
      </resourceadapter>
    </connector>
  </resource>
</application-client>

Once the database pool has been deployed, application modules can refer to it using the name specified in the configuration information. To do this, the application module first declares a resource-ref with a type of javax.sql.DataSource in its standard J2EE deployment descriptor. For example, a web application could do it like this:

WEB-INF/web.xml

<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
         http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
         version="2.4">
  ...
  <resource-ref>
    <res-ref-name>jdbc/DataSource</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>

The key elements here are:

Now in the Geronimo deployment plan for that module, you'll specify which connection pool in the server will be used to satisfy the data source required by the web module. A deployment plan that maps it to the database pool configured in Example 6.1, “Database Pool Deployment Plan” would look like this:

WEB-INF/geronimo-web.xml

<web-app
    xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.0"
    xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.0"
    ...>
    ...
    <naming:resource-ref>
        <naming:ref-name>jdbc/DataSource</naming:ref-name>
        <naming:resource-link>
          PostgreSQLDataSource
        </naming:resource-link>
    </naming:resource-ref>
</web-app>

The important elements here are:

With the resource-ref in the web.xml deployment descriptor and the resource-ref in the geronimo-web.xml deployment plan, if a servlet or other component of the web application looks in JNDI under java:comp/env/jdbc/DataSource, then it will find a javax.sql.DataSource that uses connections to the PostgreSQL database configured in Example 6.1, “Database Pool Deployment Plan”.

An EJB or Application Client could configure a database pool using the same resource reference elements shown above, though of course the rest of the deployment descriptor would look different.

	Tip
	This section did not cover all the options available in Geronimo deployment plans for the different application modules. For full details on customizing application modules, see Chapter 11, Web Applications (WARs) [DRAFT (1.0)], Chapter 12, Enterprise Java Beans (EJB JARs) [DRAFT (1.0)], and Chapter 14, Client Applications (Client JARs) [IN PROGRESS].

The application code necessary to access a database connection pool looks like this:

InitialContext ctx = new InitialContext();
DataSource ds = ctx.lookup("java:comp/env/jdbc/DataSource");
Connection con = ds.getConnection();

The JNDI location used to look up the pool is "java:comp/env/" followed by the res-ref-name specified for the resource-ref in the J2EE deployment descriptor. In Section 6.5.1, “Updating the Module's Deployment Information”, the res-ref-name was jdbc/DataSource so here we use the full JNDI location "java:comp/env/jdbc/DataSource".

Since the res-auth in the web.xml deployment descriptor was set to Container, the application code does not specify a username or password to use to connect to the database. If the res-auth had been set to Application, you'd pass a username and password to getConnection(), but be aware that using a variety of usernames for the database connections makes the pooling less efficient.

	Note
	Geronimo does not support a "global JNDI space" where all resource are listed. The only portable way for an application to access a database pool is to use a resource reference and access the pool through the component's local java:comp/env/ namespace as is described here.

To begin working with JMS resource groups, select the JMS Resources link in the left-side navigation bar:

Figure 7.2. Console: JMS Resource Group List

This screen lists the available JMS resource groups. For each group, it shows the group name followed by the name of the configuration that resource group was deployed in, and then a list of JMS resources (connection factories and destinations) included in that group. From here you can create a new JMS resource group using the links under Create a new JMS Resource Group at the bottom of the screen.

If you select one of the known JMS providers (currently only ActiveMQ), then the console will skip straight to the initial configuration screen. Otherwise, the process begins by selecting a JMS provider.

7.2.2.1. Select JMS Provider RAR

If you don't select one of the pre-configured JMS providers, you'll need to start by selecting the JMS provider RAR. A JMS server vendor may provider their own RAR, or you may find a third-party RAR know to be able to connect to a particular JMS server product. In either case, the RAR should be installed in the Geronimo repository (e.g. saved to a file such as repository/vendor/rars/some-jms-provider-1.0.rar).

Figure 7.3. Console: Select JMS Provider

This screen gives you a list of the RAR files in the repository to select from. Pick the RAR file for your JMS provider, and click Next to advance to the initial configuration screen.

7.2.2.2. Initial Configuration

This configuration screen is driven by the configuration parameters for the selected JMS provider RAR, but normally the settings here are used to identify the server to connect to:

Figure 7.4. Console: JMS Resource Group Configuration

The one field that's always present on this screen is:

Field	Description
Resource Group Name	A unique name used to identify this resource group. This is how the group is listed in the console, and it will also be needed by message-driven beans that use this resource group to connect to the JMS server.

All the other fields on this screen vary according to the selected JMS provider. Figure 7.4, “Console: JMS Resource Group Configuration” shows the settings for ActiveMQ, which is the most common JMS provider used with Geronimo.

From here, click the Next button to move on to the resource group progress screen.

7.2.2.2.1. ActiveMQ Configuration Settings

The configuration settings for this screen for the ActiveMQ JMS provider are:

Field	Description
ServerUrl	The URL used to connect to the JMS server. Normally this is tcp://localhost:61616 though for a custom ActiveMQ server configuration you can change the URL to refer to a different host or port, or even to use a different protocol entirely.
UserName	The user name used to connect to the ActiveMQ server. For the ActiveMQ server that runs as part of Geronimo, this is normally geronimo.
Password	The password used to connect to the ActiveMQ server. For the ActiveMQ server that runs as part of Geronimo, this is normally geronimo.
Clientid	A JMS client ID used for any connections to the ActiveMQ server. Normally it's better not to specify this for the entire resource group (e.g. leave it blank here).
UseEmbeddedBroker	If set to true, the resource group will start a new ActiveMQ broker to connect to. Normally this is not what you want since Geronimo already runs a configurable ActiveMQ broker, so this is usually set to the default value of false.
UseInboundSession	If true, both inbound and outbound sessions will share a single connection to conserve resources. This is normally not what you want, so this is usually set to the default value of false.
BrokerXmlConfig	If UseEmbeddedBroker is set to true, this value identifies an XML configuration file with the configuration settings that the broker should use (otherwise, it is ignored). By default, this file should be on the class path (so any path information would be applied within JARs on the class path, etc.). You may also specify a full URL (e.g. starting with http:// or file:/) to identify a file elsewhere.

7.2.2.3. Create Resource Group Progress

The next screen display the connection factories and destinations created for the resource group so far. The first time you get here, it just displays some help text as nothing has been created yet:

Figure 7.5. Console: JMS Resource Group Progress (First Time)

At this point, you can use the Add Connection Factory or Add Destination buttons to add resources to the resource group.

After you create each connection factory or destination, you'll return to this screen and see a list of the progress so far:

Figure 7.6. Console: JMS Resource Group Progress

The summary shows the resources added to the group so far. In addition to the buttons to add new resources, you can select Show Plan to see the Geronimo deployment plan for the resource group, or Deploy Now to finalize the resource group and deploy it to the current Geronimo server.

7.2.2.4. Add Connection Factory

To add a connection factory to the resource group, you must first select the connection factory type. Different JMS providers may support different types of connection factories, but the standard options are:

• javax.jms.ConnectionFactory (supports connections to both Topics and Queues)

• javax.jms.TopicConnectionFactory (supports connections to Topics only)

• javax.jms.QueueConnectionFactory (supports connections to Queues only)

Figure 7.7. Console: Select JMS Connection Factory Type

To proceed, select the desired JMS Factory Type and click Next. This brings up the configuration screen for the selected connection factory type:

Figure 7.8. Console: Configure JMS Connection Factory

The standard settings here are:

Field	Description
Connection Factory Name	A unique name for this connection factory. Applications that create a resource reference to the connection factory will need to use this name to refer to it.
Transaction Support	Defaults to the transaction support declared by the JMS provider's RAR. Normally this should not be changed.
Pool Min Size	The smallest number of connections that this connection factory should have open at any time. The default is 0.
Pool Max Size	The largest number of connections that this connection factory should have open at any time. If there are more clients than open connections, the pool will grow to its maximum size, and after that some clients will simply wait for a connection to be returned to the pool. The default is 10.
Blocking Timeout	How long a client will wait for a connection to become available, if all connections in the pool are in use and the pool is at its maximum size. After this amount of time elapses with no connection available, the client will receive an Exception indicating that no connections are available. The default is 5000 (in other words, 5 seconds).
Idle Timeout	If a connection in the pool has gone this long without being used, it will be closed and the pool will shrink. The default is 15 (minutes).

	Note
	Some JMS providers may offer additional configuration parameters for their connection factories. However, ActiveMQ uses only the standard settings described here.

From here, you can click Next to return to the resource group progress screen (see Section 7.2.2.3, “Create Resource Group Progress”).

7.2.2.5. Add Destination

To add a destination to the resource group, you must first select the destination type. The standard options are:

• javax.jms.Topic

• javax.jms.Queue

Figure 7.9. Console: Select JMS Destination Type

To proceed, select the desired JMS Destination Type and click Next. This brings up the configuration screen for the selected destination type:

Figure 7.10. Console: Configure JMS Destination

The one field that's always present on this screen is:

Field	Description
Message Destination Name	A unique name used to identify this destination. This will be needed by JMS clients or message-driven beans to send or receive messages using this destination.

All the other fields on this screen vary according to the selected JMS provider. Figure 7.10, “Console: Configure JMS Destination” shows the additional setting for ActiveMQ, which is the most common JMS provider used with Geronimo.

From here, you can click Next to return to the resource group progress screen (see Section 7.2.2.3, “Create Resource Group Progress”).

7.2.2.5.1. ActiveMQ Destination Configuration

The only destination configuration setting for the ActiveMQ JMS provider is:

Field

Description

PhysicalName

While the Geronimo configuration uses the Message Destination Name to refer to this destination, you can use this setting to actually map that to a destination with a different name in the underlying JMS server. There's not normally any reason to do this, so the PhysicalName is usually set to be the same as the Message Destination Name. It may be helpful if for some reason you don't want to change the deployment plan for an application but you still want to point it to a different underlying destination.

The JMS features in the console can't update an application or client configuration. However, they can generate a deployment plan that can be used elsewhere to either deploy the resource group with the command-line tools, or to include the plan in an application or client module.

To do this, follow the normal process to create a resource group outlined in Section 7.2.2, “Creating a new JMS Resource Group”. From the progress screen, select the command to Show Plan to bring up the plan screen:

Figure 7.11. Console: JMS Resource Group Deployment Plan

This screen shows the deployment plan that was generated based on the selections made on the previous screens. It also provides a command that could be used to deploy the resource group on the command line, as well as providing a simple procedure to add the resource group to an EAR as an application-scoped group.

The main step to take from this screen is to copy the entire contents of the Deployment Plan text area (using Ctrl-A or a similar shortcut to be sure). The next three sections discuss the different ways to use this plan.

	Tip
	If you plan to deploy more than one resource group in the same server using this plan, be sure to change the configId attribute in the top connector element, as well as the resourceadapter-name, the connectiondefinition-instance name for any connection factories, and the adminobject-instance message-destination-name for any destinations.

java -jar GERONIMO_HOME/bin/deployer.jar deploy \
    GERONIMO_HOME/jms-resource.xml \
    GERONIMO_HOME/repository/activemq/rars/activemq-ra-3.2.1.rar

The configuration information required for one or more JMS resources is typically combined into a single ActiveMQ RAR deployment plan. It uses the standard Connector deployment options described in Chapter 13, J2EE Connectors (RARs) [DRAFT (1.0)], though the most important options for JMS are covered here.

A typical resource group deployment plan would look like this:

<connector
    xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.0"
    configId="MyJMSResources"
    parentId="geronimo/activemq-broker/1.0/car">

  <resourceadapter>
    <!-- how to connect to the JMS Server -->
    <resourceadapter-instance>
      <resourceadapter-name>
        My JMS Resources
      </resourceadapter-name>
      <config-property-setting name="ServerUrl">
        tcp://localhost:61616
      </config-property-setting>
      <config-property-setting name="UserName">
        not needed
      </config-property-setting>
      <config-property-setting name="Password">
        not needed
      </config-property-setting>
      <workmanager>
        <gbean-link>DefaultWorkManager</gbean-link>
      </workmanager>
    </resourceadapter-instance>
    <!-- defines a ConnectionFactory -->
    <outbound-resourceadapter>
      <connection-definition>
        <connectionfactory-interface>
          javax.jms.ConnectionFactory
        </connectionfactory-interface>
        <connectiondefinition-instance>
          <name>MyConnectionFactory</name>
          <implemented-interface>
            javax.jms.QueueConnectionFactory
          </implemented-interface>
          <implemented-interface>
            javax.jms.TopicConnectionFactory
          </implemented-interface>
          <connectionmanager>
            <xa-transaction>
              <transaction-caching />
            </xa-transaction>
            <single-pool>
              <max-size>10</max-size>
              <min-size>0</min-size>
              <blocking-timeout-milliseconds>
                5000
              </blocking-timeout-milliseconds>
              <idle-timeout-minutes>
                0
              </idle-timeout-minutes>
              <match-one/>
            </single-pool>
          </connectionmanager>
        </connectiondefinition-instance>
      </connection-definition>
    </outbound-resourceadapter>
  </resourceadapter>
  <!-- defines a Topic -->
  <adminobject>
    <adminobject-interface>
      javax.jms.Topic
    </adminobject-interface>
    <adminobject-class>
      org.activemq.message.ActiveMQTopic
    </adminobject-class>
    <adminobject-instance>
      <message-destination-name>
        MyTopic
      </message-destination-name>
      <config-property-setting name="PhysicalName">
        MyTopic
      </config-property-setting>
    </adminobject-instance>
  </adminobject>
  <!-- defines a Queue -->
  <adminobject>
    <adminobject-interface>
      javax.jms.Queue
    </adminobject-interface>
    <adminobject-class>
      org.activemq.message.ActiveMQQueue
    </adminobject-class>
    <adminobject-instance>
      <message-destination-name>
        MyQueue
      </message-destination-name>
      <config-property-setting name="PhysicalName">
        MyQueue
      </config-property-setting>
    </adminobject-instance>
  </adminobject>
</connector>

This rather dense deployment plan has 4 basic sections:

7.3.1.2. Message Broker Connection Settings

The resourceadapter-instance block contains the settings used to connect to the message broker. They are:

resourceadapter-name element

A name used to identify this resource adapter. This setting is not used elsewhere, and can be whatever you want.

ServerUrl configuration property

The method used to contact the message broker. This should match one of the ActiveMQConnectors deployed as part of the message broker.

UserName configuration property

A user name used to connect to the message broker. Not needed for the basic ActiveMQ message broker.

Password configuration property

A password used to connect to the message broker. Not needed for the basic ActiveMQ message broker.

workmanager element

A work manager handles certain tasks on behalf of the resource adapter. The name specified in the nested gbean-link element must match a WorkManager instance running in Geronimo. Unless you have manually configured a WorkManager, leave this set to DefaultWorkManager.

Tip

The work manager handles providing worker threads to a J2EE Connector, typically using a thread pool instead of (in the case of JMS) creating a separate thread to deliver every message. A custom work manager might be used to provide different threading behavior, such as higher-priority threads for a certain JMS configuration. However, this sort of change has not been tested with the current release.

With the deployment plan and the ActiveMQ RAR (located at geronimo/repository/activemq/rars/activemq-ra-3.2.1.rar), you can deploy the JMS resources.

java -jar bin/deployer.jar deploy jms-resource-plan.xml \
        repository/activemq/rars/activemq-ra-3.2.1.rar

7.3.2.2. Application-Scoped Deployment

To deploy application-scoped JMS Resources, you'll include the ActiveMQ RAR as a module in your application EAR. First you should save the JMS Resource deployment plan to a file like jms-resource-plan.xml (the name can be anything you like). Then you need to add that along with the ActiveMQ RAR to your EAR.

For example, the EAR structure might look like this:

jar -tf my-app.ear
  my-web-app.war
  my-ejbs.jar
  activemq-ra-3.2.1.rar
  jms-resource-plan.xml
  META-INF/application.xml
  META-INF/geronimo-application.xml

Notice the ActiveMQ RAR and the JMS Resource deployment plan. You should add a reference to the ActiveMQ RAR to the standard META-INF/application.xml deployment descriptor, and add a reference to the JMS Resource deployment plan to the META-INF/geronimo-application.xml deployment plan. This might be the only entry in the geronimo-application.xml file, so you'll need to create that file if you don't have one already.

The application.xml file for the EAR above would look like this:

META-INF/application.xml

<application 
       xmlns="http://java.sun.com/xml/ns/j2ee"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
       http://java.sun.com/xml/ns/j2ee/application_1_4.xsd"
       version="1.4">
    <module>
        <ejb>my-ejbs.jar</ejb>
    </module>
    <module>
        <web>
            <web-uri>my-web-app.war</web-uri>
            <context-root>/my-web-app</context-root>
        </web>
    </module>
    <module>
        <connector>activemq-ra-3.2.1.rar</connector>
    </module>
</application>

Notice the final module entry for the RAR.

The geronimo-application.xml file identifying the JMS Resource deployment plan would look like this:

META-INF/geronimo-application.xml

<application
  xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-1.0"
  configId="MyApplication">
    <module>
        <connector>activemq-ra-3.2.1.rar</connector>
        <alt-dd>jms-resource-plan.xml</alt-dd>
    </module>
</application>

Using the alt-dd element, the deployment plan for the application indicates that the JMS Resource deployment plan for the connector is included as a separate file in the EAR, instead of being packaged into the RAR. The elements here look very similar to the elements in the standard application.xml deployment descriptor, but if we specify an alt-dd there it means an alternate standard J2EE deployment descriptor, whereas specifying the alt-dd here means an alternate Geronimo deployment plan for the connector.

With this configuration, the JMS resources will be started when the application is started.

	Tip
	For more information on the geronimo-application.xml file, see Chapter 15, Enterprise Applications (EARs) [DRAFT (1.0)].

<application-client xmlns=
  "http://geronimo.apache.org/xml/ns/j2ee/application-client-1.0"
  configId="MyClientConfig"
  clientConfigId="MyClient">
  ...
  <resource>
    <external-rar>
      activemq/activemq-ra/3.2.1/rar
    </external-rar>
    <connector
     xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.0"
     configId="MyJMSResources"
     parentId="geronimo/activemq-broker/1.0/car">
      ...
    </connector>
  </resource>
</application-client>

Once the JMS resources have been deployed, application modules can refer to them using the names specified in the JMS Resource deployment plan. ConnectionFactories are mapped by the name specified in the outbound-resourceadapter block (for example, MyConnectionFactory in Example 7.1, “JMS Resource Group Deployment Plan”), while destinations are mapped by the message-destination-name specified in the adminobject block (for example, MyQueue and MyTopic in Example 7.1, “JMS Resource Group Deployment Plan”).

To map a connection factory, the application module first declares a resource-ref with a type of javax.jms.ConnectionFactory in its standard J2EE deployment descriptor. To map a destination, the module declares a message-destination-ref with a type of javax.jms.Queue or javax.jms.Topic and links it to a message-destination with the same message-destination-name as we used for the adminobjects in the JMS resource deployment plan. For example, a web application could do one of each like this:

WEB-INF/web.xml

<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
         http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
         version="2.4">
  ...
  <resource-ref>
    <res-ref-name>jms/AConnectionFactory</res-ref-name>
    <res-type>javax.jms.ConnectionFactory</res-type>
    <res-auth>Container</res-auth>
    <res-sharing-scope>Shareable</res-sharing-scope>
  </resource-ref>
  <message-destination-ref>
    <message-destination-ref-name>
      jms/ATopic
    </message-destination-ref-name>
    <message-destination-type>
      javax.jms.Topic
    </message-destination-type>
    <message-destination-usage>
      Consumes
    </message-destination-usage>
    <message-destination-link>MyTopic</message-destination-link>
  </message-destination-ref>
  <message-destination-ref>
    <message-destination-ref-name>
      jms/AQueue
    </message-destination-ref-name>
    <message-destination-type>
      javax.jms.Queue
    </message-destination-type>
    <message-destination-usage>
      Produces
    </message-destination-usage>
    <message-destination-link>MyQueue</message-destination-link>
  </message-destination-ref>
  <message-destination>
    <message-destination-name>MyTopic</message-destination-name>
  </message-destination>
  <message-destination>
    <message-destination-name>MyQueue</message-destination-name>
  </message-destination>
</web-app>

The important elements here are:

Because of the mapping done between the message-destination-name here and the message-destination-name in the adminobject, no further configuration is required for message destinations. However, the mapping for the connection factory is not yet complete.

In the Geronimo deployment plan for that module, you'll specify which JMS connection factory in the server will satisfy the connection factory reference declared by the web module. A deployment plan that maps the reference above to the connection factory configured in Example 7.1, “JMS Resource Group Deployment Plan” would look like this:

WEB-INF/geronimo-web.xml

<web-app
    xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.0"
    xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.0"
    configId="MyWebApp">
    ...
    <naming:resource-ref>
        <naming:ref-name>
          jms/AConnectionFactory
        </naming:ref-name>
        <naming:resource-link>
          MyConnectionFactory
        </naming:resource-link>
    </naming:resource-ref>
</web-app>

The important elements here are:

With the configuration above, if a servlet or other component of the web application looks in JNDI under java:comp/env/jms/AConnectionFactory, then it will find a javax.jms.ConnectionFactory that connects to the JMS Server we configured. If the component looks under java:comp/env/jms/AQueue or java:comp/env/jms/ATopic, it will find a javax.jms.Queue or javax.jms.Topic, which can be used in conjunction with the ConnectionFactory to communicate with a specific JMS topic or queue.

	Tip
	This section did not cover all the options available in Geronimo deployment plans for the different application modules. For full details on customizing application modules, see Chapter 11, Web Applications (WARs) [DRAFT (1.0)], Chapter 12, Enterprise Java Beans (EJB JARs) [DRAFT (1.0)], and Chapter 14, Client Applications (Client JARs) [IN PROGRESS].

The application code necessary to use a JMS destination looks like this:

InitialContext ctx = new InitialContext();
TopicConnectionFactory tcf =
       ctx.lookup("java:comp/env/jms/AConnectionFactory");
TopicConnection connection = tcf.createTopicConnection();
Topic topic = ctx.lookup("java:comp/env/jms/ATopic");
connection.start();
TopicSession session = connection.createTopicSession(false,
                                       Session.AUTO_ACKNOWLEDGE);
TopicPublisher publisher = session.createPublisher(topic);
Message message = ...;
publisher.publish(message);

This example looked up the connection factory and topic at the JNDI locations defined by the references in Section 7.4.1, “Updating the Module's Deployment Information”.

A typical configuration is to deploy a server-wide message broker, and then attach various application-scoped resources to it. Geronimo ships with a basic server-wide message broker configuration called geronimo/activemq-broker/1.0/car. It is started when Geronimo is started in the default configuration, but if it gets disabled for any reason, you can manually start it using a command like this (while the server is running):

java -jar bin/deployer.jar start geronimo/activemq-broker/1.0/car

This configuration includes a TCP transport on port 61616 and a direct transport for clients in the same JVM.

For a more detailed ActiveMQ configuration, you'll use XML snippets to configure the GBeans for the message broker. Depending on how you choose to deploy the broker, you may create a deployment plan to hold these, or you may insert them into the deployment plan for an existing application or module.

	Tip
	GBean configuration and deployment is covered in greater detail in Chapter 18, GBeans: Adding New Services to Geronimo [EMPTY]. The current section gives you enough to deploy a custom message broker, but does not cover the full syntax or options for arbitrary Geronimo services.

A sample GBean configuration looks like this:

<import>
  <groupId>geronimo</groupId>
  <type>car</type>
  <artifactId>system-database</artifactId>
  <version>1.0</version>
</import>
<dependency>
  <groupId>activemq</groupId>
  <artifactId>activemq-core</artifactId>
  <version>3.2.1</version>
</dependency>
<dependency>
  <groupId>activemq</groupId>
  <artifactId>activemq-gbean</artifactId>
  <version>3.2.1</version>
</dependency>
<dependency>
  <groupId>activeio</groupId>
  <artifactId>activeio</artifactId>
  <version>2.0-r118</version>
</dependency>

<!-- One ActiveMQ Manager should be present in the server at 
     all times.  If the default ActiveMQ broker is running
     then this plan doesn't need one, but if this is the only
     ActiveMQ broker then it should list the manager GBean. -->
<gbean name="ActiveMQ"
     class="org.activemq.gbean.management.ActiveMQManagerGBean"/>

<!-- Message Broker GBeans -->
<gbean name="ActiveMQ"
       class="org.activemq.gbean.ActiveMQContainerGBean">
  <attribute name="brokerName">
    possibly-unique-broker
  </attribute>
  <reference name="persistenceAdapter">
    <gbean-name>
    geronimo.server:j2eeType=JMSPersistence,name=ActiveMQ.cache,*
    </gbean-name>
  </reference>
</gbean>

<gbean name="ActiveMQ.cache" class=
   "org.activemq.store.cache.SimpleCachePersistenceAdapterGBean">
  <attribute name="cacheSize">10000</attribute>
  <reference name="longTermPersistence">
    <gbean-name>
  geronimo.server:j2eeType=JMSPersistence,name=ActiveMQ.journal,*
    </gbean-name>
  </reference>
</gbean>

<gbean name="ActiveMQ.journal" class=
     "org.activemq.store.journal.JournalPersistenceAdapterGBean">
  <reference name="serverInfo">
    <module>geronimo/j2ee-system/1.0/car</module>
    <type>GBean</type>
    <name>ServerInfo</name>
  </reference>
  <attribute name="directory">var/activemq/journal</attribute>
  <attribute name="journalType">default</attribute>
  <reference name="longTermPersistence">
    <gbean-name>
     geronimo.server:j2eeType=JMSPersistence,name=ActiveMQ.jdbc,*
    </gbean-name>
  </reference>
</gbean>

<gbean name="ActiveMQ.jdbc"
     class="org.activemq.store.jdbc.JDBCPersistenceAdapterGBean">
  <reference name="dataSource">
    <gbean-name>
      geronimo.server:J2EEApplication=null,J2EEServer=geronimo,
      JCAResource=geronimo/system-database/1.0/car,
      j2eeType=JCAManagedConnectionFactory,name=SystemDatasource
    </gbean-name>
  </reference>
</gbean>

<gbean name="ActiveMQ.tcp.localhost.61616"
       class="org.activemq.gbean.ActiveMQConnectorGBean">
  <attribute name="url">tcp://localhost:61616</attribute>
  <reference name="activeMQContainer">
    <gbean-name>
      geronimo.server:j2eeType=JMSServer,name=ActiveMQ,*
    </gbean-name>
  </reference>
</gbean>

<gbean name="ActiveMQ.vm.localhost"
       class="org.activemq.gbean.ActiveMQConnectorGBean">
  <attribute name="url">vm://localhost</attribute>
  <reference name="activeMQContainer">
    <gbean-name>
      geronimo.server:j2eeType=JMSServer,name=ActiveMQ,*
    </gbean-name>
  </reference>
</gbean>

This is basically split into two parts, a list of dependencies, and a set of GBeans.

	Warning
	The example above uses the same names as the actual ActiveMQ broker configured in Geronimo. Make sure to change all the GBean names and references if you want to deploy another broker in addition to the default geronimo/activemq-broker/1.0/car configuration (instead of replacing it).

The GBeans for the message broker can be deployed in any of the three scopes, though normally they're deployed server-wide.

<configuration configId="MyJMSBroker"
        xmlns="http://geronimo.apache.org/xml/ns/deployment-1.0">
  <!-- dependency and gbean elements here -->
</configuration>

java -jar bin/deployer.jar deploy message-broker-plan.xml

<application
   xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-1.0"
   configId="MyApplication">
  <!-- dependency elements here -->
  ...
  <!-- gbean elements here -->
</application>

<application-client xmlns=
  "http://geronimo.apache.org/xml/ns/j2ee/application-client-1.0"
  configId="MyClientConfig"
  clientConfigId="MyClient">
  <!-- dependency elements here -->
  ...
  <!-- gbean elements here -->
</openejb-jar>

A user may login to Geronimo in several ways, including:

In any of those cases, the user will be authenticated by a Geronimo security realm. In the common case, that means validating a username and password, though Geronimo can also handle Kerberos authentication and Client Certificate authentication as well.

When a security realm authenticates a user, it will provide one or more java.security.Principal objects for the user. Each principal typically represents a user or group, so the most likely case is that a security realm would return a single user principal and a number of group principals for the user who just logged in. However, Geronimo doesn't restrict principals to users and groups -- a security realm may provide principals representing anything at all. For example, a site that tracks your school classmates might provide a principal for each school you attended, or a site that tracks pets may return a principal indicating whether you own dogs, cats, or goldfish. While it would be possible to represent these all as "groups", such as a group called "DogOwners", it may be less cumbersome for the realm to just represent this as a PetOwnerPrincipal with the name "dog"

Since Geronimo doesn't know exactly what kind of principals will be returned by any particular security realm, it falls on you to configure a list of which Principals from the realm get which access rights in the server.

Geronimo security realms are built around the Java Authentication and Authorization Service (JAAS). A Geronimo security realm uses one ore more JAAS LoginModules to process authentication requests, and a Geronimo security realm can also itself be exposed as a JAAS LoginModule to outside applications that want to validate against the Geronimo realm (such as application clients).

Internally, the security realm basically identifies a list of configured LoginModules, says what order they should be processed in, which ones must agree to the login to allow it to proceed, and so on. The bulk of the work takes place within the individual LoginModules. The LoginModules configured for a security realm may do things like:

Additionally, third-party or custom JAAS LoginModule can be added to a Geronimo security realm and will work as-is (no Geronimo-specific code is necessary).

A JAAS LoginModule provides the basic capabilities of prompting the user (typically for a username and password), validating the information they provide, and then creating a Subject containing the Principal entries for that user. Some other part of the system can then examine the principals in that subject, and decide whether to permit the user to access secured resources. As far as the login module is concerned, it is communicating directly with a user, so it can provide a prompt (or Callback) for the user to supply a username, password, and any other important information, and it expects the user to fill out the correct values. In practice, in a Geronimo security realm, it is Geronimo that actually gathers authentication information from the user, so the login module sends callbacks to Geronimo, and Geronimo populates them on behalf of the user. The login module's behavior is unchanged, though -- it still produces a subject for a successful login, and Geronimo will use the principals included in that subject to decide which services and resources the user should have access to.

Note that login modules can also take other action, with a Subject or Principal or otherwise. For example, an auditing LoginModule may simply record the username and time of every login attempt, without changing the Subject or Principals for the login attempt.

Geronimo ships with login modules that handle many common cases:

When a JAAS client attempts to log in, it identifies the login module to use by specifying a configuration name. That configuration name must correspond to a configuration that JAAS is aware of, so JAAS can delegate to the correct underlying LoginModules.

In a typical JAAS environment, there is a file listing all the configurations. However, Geronimo needs more control over the JAAS configuration process (because, for instance, Geronimo security realms can be added and removed at runtime). So in Geronimo, there are ConfigurationEntry GBeans that define the available login modules. When a new security realm is deployed, it actually needs to include one GBean for the realm and another GBean with the JAAS configuration entry for the realm. That way, the JAAS configuration system is made aware of new security realms as they are added.

	Note
	The details of the configuration entries are not typically important for end users, but may be relevant for securiry administrators with more advanced needs.

Application modules in Geronimo may be secured to limit access to members of a certain application role. Once a user has logged in and been authenticated by a login module, the server has a set of principals for the user, but it's still not clear which principals qualify for which roles. To resolve this, the Geronimo deployment plan for a module can list the principals from each security realm that should count as members of each role. With this information, Geronimo can list the principals for the current user, and then compare that to the set of principals for each role that's allowed to access the protected resource, and see if there are any principals in common. If any of the user's principals are the same as any of the required principals, then the access is allowed.

Geronimo does not natively support web-based single sign-on across web sites. However, it is possible for a user to achieve some level of single sign-on within the Geronimo server. For example, a user "joe.smith" may log in to a web application, using that same account to access a secure EJB. However, that secure EJB may access a database or other back-end system that requires a different sign-on, perhaps "jsmith" with a separate password.

To accommodate this, it's possible to add two LoginModules to a security realm where the first validates in the initial (in this case web) login, and the second notices the successful login and adds a separate username and password to the user's Subject such that if they end up accessing the back-end system the information for the second account will already be in the user's Subject and no additional authentication steps are required.

The most convenient way to configure a security realm is to use the Geronimo console. To get started, log in to the console and select Security Realms from the navigation area on the left:

	Tip
	Before creating a SQL security realm, create a database pool using the Database Pools entry in the console. For more details on creating database pools in the console, see Section 6.3, “Easy Configuration and Deployment using the Console”.

Figure 9.1. Console: List Security Realms

This screen lists the available security realms. Click the Add new security realm link to begin the process of creating a security realm.

9.2.1.1. Step 1: Basic Settings

The first screen collects the basic settings for the new security realm:

Figure 9.2. Console: Security Realm -- Basic Settings

The two settings on this screen are:

Field	Description
Name of Security Realm	The name that applications will use to refer to this security realm. It should be different than the name used for any other resource in the server.
Realm Type	To use a security realm made up of standard Geronimo login modules, select the type here. If you want to use a custom login module type, include multiple login modules that perform authentication, or have full control over login domain names and other advanced features, select "Other" (and see Section 9.2.1.5, “Creating Custom Security Realms”).

Select Next to continue.

9.2.1.2. Step 2: Main Settings

For the basic realm types, the next screen shows the configuration options for the selected type:

Figure 9.3. Console: Security Realm -- Main Settings

Each realm type has different settings on this screen (it essentially lets you configure the main login module for the realm). The options for each realm are described on the screen (or see Section 9.2.3, “Configuration Options for Standard Login Modules” for more information). Figure 9.3, “Console: Security Realm -- Main Settings” shows the settings for a SQL realm.

Select Next to continue.

9.2.1.3. Setp 2: Advanced Settings

The next screen shows standard login options available to security realms in Geronimo. Under the covers, these are implemented by separate login modules, so that selecting options here configures additional login modules for the realm.

Figure 9.4. Console: Security Realm -- Advanced Settings

The options available on this screen are:

Field	Description
Enable Auditing	If selected, login attempts will be recorded in a log file. Each login attempt will generally produce two lines ouf output, one listing the user attempting to authenticate, and one indicating whether the overall authentication process succeeded or failed.
Log File	The path to the log file (relative to the Geronimo installation directory).
Enable Lockout	If selected, user accounts will be locked out after too many failed login attempts in a particular time frame (that is, any subsequent login attempts will fail no matter what password is provided). If an account is locked there will not be any particular error message; logins will just fail until the lockout expires.
Lock a user after __ failures	The number of failures that cause the account to be locked. Default 5 failures.
within __ seconds	The window of time in which that many failures must happen for the account to be locked (in seconds). Default 5 minutes.
locked for __ seconds	If the account is locked, how long the user should stay locked out. There is no way to manually lock or unlock an account. Default 30 minutes.
Store Password	Normally not necessary. This is an advanced feature that will save the user's password in their Subject, so later custom security hooks can access it.

From here, there are three ways to proceed:

Test a Login

If the login module can be tested, continues to the next screen where you can enter a username and password and see if the login module allows access. This is typically used just to ensure that the fundamental settings are correct. Note that not all realms can be tested (e.g. Kerberos or Client Certificates). See Section 9.2.1.4, “Step 4: Test Login”.

Skip Test and Deploy

Deploys the security realm with the collected configuration information. This returns to the security realm list screen. If there is an error deploying the security realm, it will be printed to the server log.

Skip Test and Show Plan

Shows the Geronimo deployment plan constructed for the security realm. This can be used to deploy the realm as an application-scoped realm or to save the configuration for later use or automated deployment, etc. See Section 9.2.1.7, “Generate a Plan for an Application Scoped Realm”.

9.2.1.4. Step 4: Test Login

If the login test is selected, this screen prompts for a username and password:

Figure 9.5. Console: Security Realm -- Test Login

Enter a valid username and password for the realm and select Next to continue. This will result in one of the following two screens, depending on whether the login was successful.

Figure 9.6. Console: Security Realm -- Test Login Failure

This screen indicates that the login failed. From here you can try again (Test Again), adjust the configuration for the realm (Edit Realm), show the Geronimo deployment plan generated for the realm (Show Plan), or ignore the failure and deploy the realm anyway (Deploy Realm).

Figure 9.7. Console: Security Realm -- Test Login Success

This screen indicates that the login succeeded. It shows which principals were generated for the user, with the principal name and principal class for each. This information (the principal class and name) can be used to map J2EE roles to specific users or groups in the security realm (see Section 9.4.2, “Mapping Roles to Principals”).

From here, there are four options:

Test Again

Run the test again with a different login.

Edit Realm

Adjust the configuration for the realm.

Show Plan

Show the Geronimo deployment plan constructed for the security realm. This can be used to deploy the realm as an application-scoped realm or to save the configuration for later use or automated deployment, etc. See Section 9.2.1.7, “Generate a Plan for an Application Scoped Realm”.

Deploy Realm

Deploys the security realm with the collected configuration information. This returns to the security realm list screen. If there is an error deploying the security realm, it will be printed to the server log.

9.2.1.5. Creating Custom Security Realms

To create a security realm using non-standard login module, or to configure a realm with more control over the individual login modules and configuration, add a new realm from the realm list screen and select a Realm Type of Other:

Figure 9.8. Console: Security Realm -- Create Custom Realm

This brings up the detailed realm edit screen:

Figure 9.9. Console: Security Realm -- Configure Custom Realm

This screen has configuration settings for the realm and up to 5 login modules. The available settings are the same for all 5 login modules. If there are fewer than 5 login modules for the realm, the settings for all the additional login modules may be left blank. The available settings are:

Field	Description
Login Domain Name	A name that uniquely identifies this login module. This can be used for advanced security role mapping, to distinguish between principals that come from 2 otherwise identical login modules (for example, two LDAP realms pointing to two distinct LDAP servers). Otherwise, this typically just needs to be different than the login domain name set for other login modules.
Login Module Class	The fully-qualified class name for the login module. This class must implement javax.security.auth.spi.LoginModule.
Control Flag	Each login module has a control flag, indicating what should happen to the overall login process if this module succeeds or fails. For example, it might be Required (this login module must succeed in order for the overall login to succeed, but other login modules will still be called even if this module fails). For more detail on JAAS control flags, see the JavaDoc for the JAAS Configuration class. If there's only one login module in the realm, it should typically be set to Required.
Server-Side	Most login modules should be run on the server side. Unless you know other wise, this should be set to Server Side. However, some modules such as the Kerberos login module have components that must run on the client side, and in that case this should be set to Client Side.
Configuration Options	Each login module takes a number of custom configuration options (for example, a debug option that may be set to true or false). In this box, you can enter any number of configuration options using the standard Java properties file format (one option per line, with the form name=value).

	Tip
	If the security realm has multiple login modules, the Control Flag is particularly important to establish the relationship between the modules, and which modules will be run depending on whether the ones before them succeeded or failed. The order of the login modules is also important, in case the control flag for one of them is set such that success or failure stops the login process.

From here, there are two options:

Show Plan

Show the Geronimo deployment plan constructed for the security realm. This can be used to deploy the realm as an application-scoped realm or to save the configuration for later use or automated deployment, etc. See Section 9.2.1.7, “Generate a Plan for an Application Scoped Realm”.

Deploy

Deploys the security realm with the collected configuration information. This returns to the security realm list screen. If there is an error deploying the security realm, it will be printed to the server log.

9.2.1.6. Editing Existing Security Realms

Editing existing security realms is similar to creating a custom security realm. To begin, click the edit link to the right of one of the realms on the initial security realm list screen. That brings up the edit screen:

Figure 9.10. Console: Security Realm -- Edit Realm

This screen has configuration settings for each of the login modules in the realm. The available settings are the same for all the login modules:

Field	Description
Login Module Class	The fully-qualified class name for the login module. This class must implement javax.security.auth.spi.LoginModule.
Control Flag	Each login module has a control flag, indicating what should happen to the overall login process if this module succeeds or fails. For example, it might be Required (this login module must succeed in order for the overall login to succeed, but other login modules will still be called even if this module fails). For more detail on JAAS control flags, see the JavaDoc for the JAAS Configuration class. If there's only one login module in the realm, it should typically be set to Required.
Server-Side	Most login modules should be run on the server side. Unless you know other wise, this should be set to Server Side. However, some modules such as the Kerberos login module have components that must run on the client side, and in that case this should be set to Client Side.
Configuration Options	Each login module takes a number of custom configuration options (for example, a debug option that may be set to true or false). In this box, you can enter any number of configuration options using the standard Java properties file format (one option per line, with the form name=value).

	Tip
	If the security realm has multiple login modules, the Control Flag is particularly important to establish the relationship between the modules, and which modules will be run depending on whether the ones before them succeeded or failed. The order of the login modules is also important, in case the control flag for one of them is set such that success or failure stops the login process.

From here, there are two options:

Show Plan

Show a Geronimo deployment plan for the modified security realm. This can be used to deploy the realm as an application-scoped realm or to save the configuration for later use or automated deployment, etc. See Section 9.2.1.7, “Generate a Plan for an Application Scoped Realm”.

Save

Updates the security realm with the collected configuration information. This returns to the security realm list screen. If there is an error updating the security realm, it will be printed to the server log.

9.2.1.7. Generate a Plan for an Application Scoped Realm

The security realm features in the console can't update an application configuration. However, they can generate a deployment plan that can be used elsewhere to either deploy the pool with the command-line tools, or to include the plan in an application module.

To do this, follow the normal process to create a pool outlined previously. From the advanced settings, test results, custom realm, or edit realm screens, select the command to Show Plan to bring up the plan screen:

Figure 9.11. Console: Security Realm -- Show Plan

This screen shows the deployment plan that was generated based on the selections made on the previous screens. It also provides a command that could be used to deploy the security realm on the command line, as well as providing a simple procedure to add the security realm to an EAR as an application-scoped realm.

The main step to take from this screen is to copy the entire contents of the Deployment Plan text area (using Ctrl-A or a similar shortcut to be sure). The next three sections discuss the different ways to use this plan.

	Tip
	If you plan to deploy more than one pool in the same server using this plan, be sure to change the configId attribute in the top connector element, and the name specified in the connectiondefinition-instance element.

9.2.1.7.1. Deploy via Command-Line Deploy Tool

To deploy via the command-line deploy tool, save the plan to a file on disk. Then that file can be used to deploy the security realm. For example, if the plan was saved as GERONIMO_HOME/security-realm.xml, then a deploy command might look like this:

java -jar GERONIMO_HOME/bin/deployer.jar deploy \
    GERONIMO_HOME/security-realm.xml

9.2.1.7.2. Deploy as Application-scoped Pool

To deploy the security realm as part of an EAR, create or edit the geronimo-application.xml deployment plan for the EAR (for more details on the Geronimo EAR deployment plan, see Chapter 15, Enterprise Applications (EARs) [DRAFT (1.0)]). Add the dependency (if any) and gbean elements to the EAR deployment plan. For example, the plan might look like this:

Example 9.1. EAR Deployment Plan with Application Scoped Security Realm

<?xml version="1.0" encoding="UTF-8"?>
<application
   xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-1.0"
   configId="MyApplication">
  <gbean name="my-security-realm"
class="org.apache.geronimo.security.realm.GenericSecurityRealm">
    <attribute name="realmName">
      my-security-realm
    </attribute>
    <reference name="ServerInfo">
      <gbean-name>geronimo.server:J2EEApplication=null,
J2EEModule=geronimo/j2ee-system/1.0/car,J2EEServer=geronimo,
j2eeType=GBean,name=ServerInfo</gbean-name>
    </reference>
    <reference name="LoginService">
      <gbean-name>geronimo.server:J2EEApplication=null,
J2EEModule=geronimo/j2ee-security/1.0/car,J2EEServer=geronimo,
j2eeType=JaasLoginService,name=JaasLoginService</gbean-name>
    </reference>
    <xml-reference name="LoginModuleConfiguration">
      <log:login-config
xmlns:log="http://geronimo.apache.org/xml/ns/loginconfig-1.0">
        <log:login-module control-flag="REQUIRED"
                          server-side="true"
                          wrap-principals="false">
          <log:login-domain-name>
            my-security-realm
          </log:login-domain-name>
          <log:login-module-class>
            org.apache.geronimo.security.realm.providers.
                                        PropertiesFileLoginModule
          </log:login-module-class>
          <log:option name="usersURI">
            var/security/users.properties
          </log:option>
          <log:option name="groupsURI">
            var/security/groups.properties
          </log:option>
        </log:login-module>
      </log:login-config>
    </xml-reference>
  </gbean>
</applications>

This section describes how to manually configure a security realm. Once you have the configuration information together, you can deploy and activate the new security realm using the process described in Section 9.3, “Deploying a Security Realm”.

A security realm should be a GBean, so it can be deployed like any other custom service. This section describes the basic GBean configuration procedure (though Chapter 18, GBeans: Adding New Services to Geronimo [EMPTY] contains a more thorough description of deploying services in Geronimo). The following sections describe the specific configuration settings for a Geronimo security realm and each of the standard LoginModule implementations.

To deploy a security realm, first you must create a deployment plan for it. Typical deployment information for a security realm looks like this:

<gbean name="some-properties-file-realm"
class="org.apache.geronimo.security.realm.GenericSecurityRealm">
  <attribute name="realmName">
    some-properties-file-realm
  </attribute>
  <reference name="ServerInfo">
    <application>null</application>
    <module>geronimo/j2ee-system/1.0/car</module>
    <name>ServerInfo</name>
  </reference>
  <xml-reference name="LoginModuleConfiguration">
    <login-config
           xmlns="http://geronimo.apache.org/xml/ns/loginconfig">
      <login-module control-flag="REQUIRED"
                       server-side="true">
        <login-domain-name>
          some-properties-file-login
        </login-domain-name>
        <login-module-class>
          org.apache.geronimo.security.realm.providers.
                                       PropertiesFileLoginModule
        </login-module-class>
        <option name="usersURI">
          var/security/some_users.properties
        </option>
        <option name="groupsURI">
          var/security/some_groups.properties
        </option>
      </login-module>
    </login-config>
  </xml-reference>
</gbean>

This GBean definition includes the basic security realm configuration (in other words, the name of the realm), and also includes an embedded block of XML that defines the LoginModules that this security realm will use.

The important elements and attributes in this configuration block are:

The login module configuration looks like this:

Figure 9.12. Security: Login Module List

It basically provides a list of login modules, each of which may be listed in one of two ways:

The reference to an existing login module looks like this:

Figure 9.13. Security: Existing Login Module Configuration

The elements used here are fairly standard for referring to a GBean running elsewhere in the server; the only real difference is the JAAS control flag in addition:

The definition for a new login module looks like this:

Figure 9.14. Security: New Login Module Configuration

The elements introduced here are:

This section describes the options available for each of the standard login modules. These can be set using the option element in the configuration block above (see Figure 9.14, “Security: New Login Module Configuration”).

user1=somepassword
another_user=my_password
this-user=secret

administrators=user1,this-user
normalUsers=another_user

SELECT username, password FROM application_users
 WHERE username=?

SELECT u.name, g.name
FROM user_groups ug, users u, groups g
WHERE u.id=ug.user_id AND g.id=ug.group_id
  AND u.name=?

SELECT user_name, group_name FROM user_groups
 WHERE user_name=?

9.2.3.3. Kerberos Login Module Configuration

A Kerberos realm authenticates users by interacting with the local Kerberos client on a user's PC. Generally speaking, the security realm just identifies the current user's username. When the user then opens network communication with Geronimo, the network infrastructure can use GSSAPI and an exchange of Kerberos tickets to further enforce the user's identity and encrypt the communication. However, that network configuration is outside the purview of the security realm and must be configured separately. TODO: explain somewhere how to turn on GSSAPI networking and give a cross-reference here.

The options for a Kerberos login module are listed below. Geronimo just uses Sun's Kerberos LoginModule under the covers, so it will only work when running in a Sun JVM, and the configuration options are just passed on directly to the Krb5LoginModule.

When configuring the Kerberos login module, the following options are available. They should be configured using attributes of type String or boolean as appropriate:

• clearPass

• debug

• doNotPrompt

• keyTab

• principal

• refreshKrb5Config

• storeKey

• storePass

• ticketCache

• tryFirstPass

• useFirstPass

• useKeyTab

• useTicketCache

These options are documented on Sun's site:

• JDK 1.4 Krb5LoginModule

• JDK 1.5 Krb5LoginModule

	Note
	In the case of an application client, the Kerberos realm needs components to be run on both the client PC and the server. Why? How is that set up?

To deploy a security realm to the server, you need to create a Geronimo deployment plan for the security realm GBean. This is just a thin wrapper around the GBean configuration. You can save this with any file name you like.

<configuration
    xmlns="http://geronimo.apache.org/xml/ns/deployment"
    configId="MySecurityRealm"
    parentId="geronimo/j2ee-server/1.0/car">

<!-- standard realm GBean configuration -->
<gbean name="some-properties-file-realm"
class="org.apache.geronimo.security.realm.GenericSecurityRealm">
  <attribute name="realmName">
    some-properties-file-realm
  </attribute>
  <reference name="ServerInfo">
    <application>null</application>
    <module>geronimo/j2ee-system/1.0/car</module>
    <name>ServerInfo</name>
  </reference>
  <xml-reference name="LoginModuleConfiguration">
    <login-config
           xmlns="http://geronimo.apache.org/xml/ns/loginconfig">
      <login-module control-flag="REQUIRED"
                       server-side="true">
        <login-domain-name>
          some-properties-file-login
        </login-domain-name>
        <login-module-class>
          org.apache.geronimo.security.realm.providers.
                                       PropertiesFileLoginModule
        </login-module-class>
        <option name="usersURI">
          var/security/some_users.properties
        </option>
        <option name="groupsURI">
          var/security/some_groups.properties
        </option>
      </login-module>
    </login-config>
  </xml-reference>
</gbean>

</configuration>

The new elements here are:

java -jar bin/deployer.jar deploy realm-plan.xml

Instead of deploying the security realm as a top-level service, you can deploy it within on application (or module). In this case, you'll add the security realm configuration information to the Geronimo deployment plan for the application (or module). For all the details on the structure of application deployment plans, see Part III, “J2EE Applications on Geronimo”. For example, including a realm in an application would look like this:

<application
    xmlns="http://geronimo.apache.org/xml/ns/j2ee/application"
    configId="MyApplication"
    parentId="geronimo/j2ee-server/1.0/car">

<!-- standard Realm GBean configuration -->
<gbean name="some-properties-file-realm"
class="org.apache.geronimo.security.realm.GenericSecurityRealm">
  <attribute name="realmName">
    some-properties-file-realm
  </attribute>
  <reference name="ServerInfo">
    <application>null</application>
    <module>geronimo/j2ee-system/1.0/car</module>
    <name>ServerInfo</name>
  </reference>
  <xml-reference name="LoginModuleConfiguration">
    <login-config
           xmlns="http://geronimo.apache.org/xml/ns/loginconfig">
      <login-module control-flag="REQUIRED"
                       server-side="true">
        <login-domain-name>
          some-properties-file-login
        </login-domain-name>
        <login-module-class>
          org.apache.geronimo.security.realm.providers.
                                       PropertiesFileLoginModule
        </login-module-class>
        <option name="usersURI">
          var/security/some_users.properties
        </option>
        <option name="groupsURI">
          var/security/some_groups.properties
        </option>
      </login-module>
    </login-config>
  </xml-reference>
</gbean>

</application>

Note that the parentId for the application should be geronimo/j2ee-server/1.0/car (or it should at least be one of the ultimate parents in the hierarchy), since that's where the security realm classes and interfaces live.

There are generally three ways for an application user to authenticate:

Selecting a realm for the first two (application client) scenarios is addressed in Chapter 14, Client Applications (Client JARs) [IN PROGRESS]. Selecting a realm for a web application is addressed in Section 11.4, “Web Application Login”.

Each J2EE application module declares the application roles it uses in its J2EE deployment descriptor (such as web.xml for web modules). To map these to principals provided by the security realm, you'll add settings to the Geronimo deployment plan for the module. For each application role, you'll list the principals that should be members of that role. The same settings are used in the deployment plan for each module type. An example is given in Example 9.7, “Role Mapping” and the full details are provided in Section 11.3.5, “Security Settings”, Section 12.3.8, “Security Settings”, and Chapter 14, Client Applications (Client JARs) [IN PROGRESS].

Note

The principal entries in the Geronimo deployment plan are normally identified by their principal class and principal name. Both values must match in order for the principal to successfully qualify for the application role. However, if the Support Advanced Mapping flag is enabled for the login modules in the realm, principals are also identified by their login domain name and realm name, and the security mapping process can distinguish based on those characteristics of the principal as well.

<web-app ...>
  <security-role>
    <role-name>NormalUser</role-name>
  </security-role>
</web-app>

<web-app ...>
  <security
         xmlns="http://geronimo.apache.org/xml/ns/security-1.1">
    <role-mapping>
      <role name="NormalUser">
        <principal class="com.ldap.User" name="Aaron" />
        <principal class="com.ldap.Group" name="Developers" />
        <principal class="com.tribal.Clan" name="Developers" />
        <principal class="com.tribal.Chief" name="Erin" />
      </role>
    </role-mapping>
  </security>
</web-app>

<web-app ...>
  <security
         xmlns="http://geronimo.apache.org/xml/ns/security-1.1">
    <role-mapping>
      <role name="NormalUser">
        <login-domain-principal domain-name="LDAPdomain" 
               class="com.ldap.User" name="Aaron" />
        <login-domain-principal domain-name="LDAPdomain"
               class="com.ldap.Group" name="Developers" />
        <login-domain-principal domain-name="TRIBALdomain"
               class="com.tribal.Clan" name="Developers" />
        <login-domain-principal domain-name="TRIBALdomain"
               class="com.tribal.Chief" name="Erin" />
      </role>
    </role-mapping>
  </security>
</web-app>

<web-app ...>
  <security
         xmlns="http://geronimo.apache.org/xml/ns/security-1.1">
    <role-mapping>
      <role name="NormalUser">
        <realm-principal
               realm-name="LDAP" domain-name="LDAPdomain" 
               class="com.ldap.User" name="Aaron" />
        <realm-principal
               realm-name="LDAP" domain-name="LDAPdomain"
               class="com.ldap.Group" name="Developers" />
        <realm-principal
               realm-name="Tribal" domain-name="TRIBALdomain"
               class="com.tribal.Clan" name="Developers" />
        <realm-principal
               realm-name="Tribal" domain-name="TRIBALdomain"
               class="com.tribal.Chief" name="Erin" />
      </role>
    </role-mapping>
  </security>
</web-app>

Tip

Normally an application could only possibly see principals from a single Realm. For example, if a web application authenticates against the LDAP realm, there's no way that principals could be generated for the Tribal realm. It may be the case that application clients contacting EJBs login using one realm and a web application contacting the same EJBs uses a different login realm (so the EJBs might have security mappings for both realms), but this would be quite unusual.

A custom login module needs to implement javax.security.auth.spi.LoginModule. The login module has two main responsibilities:

To make it that far, the LoginModule must define the principal classes it intends to use. For example, a login module that provides principals for the username and the user's home state might declare principals like this:

public class UserPrincipal implements Principal, Serializable {
    private String name;

    public UserPrincipal(String name) {
        this.name = name;
    }

    public String getName() {
        return name;
    }

    public String toString() {
        return name;
    }

    public boolean equals(Object o) {
        return o instanceof UserPrincipal &&
               ((UserPrincipal)o).name.equals(name);
    }

    public boolean hashCode() {
        return name.hashCode();
    }
}

public class StatePrincipal implements Principal, Serializable {
    private String state;

    public StatePrincipal(String state) {
        state = state;
    }

    public String getName() {
        return state;
    }

    public String toString() {
        return state;
    }

    public boolean equals(Object o) {
        return o instanceof StatePrincipal &&
               ((StatePrincipal)o).state(state);
    }

    public boolean hashCode() {
        return state();
    }
}

Then the LoginModule that uses those Principal classes might look like this:

public class MyLoginModule implements LoginModule {
    private Subject subject;
    private CallbackHandler handler;
    private String user;

    public void initialize(Subject subject,
                           CallbackHandler handler,
                           Map sharedState, Map options) {
        this.subject = subject;
        this.handler = handler;
        // Any options passed in the ConfigurationEntry GBean
        // will end up in the options Map here, and can be
        // saved to be used in the other methods
    }

    public boolean login() throws LoginException {
        NameCallback name = new NameCallback("User name");
        PasswordCallback pwc = new PasswordCallback("Password",
                                                    false);
        handler.handle(new Callback[]{name, pwc});
        user = name.getName();
        String pw = new String(pwc.getPassword());
        // validate the account
    }

    public boolean commit() throws LoginException {
        subject.add(new UserPrincipal(user));
        String state = ...;
        subject.add(new StatePrincipal(state));
        return true;
    }

    ...
}

To package a custom login module, you should package the login module and principals into a JAR, and add it to the Geronimo repository (in a file such as geronimo/repository/login/jars/my-login-module-1.0.jar). Then you can configure the custom login module in the normal way -- just add a login modules configuration entry with the login-module-class set to the new class (see Figure 9.14, “Security: New Login Module Configuration”).

Both the top-level deployment procedure described in Section 9.3.1, “Server-Wide Security Realms” and the application-level deployment procedure described in Section 9.3.2, “Application-Scoped Security Realms” support the dependency element, which is used to include the custom login module JAR on the ClassPath for the configuration:

<dependency>
  <uri>login/jars/my-login-module-1.0.jar</uri>
</dependency>

<!-- Normal security realm declaration here -->
<gbean ...

In order to enable HTTPS, Geronimo requires a keystore. There are two restrictions on the keystore:

Generally, this means that the keystore should contain only Geronimo server information.

There are three possible approaches to server certificates:

The last two cases are identical so far as the keystore is concerned, so the following sections will cover preparing a self-signed test certificate, preparing a certificate signed by a certificate authority, and importing CA certificates.

	Note
	The procedures described here use the keytool tool included with the JDK.

keytool -genkey -alias geronimokey -keyalg RSA -validity 365 \
        -keystore ssl-keystore

keytool -genkey -alias geronimokey -keyalg RSA -validity 365 \
        -keystore ssl-keystore

keytool -certreq -alias geronimokey -file geronimo.csr \
        -keystore ssl-keystore

keytool -import -trustcacerts -file ca-cert.pem -alias MyCA \
        -keystore ssl-keystore

keytool -import -file geronimo.pem -alias geronimokey \
        -keystore teststore