Geronimo provides all the capabilities required by the J2EE 1.4 specification. In particular:

Geronimo is a product of the Apache Software Foundation. As an open source product, Geronimo is developed, enhanced, and maintained by a group of Apache developers, and made available to others under the terms of the Apache Software License. Most Geronimo business is conducted in open forums, including mailing lists and an IRC channel for user and developer discussions, a public issue tracker for bugs and new features, and a Wiki for (among other things) recording tips and tricks for new users.

While the open source development process can be an advantage for some users -- you never need to wonder who's assigned to a bug, what progress is being made, and whether a fix will be made available to you -- it can be a disadvantage if you're looking for a more rigorous level of support. For that reason, outside vendors offer support contracts for Geronimo with the full support of the Geronimo development team.

Another aspect of the Apache license is that Geronimo may be included in commercial products, such as higher-level servers, development tools requiring a working application server for testing, and more. In such cases the product vendor would typically provide support, though again, the Geronimo team encourages embedded use of this nature.

Many people have asked, "why does the world need another application server?" After all there are numerous application servers already, many very capable products, several relatively inexpensive products, and even two other application servers that are J2EE certified -- JOnAS and JBoss.

There are two key answers to this question. One answer is, Geronimo has been built to be modular and configurable to a greater degree than other available application servers. A key aim of Geronimo is to support custom "builds" or distributions of the server, tightly customized to the needs of a specific application or deployment scenario. The core J2EE application server is created by assembling a group from over 40 distinct configuration modules. But for applications with different needs, servers can be assembled from a smaller group of components, or including additional third-party components. This area will continue to be a focus for future versions of Geronimo, expanding to handle extracting customized components from a modified server and distributing them to other Geronimo servers in the environment.

A second answer to this question is the Apache license. As an open source product, Geronimo is clearly in the same playing field as JBoss and JOnAS. However, both of those projects use the Lesser General Public License, or LGPL. While the exact effect of the LGPL as it applies to Java is subject to interpretation, one thing is clear. Changes to the core product, or products derived from the core product, must also be released as open source under the terms of the LGPL. The common interpretation of the LGPL is that a J2EE application can safely run on JBoss or JOnAS without being considered a derived work. But many development tools and server products could benefit from building on a certified application server, and those often require enough custom interaction with the application server that they may well be considered derived works. It's no surprise that most products like portal servers and integration servers are built on top of proprietary application servers.

In the future, just like some vendors have built proprietary servers which tightly integrate the Apache web server or the Tomcat web container, the Apache license will allow proprietary products to be built using Geronimo as a fundamental building block. The next natural question is, "why would you want some big company to profit from your hard work?" There are many answers to this too, but a key point is that many companies who use and profit from open source servers contribute back to the open source projects. In fact, the first commercial product based on Geronimo has already been released, and the company behind it supports several developers working on the Geronimo project. In other words, each product built on Geronimo looks like a success story, not a hurdle.

License aside, Geronimo is intended to scale in a way few open source products have really explored. Many open source projects are very accessible to developers, but fall short when it comes to high-end production configurations. Clustering support tends to be limited in scalability, and most open source products are very limited when it comes to management and deployment in 24/7 configurations. Integration packages for standard third-party systems such as accounting and ERP systems are typically targeted strictly at proprietary application servers. All of these hurdles need to be overcome, without losing the core ease-of-development features that attracted a following in the first place.

Geronimo will ultimately address these issues, supporting ISPs, high-load Internet-facing web applications, and other applications ranging from small to very, very large. Of course, talk is cheap, and the 1.0 release of Geronimo doesn't include all the features on this list. Still, the Geronimo team members have developed and supported applications in these mission-critical environments, and this goal has been and will continue to be an important one in the ongoing development of Geronimo.

Back to the original question, yet another motivation behind the founding of Geronimo is the Apache community. While some other projects are controlled by a single company or a small number of individuals, Apache projects are based on the principles of collaborative development, and Geronimo will never be subject to anyone's fiat. The key developers span numerous companies and continents, and all decisions are voted on and made in public forums, with the input of the community. You're welcome to join!

Geronimo was started in the summer of 2003, by a new community formed by current and past contributors to projects like JBoss, OpenEJB, Jetty, Castor, and more. It originally started in the Apache Incubator, a home for projects that might one day become full Apache projects.

