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

In addition to the J2EE features listed above, Geronimo supports a number of extensions to the J2EE specification, both internally and via Geronimo Plugins. These include:

In addition, many other products can be integrated with Geronimo or run on Geronimo, even if they are not yet released as Geronimo Plugins. For example, products such as the Mule and ServiceMix ESBs currently work with Geronimo, with plugin releases planned.

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, multiple 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 several key answers to this question.

One important answer is that there's still room left for innovation in the Application Server market. Many current application server providers have stopped enhancing their core application servers, focusing instead on other products such as portals and integration platforms. The Geronimo team believes that the application server space is not dead, and there is plenty of room left for innovation. We'd rather build a newer and better application server, and integrate with other projects that provide features like portals and ESBs.

As a specific example of this principle, 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. The Geronimo Plugin system allows new features to be downloaded and installed or updated at runtime, and it can also be used to copy applications or services from one Geronimo server to another (to get a new developer's environment up immediately, to migrate an application from test to production, or to clone features across a farm of servers).

Another 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 commercial 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.1 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.

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 was released in January 2006. 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.

In June 2006, Geronimo 1.1 was released, including the Geronimo Plugin system, administration console enhancements, and many other fixes and improvements.

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 releases are offered with two distinct configurations. Each configuration uses a different web container in Geronimo. The available web containers are:

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.1/ 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-jetty-j2ee-1.1.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 (1.1)] for more details).

Figure 2.1. Quick Start: Install Directory

geronimo-1.1> java -jar bin/server.jar
Booting Geronimo Kernel (in Java 1.5.0_07)...
Starting Geronimo Application Server v1.1
[************************] 100%  25s Startup complete
  Listening on Ports:
    1099 0.0.0.0 RMI Naming
    1527 0.0.0.0 Derby Connector
    4201 0.0.0.0 ActiveIO Connector EJB
    4242 0.0.0.0 Remote Login Listener
    8009 0.0.0.0 Jetty Connector AJP13
    8080 0.0.0.0 Jetty Connector HTTP
    8443 0.0.0.0 Jetty Connector HTTPS
    9999 0.0.0.0 JMX Remoting Connector
   61616 0.0.0.0 ActiveMQ Message Broker Connector

  Started Application Modules:
    EAR: geronimo/webconsole-jetty/1.1/car
    RAR: geronimo/activemq/1.1/car
    RAR: geronimo/system-database/1.1/car
    WAR: geronimo/remote-deploy-jetty/1.1/car
    WAR: geronimo/welcome-jetty/1.1/car

  Web Applications:
    http://remus:8080/
    http://remus:8080/console
    http://remus:8080/console-standard
    http://remus:8080/remote-deploy

Geronimo Application Server started

...
  <module name="geronimo/jetty/1.1/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)] 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.1)] 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/derby/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.

	Tip
	Instead of creating the database in advance using the DB Manager, you can add ;create=true to the end of the JDBC URL that the console generates, and then the database will be created automatically when the connection pool is deployed.

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)]). 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://people.apache.org/repository/geronimo/wars/geronimo-welcome-1.1-SNAPSHOT.war and http://people.apache.org/repository/geronimo/wars/geronimo-ldap-demo-1.1-SNAPSHOT.war.

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

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

To make sure this is running, try connecting to http://localhost:8080/geronimo-welcome-1.1-SNAPSHOT/. This is a very small web application, 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.1)] 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.1">
    <environment>
        <moduleId>
            <artifactId>TestWebApplication</artifactId>
        </moduleId>
    </environment>
    <context-root>/test-web</context-root>
    <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.1-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, J2EE includes certain CORBA requirements, and the CORBA features currently used by Geronimo require a Sun 1.4.x JVM. That means the only J2EE Certified platform for Geronimo is currently the Sun 1.4.2 JVM. Broader certification across other JVM vendors and versions is a goal for future releases.

	Tip
	Geronimo runs well on Java 5, so long as CORBA features are left disabled. If your applications require CORBA support, you'll need to use a Sun J2SE 1.4.2_* JVM.

As far as operating systems go, Geronimo has been successfully run on many Windows, Mac, Linux, and UNIX platforms, including:

Geronimo includes a bundled JSP compiler, which means it can actually run under the Java Runtime Environment (JRE), and does not require a Java Development Kit (JDK).

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. No additional steps are necessary, and you will get a default, working configuration out of the box.

3.2.1. Windows Installation

On Windows platforms, use a tool like WinZip to open the .zip file and extract the Geronimo files. This will create a new geronimo-1.1/ subdirectory containing all the Geronimo files.

Warning

Geronimo includes files with long paths and names, and Windows limits all files to a total path length of 255 characters. This means it's safest to install Geronimo into a directory with a very short path name. For example, it would be best to use a path like C:\geronimo-1.1 instead of a longer path (like C:\Program Files\Application Servers\Geronimo 1.1). If there are errors while unzipping the Geronimo distribution, try installing it to a directory with a shorter path name.

> tar -xzvf geronimo-jetty-j2ee-1.1.tar.gz

geronimo-1.1/
geronimo-1.1/bin/
geronimo-1.1/docs/
geronimo-1.1/lib/
...

All of the installation methods create the same final directory layout. The resulting Geronimo directory will look something like this:

The text files are informational only, and can be freely moved or removed. The directories are the interesting part:

None of these directories should be moved or altered. Only a limited number of files in them should even be edited (one example of an editable file is the properties file that configures users and password for the default security realm).

Once Geronimo has been installed, it must be started fr