Apache Geronimo Development and Deployment

Aaron Mulder

Apache


          
        

Chariot Solutions


          
        

Abstract

This book is an introduction to installing and configuring the Apache Geronimo application server, and then configuring and deploying applications to Geronimo. It is aimed at developers with prior J2EE experience, and basic knowledge of at least one other application server product. While some of the advanced topics cover specialized deployment scenarios, in general, this book is not aimed at system administrators.


Table of Contents

Preface [MINIMAL]
1. Drafts and Milestone Releases
2. A Note On Formatting
3. Acknowledgements
I. Getting Started
1. About Apache Geronimo [DRAFT (1.0)]
1.1. Apache Geronimo Features
1.1.1. Application Modules
1.1.2. Server Resources
1.1.3. Server Management & Deployment
1.1.4. Additional APIs
1.2. Vendor and License
1.3. Why Another Application Server?
1.4. A Brief History of Geronimo
1.5. Related Projects
1.5.1. Top-Level Services
1.5.2. Selected APIs and Tools
2. Acquiring Geronimo & Quick Start [DRAFT (1.0)]
2.1. Downloading Geronimo
2.1.1. Source Code Access
2.2. Geronimo Quick Start
2.2.1. Download & Install
2.2.2. Start the Server
2.2.3. Customize Network Ports (if necessary)
2.2.4. Log in to Management Console
2.2.5. Create a Database Pool
2.2.6. Create a Security Realm
2.2.7. Deploy Web Applications
2.2.8. Quick Start Summary
3. Installing Geronimo [DRAFT (M4)]
3.1. Platforms & Prerequisites
3.2. Quick Start Installation Procedure
3.3. Custom Installation Procedure
3.4. Automated Installation Procedure
3.5. Installation Results
3.6. Starting the Server
3.6.1. Startup Options
3.6.2. Troubleshooting Startup Problems
3.7. Stopping the Server
3.8. Running Geronimo as a Windows or UNIX Service
4. Elements of Geronimo [DRAFT (1.0-pre)]
4.1. Geronimo Architecture
4.1.1. Geronimo Managed Components: GBeans
4.1.2. Communication Between GBeans
4.2. Server Startup and Configurations
4.2.1. Configuration Dependencies
4.2.2. Adding New Applications & Configurations
4.2.3. Server Startup Options
4.3. Introduction to Deployment
4.3.1. XML Schema and Geronimo Deployment Plans
4.3.2. Deploying J2EE Application Modules
4.3.3. Deploying JDBC and JMS Resources
4.3.4. Deploying GBeans
4.4. ClassLoaders in Geronimo
II. Configuring Geronimo
5. Core Configuration [EMPTY]
5.1. Network Configuration
5.2. Logging Configuration
5.3. Transaction Configuration
6. Database Configuration [DRAFT (1.0-pre)]
6.1. JDBC Drivers
6.1.1. Automatic JDBC Driver Installation
6.2. Database Pools as Connectors and the TranQL RAR
6.3. Easy Configuration and Deployment using the Console
6.3.1. Create a new JDBC Pool
6.3.2. Create a new XA Database Pool
6.3.3. Import a Pool from Another Application Server
6.3.4. Generate a Plan for an Application or Client Scoped Pool
6.3.5. Edit an Existing Pool
6.4. Manual Configuration and Deployment
6.4.1. Configuring a Database Pool
6.4.2. Deploying a Database Pool
6.5. Using a Database Pool
6.5.1. Updating the Module's Deployment Information
6.5.2. Application Code
6.6. Reconfiguring a Previously Deployed Pool
7. JMS Configuration [DRAFT (1.0)]
7.1. JMS Resource Groups, Connectors, and the ActiveMQ RAR
7.2. Easy Configuration and Deployment Using the Console
7.2.1. JMS Resource Group List
7.2.2. Creating a new JMS Resource Group
7.2.3. Generate a Plan for an Application or Client Scoped Resource Group
7.3. Manual Configuration and Deployment
7.3.1. JMS Resource Group Configuration
7.3.2. JMS Resource Deployment
7.4. JMS Applications
7.4.1. Updating the Module's Deployment Information
7.4.2. Application Code
7.5. Message Broker Configuration and Deployment
7.5.1. Quick Start
7.5.2. Message Broker GBean Configuration
7.5.3. Message Broker GBean Deployment
8. Additional Services [EMPTY]
8.1. J2EE Connectors
8.2. Java Mail Resources
9. Security Configuration [DRAFT (1.0-pre)]
9.1. Geronimo Security Concepts
9.1.1. Login: Authentication and Principals
9.1.2. Security Realms
9.1.3. JAAS Login Modules
9.1.4. JAAS Configuration Entries
9.1.5. Authorization
9.1.6. One Login, Multiple Destinations
9.2. Security Realm Configuration
9.2.1. Easy Configuration and Deployment using the Console
9.2.2. Manual Security Realm Configuration
9.2.3. Configuration Options for Standard Login Modules
9.3. Deploying a Security Realm
9.3.1. Server-Wide Security Realms
9.3.2. Application-Scoped Security Realms
9.4. Enabling Security for Applications
9.4.1. Selecting the Realm to Authenticate Against
9.4.2. Mapping Roles to Principals
9.5. Using a Custom Login Module
9.5.1. Implementing a Custom LoginModule
9.5.2. Packaging and Deploying a Custom LoginModule
9.6. Configuring SSL/HTTPS
9.6.1. Keystore Configuration
9.6.2. HTTPS Connector Configuration
9.6.3. HTTPS Connector Deployment
III. J2EE Applications on Geronimo
10. Development & Deployment Overview [DRAFT (1.0)]
10.1. Component Development
10.2. J2EE Deployment Descriptors
10.3. Geronimo Deployment Plans
10.3.1. Necessity of Deployment Plans
10.3.2. Deployment Plan File Names & Packaging
10.4. The Deploy Tool
10.4.1. Deploy Tool Capabilities
10.4.2. Deploy Tool Concepts
10.4.3. Deploy Tool Syntax
10.4.4. Remote Deployment
10.4.5. Deploy Tool Troubleshooting
10.5. Maven 1.x Deployment Plugin
10.5.1. Deployment Plugin Commands
10.5.2. Deployment Plugin Example
10.6. JSR-88 Configuration & Deployment Tools
10.6.1. Connecting a Tool to Geronimo
11. Web Applications (WARs) [DRAFT (1.0)]
11.1. Creating a Web Application WAR
11.1.1. web.xml Format
11.2. The Web App Geronimo Deployment Plan
11.3. Structure of the Deployment Plan
11.3.1. Customizing the Web Application Class Path
11.3.2. Basic Web Application Settings
11.3.3. Web Container-specific Configuration
11.3.4. Resolving References
11.3.5. Security Settings
11.3.6. Adding Module-Scoped Services
11.4. Web Application Login
11.5. Forcing Web Application Deployment to Tomcat or Jetty
12. Enterprise Java Beans (EJB JARs) [DRAFT (1.0)]
12.1. Creating an EJB JAR
12.1.1. ejb-jar.xml Format
12.2. The Geronimo EJB Deployment Plan
12.2.1. Typical Contents of the Geronimo EJB Deployment Plan
12.3. Structure of the Deployment Plan
12.3.1. Customizing the Class Path
12.3.2. Common Settings For All CMP Entity Beans
12.3.3. Session Beans
12.3.4. Entity Beans
12.3.5. Message-Driven Beans
12.3.6. Resolving References from EJBs
12.3.7. Resolving Container-Managed Relationships
12.3.8. Security Settings
12.3.9. Module-Scoped Services
13. J2EE Connectors (RARs) [DRAFT (1.0)]
13.1. Creating a J2EE Connector RAR
13.1.1. ra.xml Format
13.2. The Resource Adapter Geronimo Deployment Plan
13.3. Structure of the Deployment Plan
13.3.1. Customizing the Resource Adapter Class Path
13.3.2. Resource Adapter Configuration
13.3.3. Admin Object Configuration
13.3.4. Adding Module-Scoped Services
13.4. Sample Resource Adapter Configurations
14. Client Applications (Client JARs) [IN PROGRESS]
14.1. Client Styles
14.2. J2EE Application Clients
14.2.1. Creating a J2EE Client JAR
14.2.2. Running a J2EE Application Client
14.2.3. The Client Geronimo Deployment Plan
14.2.4. Structure of the Deployment Plan
14.3. J2SE Application Clients
14.4. Client Authentication
15. Enterprise Applications (EARs) [DRAFT (1.0)]
15.1. Creating an Enterprise Application EAR
15.1.1. application.xml Format
15.2. The Enterprise Application Geronimo Deployment Plan
15.3. Structure of the Deployment Plan
15.3.1. Customizing the Application Class Path
15.3.2. Configuring Application Modules
15.3.3. Application-Wide Security Mapping
15.3.4. Adding Application-Scoped Services
16. Web Services [DRAFT(1.0)]
16.1. J2EE Web Services Concepts & Features
16.1.1. Client, WSDL, and Server
16.1.2. WSDL Styles: Literal, Encoded, RPC, Document, and Wrapped
16.1.3. Services and Ports
16.1.4. Namespaces
16.1.5. The JAX-RPC Mapping File
16.2. A Sample Web Service
16.2.1. The Service Endpoint Interface
16.2.2. The WSDL
16.2.3. The Client Service Interface
16.2.4. The JAX-RPC Mapping File
16.3. Serving Web Services from Geronimo
16.3.1. The webservices.xml Configuration File
16.3.2. Servlet-based Web Services
16.3.3. Session Bean based Web Services
16.4. Web Services Clients in Geronimo
16.4.1. Adding a Web Service Reference to a J2EE Component
16.4.2. Customizing the Service Reference
16.4.3. Authenticating to a Web Service
16.4.4. Packaging and Deployment
16.4.5. Accessing the Service
17. CORBA in Geronimo [DRAFT (1.0)]
17.1. CORBA in Geronimo
17.1.1. Key CORBA Concepts
17.1.2. Geronimo CORBA Services and Configuration
17.2. Exposing EJBs via CORBA
17.2.1. Configuring a TSS
17.2.2. Configuring an EJB for CORBA
17.3. Referencing CORBA EJBs
17.3.1. Configuring a CSS
17.3.2. Configuring an EJB Reference for CORBA
IV. Advanced Geronimo
18. GBeans: Adding New Services to Geronimo [EMPTY]
18.1. Introduction to GBeans
18.2. Developing GBeans
18.3. Configuring GBeans
18.4. Deploying GBeans
19. Overview of Core Geronimo Services [EMPTY]
19.1. The Configuration Store
19.2. The Persistent Configuration List
19.3. The Repository
19.4. The RMI Registry
19.5. JAAS Login Configuration
19.6. Thread Pool
19.7. Work Manager
19.8. Transactions
19.9. Web Container
19.10. EJB Container
19.11. EJB Remote Access
19.12. J2EE Management
19.13. JMX Remote Management
19.14. Application/Service Deployment
20. Management & Monitoring [EMPTY]
20.1. JSR-77 J2EE Management Features
20.2. The Geronimo Management API
20.3. JMX and JMX Management Tools
V. Appendices
A. XML Schemas for Deployment Descriptors & Configuration Files [EMPTY]
B. Apache Software License [DRAFT]

List of Figures

2.1. Quick Start: Install Directory
2.2. Quick Start: Startup Output
2.3. Quick Start: Editing Ports in config.xml
2.4. Quick Start: Console Login
2.5. Quick Start: Database Pools
3.1. Geronimo Installer: Welcome
3.2. Geronimo Installer: License
3.3. Geronimo Installer: Install Path
3.4. Geronimo Installer: Create New Directory
3.5. Geronimo Installer: Overwrite Existing Directory
3.6. Geronimo Installer: Feature Selection
3.7. Geronimo Installer: Main Configuration
3.8. Geronimo Installer: EJB/IIOP Configuration
3.9. Geronimo Installer: Service Configuration
3.10. Geronimo Installer: Unpack Files
3.11. Geronimo Installer: Customize Installation
3.12. Geronimo Installer: Release Notes
3.13. Geronimo Installer: Install Summary
4.1. Components in a Geronimo Runtime
4.2. Communication Between GBeans
4.3. EAR ClassLoader Hierarchy
6.1. Console: Login
6.2. Console: List Database Pools
6.3. Console: Database Pool -- Basic Settings
6.4. Console: Database Pool -- Connection Properties
6.5. Console: Database Pool -- Driver Error
6.6. Console: Database Pool -- Pool Settings
6.7. Console: Database Pool -- Test Successful
6.8. Console: Database Pool -- Test Failed
6.9. Console: Database Pool -- Detailed Edit
6.10. Console: Database Pool List View
6.11. Console: Database Pool -- Select XA Database
6.12. Console: Database Pool -- New XA Database Pool
6.13. Console: Database Pool -- Start Import
6.14. Console: Database Pool -- JBoss Import
6.15. Console: Database Pool -- WebLogic Import
6.16. Console: Database Pool -- Import Status
6.17. Console: Database Pool -- Show Plan
6.18. Console: Database Pool List View
6.19. Console: Database Pool -- Edit JDBC Database Pool
6.20. Console: Database Pool -- New XA Database Pool
7.1. Console: Login
7.2. Console: JMS Resource Group List
7.3. Console: Select JMS Provider
7.4. Console: JMS Resource Group Configuration
7.5. Console: JMS Resource Group Progress (First Time)
7.6. Console: JMS Resource Group Progress
7.7. Console: Select JMS Connection Factory Type
7.8. Console: Configure JMS Connection Factory
7.9. Console: Select JMS Destination Type
7.10. Console: Configure JMS Destination
7.11. Console: JMS Resource Group Deployment Plan
9.1. Console: List Security Realms
9.2. Console: Security Realm -- Basic Settings
9.3. Console: Security Realm -- Main Settings
9.4. Console: Security Realm -- Advanced Settings
9.5. Console: Security Realm -- Test Login
9.6. Console: Security Realm -- Test Login Failure
9.7. Console: Security Realm -- Test Login Success
9.8. Console: Security Realm -- Create Custom Realm
9.9. Console: Security Realm -- Configure Custom Realm
9.10. Console: Security Realm -- Edit Realm
9.11. Console: Security Realm -- Show Plan
9.12. Security: Login Module List
9.13. Security: Existing Login Module Configuration
9.14. Security: New Login Module Configuration
11.1. Web Application Deployment Plan Overview
11.2. Web Application: Class Path Settings
11.3. Web Application: Basic Settings
11.4. Web Application: Container Configuration
11.5. Web Application: Tomcat-Specific Settings
11.6. Web Application: Jetty-Specific Settings
11.7. Web Application: GBean References
11.8. Web Application: Remote EJB References
11.9. Web Application: Local EJB References
11.10. Web Application: CORBA EJB References
11.11. Web Application: Resource References
11.12. Web Application: Administered Object References
11.13. Web Application: Message Destination Refs
11.14. Web Application: Web Service References
11.15. Web Application: Web Service Port
11.16. Web Application: Security
11.17. Web Application Security: Default Principal
11.18. Web Application Security: Role Mapping
11.19. Web Application Security: Principals
11.20. Web Application Security: Login Domain Principals
11.21. Web Application Security: Realm Principals
11.22. Web Application: Module-Scoped Services
12.1. Geronimo EJB Deployment Plan
12.2. EJB: Class Path Settings
12.3. EJB: Connection Factory
12.4. EJB: Session Bean
12.5. EJB: Session Bean CORBA Settings
12.6. EJB: Entity Bean
12.7. EJB: Entity Bean CORBA Settings
12.8. EJB: CMP Entity Bean Settings
12.9. EJB: CMP Entity Bean Field Mapping
12.10. EJB: CMP Entity Bean Primary Key Generators
12.11. EJB: CMP Entity Bean Prefetch Groups
12.12. EJB: Entity Bean Data Cache
12.13. EJB: CMP Entity Bean Query Configuration
12.14. EJB: Message-Driven Bean
12.15. EJB: Message Driven Resource Adapter
12.16. EJB: Message Driven Destination
12.17. EJB: objectNameGroup References
12.18. EJB: EJB References
12.19. EJB: CORBA EJB References
12.20. EJB: Local EJB References
12.21. EJB: Resource References
12.22. EJB: Resource Environment References
12.23. EJB: Message Destination Reference
12.24. EJB: Web Service References
12.25. EJB: Relationships
12.26. EJB: Relationship Role
12.27. EJB: Security
12.28. EJB: Default Principal
12.29. EJB Security: Role Mapping
12.30. EJB Security: Principals
12.31. EJB Security: Login Domain Principals
12.32. EJB Security: Realm Principals
12.33. EJB: Module-Scoped Services
13.1. Resource Adapter Deployment Plan Overview
13.2. Resource Adapter: Class Path Settings
13.3. Resource Adapter: Configuration Overview
13.4. Resource Adapter: Instance Configuration
13.5. Resource Adapter: objectNameGroup
13.6. Resource Adapter: Outbound Configuration
13.7. Resource Adapter: Connection Instance
13.8. Resource Adapter: Connection Manager Configuration
13.9. Resource Adapter: Single Pool
13.10. Resource Adapter: Partitioned Pool
13.11. Resource Adapter: Admin Object Configuration
13.12. Resource Adapter: Module-Scoped Services
14.1. J2EE Client Deployment Plan Overview
14.2. J2EE Client: Includes
14.3. J2EE Client: Common Libraries
14.4. J2EE Client: Remote EJB References
14.5. J2EE Client: Object Name Group
14.6. J2EE Client: CORBA EJB References
14.7. J2EE Client: Web Services References
14.8. J2EE Client: Web Services Ports
14.9. J2EE Client: Resource References
14.10. J2EE Client: Administered Object References
14.11. J2EE Client: Default Security Principal
14.12. J2EE Client: Embedded Resources
14.13. J2EE Client: Module-Scoped Services
15.1. Enterprise Application Deployment Plan Overview
15.2. Enterprise Application: Class Path Settings
15.3. Enterprise Application: Module Configuration
15.4. Enterprise Application: Adding New Modules
15.5. Enterprise Application: Security
15.6. Enterprise Application Security: Default Principal
15.7. Enterprise Application Security: Role Mapping
15.8. Enterprise Application Security: Principals
15.9. Enterprise Application Security: Login Domain Principals
15.10. Enterprise Application Security: Realm Principals
15.11. Enterprise Application: Application-Scoped Services
17.1. TSS Configuration: Overview
17.2. TSS Configuration: Default Principal
17.3. Web Application Security: Principals
17.4. Web Application Security: Login Domain Principals
17.5. Web Application Security: Realm Principals
17.6. TSS Configuration: SSL
17.7. TSS Configuration: Security Mechanisms
17.8. TSS Configuration: Identity Tokens
17.9. CSS Configuration: Overview
17.10. CSS Configuration: A Security Mechanism
17.11. CSS Configuration: SSL
17.12. CSS Configuration: Authentication
17.13. CSS Configuration: Identification

List of Tables

4.1. Geronimo Deployment Plan File Names
6.1. Database Connection Pool: Default Visibility
6.2. Connection Pool Configuration Properties
7.1. JMS Resource Groups: Default Visibility
7.2. ActiveMQ Transport Types
9.1. Properties File Realm Configuration
9.2. SQL Realm Configuration
10.1. J2EE Deployment Descriptor File Names
10.2. Geronimo Deployment Plan File Names
10.3. Maven Deployment Plugin Commands
10.4. Geronimo J2EE Deployment API Connection Settings
12.1. ActiveMQ Activation Config Properties
16.1. Web Service: Login Module to Save Username & Password
17.1. TSS Configuration: CORBA SSL Attributes
17.2. CSS Configuration: CORBA SSL Attributes
17.3. CSS: Login Module to Save Username & Password

List of Examples

4.1. Explicit Dependencies
4.2. Implicit Dependencies
4.3. Web Application Deployment Descriptor: Schema vs. DTD
4.4. Nested Schemas in a Geronimo Deployment Plan
6.1. Database Pool Deployment Plan
7.1. JMS Resource Group Deployment Plan
7.2. JMS Message Broker Configuration
9.1. EAR Deployment Plan with Application Scoped Security Realm
9.2. Sample Security Realm Configuration
9.3. Properties File Realm: User File
9.4. Properties File Realm: Group File
9.5. Server-Wide Security Realm Deployment Plan
9.6. Application-Scoped Security Realm Deployment Plan
9.7. Role Mapping
9.8. Custom Realm Principal Classes
9.9. Custom Realm LoginModule
9.10. Jetty HTTPS Connector Configuration
9.11. Jetty HTTPS Connector Deployment Plan
10.1. Deployment Descriptors: Schema vs. DTD Headers
10.2. EAR with Deployment Information Outside the Modules
10.3. Maven 1 Script Using Geronimo Deployment Plugin
11.1. Web Application: Imports and Dependencies
11.2. Web Application: Configuring Virtual Hosts
11.3. Web Application: EJB Reference Example
11.4. Web Application: Resource Reference Example
11.5. Web Application Security Example
11.6. Tomcat-only and Jetty-only Deployment Plans
12.1. EJB: Imports and Dependencies
12.2. EJB: Basic CMP Configuration
12.3. EJB: Session Bean Configuration Example
12.4. EJB: BMP Entity Bean Configuration Example
12.5. EJB: CMP Entity Bean Configuration Example
12.6. EJB: Message-Driven Configuration Example
12.7. One-To-One CMR Mapping
12.8. One-To-Many CMR Mapping
12.9. Many-To-Many CMR Mapping
12.10. EJB Security Example
13.1. Resource Adapter: Imports and Dependencies
13.2. Resource Adapter: Inbound+Outbound Instance Configuration
13.3. Resource Adapter: Connection Manager (Typical JDBC Pool)
13.4. Resource Adapter: Connection Manager (Per-User JDBC Pool)
13.5. Resource Adapter: Admin Object Configuration
15.1. Enterprise Application: Imports and Dependencies
15.2. Enterprise Application: Module Configuration Example
15.3. Enterprise Application Security Example
16.1. JAX-RPC Client Code
16.2. Contacting a Servlet Web Service
16.3. Session Bean Web Service Customization
16.4. Contacting an EJB Web Service
16.5. Security Realm Plan for a Web Service Client
17.1. CORBA: Changing Default Naming Service Port
17.2. CORBA Security & Role Mapping
17.3. TSS Configuration: GSSUP Only
17.4. TSS Configuration: Client Cert and Identity
17.5. CORBA EJB Deployment Plan
17.6. Security Realm Plan for a CORBA Client with GSSUPDynamic
17.7. CSS Configuration: GSSUP Only
17.8. CSS Configuration: Client Cert and Identity
17.9. CORBA EJB Reference: J2EE Deployment Descriptor
17.10. CORBA EJB Reference: Geronimo Deployment Plan
17.11. CORBA EJB Reference: Accessing the EJB

Preface [MINIMAL]

This book is an introduction to the Apache Geronimo application server. Currently Geronimo is under active development, and has not yet reached an feature-complete release. Milestone releases are made available periodically, as new features are added and the current version seems relatively stable.

1. Drafts and Milestone Releases

The book covers a mix of current and upcoming features. Each chapter indicates which milestone release it applies to:

DRAFT (M4)

This chapter was last updated for the Milestone 4 release.

DRAFT (1.0-pre)

This chapter was writting using cutting-edge syntax some time after the Milestone 5 release. It is the closest possible to the 1.0 syntax. It should need only minor updates to be accurate for the Geronimo 1.0 release.

To try out features that are not yet available in a milestone release, you'll need to build Geronimo from source (or contact the author for a build).

[Tip]Tip

It is actually possible to run many J2EE applications in Geronimo today. Certainly the latest milestone release is good enough to start "playing around" with the server. However, tools and deployment plan formats are still subject to change.

2. A Note On Formatting

All code in this book is (or will be) formatted with a line width of no more than 65 characters. In some cases, particularly involving long class name, this makes for illegal or silly-looking code, such as:

import org.apache.geronimo.security.realm.providers.
       PropertiesFileSecurityRealm;

Please bear with me, and remember that if you copy and paste Java or XML code samples from the book into real code, you may have to remove the occasional line break. In particular, anything within double-quotes that's split across two lines should be combined into one.

3. Acknowledgements

Thanks to Erin Mulder, Craig Johannsen, John Sisson, David Jencks, and Bruce Snyder for feedback on the online draft.

Thanks to Greg Hinkle, Rob Butler, and James Holmes for detailed reviews of the draft.

Thanks to Alan Cabrera for extensive help understanding the security implementation, and to David Jencks for extensive help understanding the connectors implementatation.

Thanks to XMLmind for an outstanding free DocBook editor that I used to write this book.

Thanks to Altova for XMLSpy, which I used to generate the diagrams of the XML Schemas in this book.

Getting Started

Table of Contents

1. About Apache Geronimo [DRAFT (1.0)]
1.1. Apache Geronimo Features
1.1.1. Application Modules
1.1.2. Server Resources
1.1.3. Server Management & Deployment
1.1.4. Additional APIs
1.2. Vendor and License
1.3. Why Another Application Server?
1.4. A Brief History of Geronimo
1.5. Related Projects
1.5.1. Top-Level Services
1.5.2. Selected APIs and Tools
2. Acquiring Geronimo & Quick Start [DRAFT (1.0)]
2.1. Downloading Geronimo
2.1.1. Source Code Access
2.2. Geronimo Quick Start
2.2.1. Download & Install
2.2.2. Start the Server
2.2.3. Customize Network Ports (if necessary)
2.2.4. Log in to Management Console
2.2.5. Create a Database Pool
2.2.6. Create a Security Realm
2.2.7. Deploy Web Applications
2.2.8. Quick Start Summary
3. Installing Geronimo [DRAFT (M4)]
3.1. Platforms & Prerequisites
3.2. Quick Start Installation Procedure
3.3. Custom Installation Procedure
3.4. Automated Installation Procedure
3.5. Installation Results
3.6. Starting the Server
3.6.1. Startup Options
3.6.2. Troubleshooting Startup Problems
3.7. Stopping the Server
3.8. Running Geronimo as a Windows or UNIX Service
4. Elements of Geronimo [DRAFT (1.0-pre)]
4.1. Geronimo Architecture
4.1.1. Geronimo Managed Components: GBeans
4.1.2. Communication Between GBeans
4.2. Server Startup and Configurations
4.2.1. Configuration Dependencies
4.2.2. Adding New Applications & Configurations
4.2.3. Server Startup Options
4.3. Introduction to Deployment
4.3.1. XML Schema and Geronimo Deployment Plans
4.3.2. Deploying J2EE Application Modules
4.3.3. Deploying JDBC and JMS Resources
4.3.4. Deploying GBeans
4.4. ClassLoaders in Geronimo

Chapter 1. About Apache Geronimo [DRAFT (1.0)]

Geronimo is a free, open source J2EE™ application server. It comes with everything you need to run standard J2EE applications developed against the J2EE 1.4 specifications, and it is also backward-compatible to J2EE 1.3 and J2EE 1.2. Furthermore, its modular design makes it easy to customize, extend, or replace core server features. And thanks to the open source license, you can download the source code for troubleshooting, to help with enhancements, or just as a matter of record.

At heart, the Geronimo architecture consists of a small core, and many services loaded on top of that core. Application components and resources are in turn loaded into the services. There are several advantages to this layered approach:

  • It is possible to configure a very compact server, running only the services, resources, and applications that are strictly necessary.

  • It is easy to add new custom services to the server environment, which can be configured, managed, and accessed by applications just like the default services.

  • It's possible to replace the default implementation of any service with an alternative, so long as it implements the same interfaces.

1.1. Apache Geronimo Features

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

1.1.1. Application Modules

Web Applications (Servlet 2.4 / JSP 2.0)

Geronimo includes a web application container supporting J2EE web applications. The web container itself supports basic configuration such as network ports and SSL options, and each web application WAR may include Geronimo-specific configuration information as well. Web applications participate in the Geronimo security infrastructure, so authenticating to a web application allows access to secure EJBs and Connectors as well.

Enterprise JavaBeans 2.1

Geronimo includes an EJB container supporting Session, Entity, and Message-Driven beans, including new J2EE 1.4 features such as Web Services and the EJB Timer service. It is also backward-compatible and supports EJB 2.0 applications. EJBs can be accessed both within the same application and by remote clients (over RMI or IIOP). An EJB JAR may include Geronimo-specific configuration information in addition to the standard J2EE deployment descriptor.

J2EE Connectors 1.5

Geronimo includes a Connector container supporting both inbound and outbound Resource Adapters. Outbound connectors are the typical gateways to enterprise information systems, while inbound connectors allow external systems to deliver asynchronous messages to Message-Driven EJBs running in Geronimo. Connectors can be deployed as part of the server configuration (available to all applications) or as part of a specific application's configuration. A Connector RAR may include Geronimo-specific configuration information in addition to the standard J2EE deployment descriptor. Geronimo is also backward-compatible and supports J2EE Connector 1.0 Resource Adapters.

J2EE 1.4 Application Clients

Geronimo provides a client container for running application clients in a managed environment. This allows a client application to access all the resources in the server environment using the same JNDI environment mapping techniques available to other application modules. All communication with the server is transparent to the application, minimizing the amount of custom code required. An application client may include Geronimo-specific configuration information in addition to the standard J2EE deployment descriptor.

J2EE 1.4 Application Archives

Geronimo supports packaging all of the module types listed above into a single EAR file per application. Applications can be customized to configure and deploy specific Geronimo services when the application itself is deployed. Application dependencies can also be expressed, making it easier to handle groups of related applications.

1.1.2. Server Resources

Database Connection Pools (JDBC 3.0)

Geronimo provides database connection pools for standard JDBC drivers. Database connection pools can be deployed as part of the server configuration or as part of a specific application's configuration.

Java Message Service 1.1

Geronimo provides JMS connection factories and destinations. JMS resources can be deployed as part of the server configuration or as part of a specific application's configuration. The JMS provider may be configured for in-memory operation for maximum performance, or it may use clustering or persistent storage for enhanced reliability.

JavaMail 1.3

Geronimo provides JavaMail sessions allowing an application to send or receive e-mail (though as of v1.0 third-party transport plugins are required for POP and IMAP support).

Security (JACC 1.0)

Geronimo allows you to plug in a variety of security realm implementations, including file, LDAP, and database sources for authentication and authorization information. All the application modules can take advantage of this common security infrastructure.

1.1.3. Server Management & Deployment

Java Management Extensions 1.2

The Geronimo infrastructure leverages JMX for configuration and management. If anything, looking at a running Geronimo server with a JMX client will probably show more JMX objects than you know what to do with, but is does provide extensive configuration and management options.

J2EE Management API (JSR-77)

Building on the JMX foundation of Geronimo, the server and all application modules are exposed via the Management EJB. The J2EE management API includes a detailed object model for the manageable components in an application server, but does not detail the information or functions available for each component. Geronimo exposes robust management features for each managed component (including application modules, JDBC, JMS, and JavaMail resources, etc.).

J2EE Deployment API (JSR-88)

Working in conjunction with the management API, the deployment API allows new application modules to be configured, deployed, started, stopped, redeployed, etc. All Geronimo-specific application configuration can be performed through the deployment API, and then the fully-configured application modules can be deployed to the server.

1.1.4. Additional APIs

Java Transaction API 1.0

Geronimo supports both user-managed and container-managed transactions.

XML, SOAP, and Web Services

Geronimo includes the required JAXP, JAX-RPC, JAXR, and SAAJ APIs for XML, SOAP, and Web Services. Geronimo provides full Web Services support for J2EE components, including the ability to map and invoke external Web Services as well as the ability to expose certain application modules as Web Services.

1.2. Vendor and License

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.

1.3. Why Another Application Server?

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!

1.4. A Brief History 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 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.

1.5. Related Projects

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.

1.5.1. Top-Level Services

OpenEJB

The EJB container used by Geronimo

http://www.openejb.org/

Jetty

One of the available web containers for Geronimo

http://www.mortbay.org/jetty/index.html

Tomcat

One of the available web containers for Geronimo

http://jakarta.apache.org/tomcat/

Active MQ

The JMS provider used by Geronimo

http://activemq.codehaus.org/

TranQL

Provides database connection pool adapters in Geronimo, as well as the EJB CMP engine

http://tranql.codehaus.org/

HOWL

Provides transaction logging and recovery for Geronimo

http://howl.objectweb.org/

1.5.2. Selected APIs and Tools

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

Axis

Web Services features

http://ws.apache.org/axis/

CGlib

Bytecode manipulation library

http://cglib.sourceforge.net/

Concurrent

Utility classes for concurrency

http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/intro.html

Derby

Embedded database

http://incubator.apache.org/derby/

Jakarta Commons

A number of separate libraries offering common utility functions

http://jakarta.apache.org/commons/

MX4J

The JMX engine that Geronimo is built on

http://mx4j.sourceforge.net/

Velocity

Used by several included web applications (debug console, etc.), as well as the Geronimo build and packaging process

http://jakarta.apache.org/velocity/

XMLBeans

XML binding library used to read and write deployment descriptors and configuration files

http://xmlbeans.apache.org/

Chapter 2. Acquiring Geronimo & Quick Start [DRAFT (1.0)]

Geronimo can be freely downloaded and installed from the project home page on the Internet. This chapter discusses the download process, and then takes a quick tour of installing and starting Geronimo, connecting to the management console, deploying a database connection pool, setting up a security realm, and deploying an application.

2.1. Downloading Geronimo

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:

  • Binary Release -- a .tar.gz or .zip package that can be unpacked to produce a working Geronimo installation, ready to run with default settings. Generally the .tar.gz packages are best suited for Mac or UNIX platforms, while the .zip packages are best suited for Windows platforms.

  • Installer Package -- an executable JAR. When run, it produces a Wizard-style installer interface, offering configuration options such as the network ports to use, the default administrator username and password, etc. Currently this is the most convenient way to change the administration account and network ports Geronimo listens on at installation time. The installer package can also be used to perform automated installations.

  • Source Code -- a .tar.gz or .zip package with the source code for Geronimo (and in some cases, closely related projects such as OpenEJB). The Geronimo release can be rebuilt completely from the provided source code, though the build scripts require a Maven installation and a Java 1.4.2 development kit.

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

  • Jetty Web Container

  • Tomcat Web Container

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

2.1.1. Source Code Access

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:

  • A Java Development Kit, version 1.4.2

  • Apache Maven 1.x, in order to download dependencies and build Geronimo

  • A Subversion 1.x client, in order to check out the source code

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.

2.2. Geronimo Quick Start

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

Quick Start: Install Directory

2.2.2. Start the Server

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

Figure 2.2. Quick Start: Startup Output

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.

2.2.3. Customize Network Ports (if necessary)

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.

Figure 2.3. Quick Start: Editing Ports in config.xml

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

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

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

2.2.8. Quick Start Summary

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

  • Downloaded Geronimo

  • Installed Geronimo

  • Changed any conflicting network ports

  • Tried out the Geronimo management console

  • Created a database connection pool

  • Created a security realm based on the test database pool

  • Deployed a simple web application requiring no customization

  • Deployed a more complex web application, customizing it to use the test database pool and security realm

  • Tried a login to make sure everything worked

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.

Chapter 3. Installing Geronimo [DRAFT (M4)]

There are three methods for installing Geronimo. The quick start approach is fast and easy, but does not give you the opportunity to customize the installation. The install package is a traditional wizard-style installer, and it gives you more customization options during the install, at the cost of a somewhat more involved process. Finally, the automated install can be used to repeat an identical installation on a different machine, with no interaction required. Any of these approaches will result in a working server, so it's mainly a matter of whether you find the default network ports to be suitable and whether the automated install would be beneficial.

[Note]Note

This chapter assumes you have downloaded a milestone release of Geronimo. If not, please see Chapter 2, Acquiring Geronimo & Quick Start [DRAFT (1.0)].

3.1. Platforms & Prerequisites

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:

  • Windows 2000, XP, and 2003

  • Linux x86 (Debian, Red Hat, SuSE, Mandrake, and Gentoo)

  • Linux x86_64 (SuSE)

  • Mac OS X

  • Solaris 8

  • HP-UX 11.0

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

3.2. Quick Start Installation Procedure

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

3.3. Custom Installation Procedure

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

Geronimo Installer: Welcome

Clicking Next brings up the license screen:

Figure 3.2. Geronimo Installer: License

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

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

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

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

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

Geronimo Installer: Main Configuration

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

Username and Password

The administrative login for the server. This is primarily used by the deploy tool when it connects to a running server to deploy, start, or stop applications (see Section 10.4, “The Deploy Tool”). In future milestones, this will also be the account used to log in to the web-based management console.

Hostname

Several of the included services bind to a specific host name / IP when starting. The two most common values for this settings are localhost (meaning accept connections from the same machine only) and 0.0.0.0 (meaning bind to all available network interfaces). However, in a machine with multiple network interfaces, it's possible to specify a specific IP or hostname here to listen on that interface only.

HTTP Port

The network port that the web container listens on. This needs to be used in any HTTP URLs that refer to web applications running in Geronimo. Note that on UNIX platforms, you must run Geronimo as root to bind to privileged ports (under 1024), which is not recommend. To bind to port 80 (the default HTTP port), it would be better to run Geronimo behind an Apache web server where Apache listens on port 80 and Geronimo can listen on a non-privileged port.

HTTPS Port

The secure network port that the web container listens on. This needs to be used in any HTTPS URLs that refer to web applications running in Geronimo. Note that on UNIX platforms, you must run Geronimo as root to bind to privileged ports (under 1024), which is not recommend. To bind to port 443 (the default HTTPS port), it would be better to run Geronimo behind an Apache web server where Apache listens on port 443 and Geronimo can listen on a non-privileged port.

Security Port (to be added in Milestone 4)

The network port that the security system listens on. This is used for client authentication requests, and it must be configured in the client's JAAS configuration (see Chapter 14, Client Applications (Client JARs) [IN PROGRESS]).

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

Figure 3.8. Geronimo Installer: EJB/IIOP Configuration

Geronimo Installer: EJB/IIOP Configuration

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

Naming Port

The network port that the JNDI server listens on. Remote clients use this to connect to the server's JNDI tree. You'll need to customize your connection settings every time you run the deploy tool if you change this, so it's best to keep the default value of 1099.

EJB Port

The network port that the EJB container listens on. TODO: does this need to be configured in clients anywhere?

Clients

The IP addresses that the EJB server should accept connections from. TODO: is there a value for "any" and how do you specify a list or range?

IIOP Port

The port used to connect to EJBs via RMI-over-IIOP (as opposed to the plain RMI port listed under EJB Port above).

ORB Port

The port that the CORBA ORB listens on

CosNaming Port

The port that the CORBA naming service listens on. Similar to JNDI and RMI, a CORBA client will typically connect to the naming service first, then look up a specific service that it connects to using the ORB port.

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

Figure 3.9. Geronimo Installer: Service Configuration

Geronimo Installer: Service Configuration

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

JMS Port

The network port that the default ActiveMQ JMS server listens on. This will need to be configured for any custom connection factories that should connect to that JMS server (a default connection factory is provided).

Derby Port

Geronimo includes an embedded Derby database used by the server itself. It is also available for use by applications, so it is configured for remote access, and this is the network port it listens on.

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

Figure 3.10. Geronimo Installer: Unpack Files

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:

Figure 3.11. Geronimo Installer: Customize Installation