In late 2003, the Apache Software Foundation became the first open source licensee of the J2EE TCK for certification purposes. Geronimo is one of the Apache projects interested in TCK access. TCK testing of Geronimo began in 2004.

In May of 2004, the Geronimo project exited the Incubator and became a top-level Apache project.

In June 2005, the automated TCK test suite was passed in full for the first time.

After 5 milestone releases, Geronimo 1.0 is expected to be released in December 2005. The initial release is J2EE certified and feature-complete as far as core J2EE features go. Some ease of use features are still under active development, including the management console and IDE integration, and others are on the horizon including EJB3 support, but we're proud of our first full release and plan to continue to work hard to improve it.

Geronimo consists of a set of core features and services as well as a number of critical services provided by other open source products. This is a list of many of those related projects.

Geronimo releases are available from the Geronimo web site:

http://geronimo.apache.org/downloads.html

There are three types of downloads available for each release:

The binary release is offered as two distinct configurations, and the same options are available through the installer. The option is related to the web container used by Geronimo

The Geronimo team fully supports both web containers, and does not have a preference for one or the other. We have people working hard to ensure that both are well-integrated into Geronimo. For straight J2EE applications, either container will work well. Some more advanced configurations do expose differences between the two web containers -- one area of note being how they handle virtual hosting. And some developers may have an existing preference. In any case, Geronimo uses a standard web deployment plan for both containers, and minimizes any differences visible to applications and developers.

	Note
	To further clarify on Virtual Hosts, Tomcat configures each host separately with listen addresses, etc. and then can assign web applications to hosts in the deployment plan for an application. Jetty simple allows the developer to specify a list of virtual hosts in the deployment plan for an application.

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

This section gives a fast-paced walkthrough of a simple installation and customization process for Geronimo. Each of the steps here is covered in more detail in subsequent chapters.

2.2.1. Download & Install

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

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

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

2.2.4. Log in to Management Console

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.

2.2.5. Create a Database Pool

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:

1. Select DB Manager in the navigation bar on the left.

2. Enter TestDatabase in the Create DB field, and click the Create button.

3. Make sure TestDatabase is listed in the Database List at the top of the screen.

To create a new database pool:

1. Select Database Pools in the navigation bar on the left.

2. Select the create pool Using the Geronimo database pool wizard link shown in Figure 2.5, “Quick Start: Database Pools”.

3. Enter TestPool in the Name of Database Pool field, and select the database product from the Database Type drop-down (select Derby Embedded if you don't have a database of your own to connect to). Click the Next button to continue.

4. Select the Driver JAR for your database. The drop-down shows encoded names for third-party JARs located in the repository/ directory of the Geronimo installation. For Derby, select org.apache.derby/derbyclient/10.1.1.0/jar as the driver JAR. (If the server has Internet access and is not behind an HTML proxy server, you can use the Download a Driver button to automatically download many open source database drivers.)

5. Enter other connection parameters to connect to the database. Many databases require a server name, database name, username, and password. (The embedded Derby driver does not require the server name, as it's always running in the same VM as the application server. You can also leave the username and password blank, though you should set the database name to, for example, TestDatabase.) Click the Next button to continue.

6. On the next page, review the JDBC Connect URL that was generated, and if it looks okay, click Test Connection to try to connect to the database. If there are any problems, use the Edit Settings button to correct them, or else use the Deploy button to deploy the 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).

2.2.6. Create a Security Realm

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:

1. Select Security Realms from the navigation area on the left side.

2. Click the link to Add new security realm.

3. Enter TestRealm for the Name of Security Realm and select Database (SQL) Realm as the Realm Type. Click Next to continue.

4. Set the User SELECT SQL to select username, password from TEST_USER where username=? and set the Group SELECT SQL to select username, group_name from TEST_USER_GROUPS where username=?

5. Select TestPool (or whatever you called the database pool above) as the Database Pool and click Next to continue (the other settings on this page are only used if no database pool is specified).

6. Click Test a Login to make sure the realm is configured correctly.

7. If you used the script above, enter jdoe as the Username and secret as the Password and click Next to test the login.

8. If you used the script above and the jdoe login, the next screen should show that 3 principals were generated, one GeronimoUserPrincipal with name jdoe, one GeronimoGroupPrincipal with name Employees, and one GeronimoGroupPrincipal with name Administrators.

9. Click Deploy Realm to deploy the new security realm.

2.2.7. Deploy Web Applications

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:

• Sets the web application to appear at a URL starting with /test-web

• Sets the security system to run any logins against the TestRealm security realm.

• Sets the default principal to a user named "anonymous" for pages where security is not required but the page still calls HttpServletRequest.getUserPrincipal.

• Maps all users in the "Administrators" group in the security realm to the "content-administrators" J2EE role (which is declared in the web.xml for the LDAP Demo realm).

	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.

Geronimo is a pure-Java product, and should therefore run on any platform with the appropriate Java Virtual Machine.

As Geronimo implements J2EE 1.4, and J2EE 1.4 requires J2SE 1.4, Geronimo will run under Java 1.4 or higher. However, the CORBA features currently used by Geronimo require a Sun 1.4.x JVM. That means the best option for Geronimo is currently the Sun 1.4.2 JVM. Broader compatibility with other JVM vendors and versions is a goal for future releases.

As far as operating systems go, Geronimo has been successfully run on:

Geronimo requires a Java compiler in order to handle JSP compilation. That means that in most cases a full Java Development Kit is required, though in special circumstances (with pre-compiled JSPs, no JSPs at all, or a third-party compiler) it can be run on a Java Runtime Environment instead. The next milestone release should eliminate this requirement by switching to a bundled compiler.

Tip

Geronimo itself can run on a headless machine (that is, a server with no windowing system or GUI available, such as some UNIX machines). In many cases, even applications dealing with printing and graphics can be run by starting Geronimo with the -Djava.awt.headless=true option. However, certain rare applications may require a working X-Windows environment to run (or at least a simulated environment such as can be provided by xvfb).

The most expedient way to install a milestone release of Geronimo is to download and unpack the .zip or .tar.gz file for that milestone. No additional steps are necessary, and you will get a default, working configuration out of the box. However, with this approach, you aren't able to change any of the default configuration parameters (such as network ports).

To run the custom installation procedure, you'll need to download the installer package, which is an executable JAR. To start the install, run a command like this (using Java 1.4 or higher):

java -jar geronimo-1.0-M4-installer.jar

You should see the first screen of the installer:

Figure 3.1. Geronimo Installer: Welcome

Clicking Next brings up the license screen:

Figure 3.2. Geronimo Installer: License

To proceed, select the I accept radio button and click Next to bring up the install path screen:

Figure 3.3. Geronimo Installer: Install Path

Select a path (by typing one in the box or selecting an existing directory with the Browse... button) and click Next to proceed. If the selected directory doesn't exist, you'll get one prompt:

Figure 3.4. Geronimo Installer: Create New Directory

Whereas if the directory does exist, you'll get a different prompt:

Figure 3.5. Geronimo Installer: Overwrite Existing Directory

Generally speaking, it's best not to install the M4 release of Geronimo over top of a previous release. It's best to uninstall any previous release if desired, then install Geronimo M4 into a new directory.

After the directory select, the feature selection screen comes up:

Figure 3.6. Geronimo Installer: Feature Selection

There's generally no reason not to select all the features, since they add little space on top of the basic installation and even when installed they won't run unless manually started. The JMX Debug Tool is particularly useful as it's a simple web application you can start and browse to make sure the web container is up and running on the expected port.

Once the feature selection is complete, click Next to continue to the main configuration screen:

Figure 3.7. Geronimo Installer: Main Configuration

The default values are shown in Figure 3.7, “Geronimo Installer: Main Configuration”. The available fields are:

Once the basic options are finished, click Next to proceed to the EJB/IIOP configuration screen:

Figure 3.8. Geronimo Installer: EJB/IIOP Configuration

The default values are shown in Figure 3.8, “Geronimo Installer: EJB/IIOP Configuration”. The available fields are:

Once the EJB/IIOP options are finished, click Next to proceed to the service configuration screen:

Figure 3.9. Geronimo Installer: Service Configuration

The default values are shown in Figure 3.9, “Geronimo Installer: Service Configuration”. The available fields are:

Once the service configuration options are set, click Next to proceed to the installation screen:

Figure 3.10. Geronimo Installer: Unpack Files

This screen unpacks all the raw Geronimo installation files. It doesn't quite result in a working installation, so when it finishes, click Next to continue to the customization screen: