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

Geronimo Installer: Customize Installation

This screen customizes the Geronimo installation according to the selected options. (Under the covers, it is building the startup JARs and deploying the core service configurations.) When it finishes, click Next to move on to the release notes:

Figure 3.12. Geronimo Installer: Release Notes

Geronimo Installer: Release Notes

Once you have finished with the release notes (which are also saved to the Geronimo installation directory), click Next to move on to the summary screen:

Figure 3.13. Geronimo Installer: Install Summary

Geronimo Installer: Install Summary

If you click the button to save an automatic installation script, you can repeat the installation (generally on a different machine) with an identical configuration. This option will prompt you to select a file to save the install script to. The install script is an XML file, though the file name is not important -- it just needs to be passed on the command line for an automated installation.

Once you click Done, Geronimo is ready to go!

3.4. Automated Installation Procedure

[Warning]Warning

The automated install routine does not work correctly for the M4 release of Geronimo. It unpacks a number of files, but does not run the post-processing steps required to complete the installation.

To perform an automated installation you must have gone through the custom graphical installation once, and then saved a script on the last screen. With that, you can repeat the installation using a command like this:

java -jar geronimo-1.0-M4-installer.jar auto-install-file.xml

The last argument is the file you saved using the Generate an automatic installation script button on the final screen of the graphical installation. When you run the automated install, you'll get non-interactive text-mode output like this:

[ Starting automated installation ]
[ Starting to unpack ]
[ Processing package: Server (1/5) ]
[ Processing package: J2EE Features (2/5) ]
[ Processing package: JMX Console Web App (3/5) ]
[ Processing package: Demo Web Application (4/5) ]
[ Processing package: Sample Derby Database (5/5) ]
[ Unpacking finished. ]
[ Starting processing ]
Starting process Construct Server Executable (1/11)
        ...
[ Processing finished ]
[ Writing the uninstaller data ... ]
[ Automated installation done ]

Once you see the final "Automated installation done" message, Geronimo is installed and ready to go, in the same directory that was chosen during the original graphical installation.

[Tip]Tip

The install script is a fairly self-explanatory XML file. If you want to change the installation directory, for example, just alter the value in the installpath element.

3.5. Installation Results

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:

bin/

Holds the JARs used to start the server and run the offline deploy tool

config-store/

Holds subdirectories for modules that can be run in Geronimo. An application might be such a module, as might a resource such as a Connector or database pool. Some or all of these configuration modules will be started when the Geronimo server is started. The subdirectories are numbered sequentially, and the config-store/index.properties file contains a list of which modules are located in which numbered subdirectories. The Geronimo deployment tools maintain the contents of this directory automatically.

lib/

Holds libraries required to load the most basic parts of Geronimo -- the foundation (or "kernel") which in turn loads all the other application, resource, and service modules.

repository/

Holds shared libraries which the application and resource modules can refer to. Not everything in this directory will be loaded -- each library will be loaded only when a module that depends on it is loaded. You might add entries here for database drivers or libraries that should be visible to multiple application modules without being separately distributed with each application.

schema/

Holds a reference copy of the XML Schema definitions for all the J2EE and Geronimo deployment descriptors, as well as the definitions of all the Geronimo configuration files.

var/

Holds some files pertaining to the runtime state of the server, such as log files, the transaction log, security realm configuration files, and a list of the configuration modules that were running the last time the server was running.

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

In addition to the directories listed above, the custom and automated installers create two more subdirectories:

installer-temp/

Holds the customized Geronimo deployment plans for all of the core services. This might be useful if you want to further customize and redeploy one of the core configurations. This capability should not be taken lightly, however, as deploying a bad configuration of a core service may cripple the Geronimo installation. More information on the default services is provided in Chapter 19, Overview of Core Geronimo Services [EMPTY].

Uninstaller/

Holds an executable JAR that can be used to uninstall Geronimo.

3.6. Starting the Server

Once Geronimo has been installed, it must be started from the command line. Open a console window or shell prompt, change to the Geronimo installation directory, and run a command like this to start the server:

java -jar bin/server.jar

You should see output like this:

Booting Geronimo Kernel (in Java 1.4.2_07)...
Starting Geronimo Application Server
[*******] 100%   9s Startup complete                                   
  Listening on Ports:
    1099 0.0.0.0   RMI Naming
    1527 127.0.0.1 Derby Connector
    4201 127.0.0.1 OpenEJB Connector EJB
    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
Geronimo Application Server started (version 1.0-M4)

During the startup, the first thing that happens is that the "Kernel" has started, which is reponsible for loading and managing all the other components of the server. After that, several configuration modules are loaded and started (the names appear on the progress line during the startup, but are replaced by the "Startup complete" message at the end). The default Geronimo installation currently starts 5 configurations (and includes several more that are available but not started). As suggested by the port list, the default services include:

  • A web container (Jetty on ports 8080 and 8443)

  • An EJB container (OpenEJB with naming services and remote access on ports 1099 and 4201)

  • A JMS broker (ActiveMQ on port 61616)

  • An embedded database (Derby, with remote access on port 1527)

In addition, a number of other services are started that do not require additional network ports, including:

  • A log service (that writes to a server log at var/log/geronimo.log)

  • A transaction manager (so the server scanned for any "in doubt" transactions -- anything running when the server shut down or crashed)

  • A security realm (based on properties files in var/security/)

  • A JMX connector allowing outside JMX clients to monitor and manage the Geronimo server

[Tip]Tip

It is not actually necessary to start Geronimo from any particular directory. So long as you pass the correct server.jar location on the java command line, you can run the start command from any directory on the file system.

3.6.1. Startup Options

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

-quiet

Suppresses the progress bar display during startup. This is typically used when redirecting the console output to a file, since the progress bar updates look somewhat bizarre when viewed by, for example, a text editor.

-v

Normally, Geronimo displays WARN and higher log output on the console, though all log output is saved to the server log file. This option reduces the threshold for console output to INFO, meaning you'll see somewhat more output during the startup process. It also disables the startup progress bar (since at this output level, it would typically be mangled by log output that occurs during the startup sequence).

-vv

Similar to -v, except the console log threshold is set to DEBUG.

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

3.6.2. Troubleshooting Startup Problems

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

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

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

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

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

3.7. Stopping the Server

Once the Geronimo server is running, you can stop it by hitting Ctrl-C in the console window where it's running, or killing the process. This brute-force mechanism will be supplemented by a graceful shutdown process in a later milestone release of Geronimo.

3.8. Running Geronimo as a Windows or UNIX Service

The current milestone releases of Geronimo do not support running it as a service. This capability will be added in a future milestone release.

Chapter 4. Elements of Geronimo [DRAFT (1.0-pre)]

This chapter gives a brief introduction to many important aspects of Geronimo:

  • The high-level architecture of Geronimo, composed of a kernel and services

  • How to start specific services or applications

  • The style and typical syntax of Geronimo configuration files

  • How Geronimo services, applications, and resources are packaged and deployed

  • The ClassLoader hierarchy used by Geronimo

These topics are more related than you might think. Every service, resource, or application is configured with a Geronimo deployment plan and deployed to the server in the same way, becoming a "configuration" available to the server. The kernel manages the lifecycle of the configuration, and the components within the configuration. Each configuration can be started when the server is started, and gets its own ClassLoader when run. These ClassLoaders can be arranged into a hierarchy, so each configuration may have a parent and many children.

4.1. Geronimo Architecture

The Geronimo core, or kernel, is small and basically responsible for managing the lifecycle and dependencies of all the individual components that run within Geronimo. Those components may be services (such as a transaction manager), resources (such as a database pool), or applications (such as a web application). The kernel also manages the process of hooking individual components up to each other, so separate components can work together at runtime. For example, the web application service (usually Jetty or Tomcat) needs a reference to every web application that starts, so when it gets an incoming HTTP request, it can dispatch it to the appropriate web application.

A diagram of a simplified Geronimo runtime might look like this (don't worry about the specific services yet, but look at the relationship between the kernel and the components):

Figure 4.1. Components in a Geronimo Runtime

Components in a Geronimo Runtime

TODO: Replace this with a better-looking diagram

In Figure 4.1, “Components in a Geronimo Runtime”, the solid bars indicate that the kernel starts and manages all of the other components. The dashed lines indicate that the individual components communicate with each other once they're up and running. The diagram is a little busy, but note that the kernel is ultimately responsible for the lifecycle of all of these components. Components don't load or manipulate each other directly; instead the kernel sets up the components and provides the communication pathways between them.

4.1.1. Geronimo Managed Components: GBeans

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

  • The application

  • Each J2EE module within the application (EJB JAR, web application WAR, etc.)

  • Each servlet in a web application (for the Jetty web container)

  • Each EJB in an EJB JAR

  • Each connection factory or admin object configured for a J2EE connector

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

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

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

4.1.2. Communication Between GBeans

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

Figure 4.2. Communication Between GBeans

Communication Between GBeans

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

4.2. Server Startup and Configurations

The available configuration modules are listed in the config-store/index.properties file -- again, each one may represent a service, a resource, or an application module, each of which is (under the covers) typically composed of a series of GBeans. In the absence of specific directions, when Geronimo starts, it starts all the configuration modules that were running last time the server was run. (This is controlled by var/config/config.xml, which is updated whenever there are changes to GBeans or configurations.)

The pre-configured modules shipped with Geronimo are listed below. Note that some of them are started by default, and some others should not actually be started manually (they are for internal use only). This list is from the Geronimo-Jetty stack, so a Tomcat build will have slightly different names (e.g. geronimo/welcome-tomcat/1.0/car instead of geronimo/welcome-jetty/1.0/car).

geronimo/j2ee-system/1.0/car

Contains the basic services required for Geronimo to operate (such as GBeans for the repository and logging services). This configuration should always be run. It is started in the default Geronimo distribution.

geronimo/rmi-naming/1.0/car

Handles the RMI registry and naming services, which are additional fundamental services for the J2EE server environment. It is started in the default Geronimo distribution.

geronimo/j2ee-server/1.0/car

Contains the services necessary for Geronimo to act as a J2EE server (such as GBeans for the web application service, EJB service, and J2EE connector service). This configuration should be run when Geronimo should be capable of hosting J2EE applications (which for the purposes of this book means "always"). It is started in the default Geronimo distribution.

geronimo/j2ee-security/1.0/car

Handles the core security services for Geronimo, including the administration security realm. This is required for any security features to work. It is started in the default Geronimo distribution.

geronimo/j2ee-corba/1.0/car

Contains basic CORBA configuration that allows code running in Geronimo to act as a CORBA client (calling out to remote CORBA services) or CORBA server (being called by remote CORBA clients). This does not need to be started if CORBA features are not required, and it is not started by default. Note: Geronimo's CORBA implementation requires a Sun Java1.4.2 VM (though IBM offers a Geronimo-based product with CORBA features that run on the IBM Java VM).

geronimo/jetty/1.0/car

Handles the basic web container, including web application hosting features, network listeners, web application deployer, etc. It is started by default.

geronimo/directory/1.0/car

Provides an embedded Apache Directory LDAP server. This is not used by the current Geronimo core; it is available to be used by applications, for custom security realms, etc. It is started by default, but may be safely stopped.

geronimo/ldap-realm/1.0/car

A sample LDAP-based security realm, to demonstrate the embedded Directory features. It is started by default, but may be safely stopped.

geronimo/system-database/1.0/car

Starts a basic embedded Derby database and network listener. It is required in order to support features like the EJB Timer service and JMS persistence. This is started in the default Geronimo distribution.

geronimo/activemq-broker/1.0/car

Starts an ActiveMQ JMS server. This is started in the default Geronimo distribution (because the SystemJMS service depends on it).

geronimo/activemq/1.0/car

Starts a JMS connection factory (that connects to the default ActiveMQ server) and two JMS queues for internal server use. This is started in the default Geronimo distribution.

geronimo/client-system/1.0/car

Should not be started. Used internally by the J2EE application client container.

geronimo/client/1.0/car

Should not be started. Used internally by the J2EE application client container.

geronimo/client-security/1.0/car

Should not be started. Used internally by the J2EE application client container.

geronimo/client-corba/1.0/car

Should not be started. Used internally by the J2EE application client container.

geronimo/javamail/1.0/car

Provides JavaMail features. Geronimo provides both the JavaMail framework and a simple SMTP transport. For more advanced SMTP features or POP/IMAP support, you can run a third-party transport on the basic JavaMail framework.

geronimo/geronimo-gbean-deployer/1.0/car

Handles basic deployment operations for Geronimo, including deploying new configurations. This should be running for all but the most locked-down servers. It is started by default.

geronimo/j2ee-deployer/1.0/car

Expands the geronimo-gbean-deployer to handle J2EE applications and modules (except web applications). This should be running for all but the most locked-down server configurations (or non-J2EE configurations).

geronimo/hot-deployer/1.0/car

Monitors the geronimo/deploy directory for activity, deploying any files copied into that directory, redeploying as the files are updated, and undeploying when the files are removed. This is an optional service, but it is started by default.

geronimo/jetty-deployer/1.0/car

Handles deployments of web applications using the Jetty web container. It is started by default.

geronimo/ldap-demo-jetty/1.0/car

A sample web application, including directions for setting up the sample LDAP security realm and tests to confirm that it's working correctly. This application is optional, and it is started by default at /ldap-demo

geronimo/welcome-jetty/1.0/car

A sample web application that listens on the server root context (e.g. http://localhost:8080/) and provides a basic sanity check and some pointers for more information. This application is optional, and it is started by default. It must be disabled if you have a different application that should listen for requests on the root context of "/".

geronimo/servlets-examples-jetty/1.0/car

A sample web application that shows some example servlets. This is based on the examples distributed with the Tomcat server. It is optional, and started by default at /servlets-examples

geronimo/jsp-examples-jetty/1.0/car

A sample web application that shows some example JSPs. This is based on the examples distributed with the Tomcat server. It is optional, and started by default at /jsp-examples

geronimo/webconsole-jetty/1.0/car

The web management console application. This provides a web-based UI for server configuration and administration. The console is recommended for all but the most locked-down server configuraitons. It is started by default at /console

geronimo/jmxdebug-jetty/1.0/car

A web application that browses the JMX objects available in the local Geronimo server. It presents a list of objects grouped by category. This can be used to ensure that the expected resources are actually running and debug reference failures, though the JMX names tend to be somewhat cryptic. It is started by default at /debug-tool

geronimo/remote-deploy-jetty/1.0/car

A web application that handles deployment requests when you run the command-line deploy tool on a machine separate from the application server. This is recommended for most configurations, though the deployment tools can still be run locally even if this is disabled. It is started by default at /remote-deploy

geronimo/uddi-jetty/1.0/car

A JAXR/UDDI server implementation, which runs as a web application. It is optional and started by default, at /juddi

geronimo/daytrader-derby-jetty/1.0/car

A sample application that can be used for performance testing and benchmarking. It is optional and started by default, and the web application component is available at /daytrader

geronimo/daytrader-derby-jetty-streamer-client/1.0/car

The application client component of the daytrader application. It is optional and should not be started manually, only run using the application client container (see Section 14.2.2, “Running a J2EE Application Client”).

geronimo/online-deployer/1.0/car

Should not be started. This is used under the covers in conjunction with the deployer.jar tool.

geronimo/shutdown/1.0/car

Should not be started. This is used under the covers in conjunction with the shutdown.jar tool.

[Tip]Tip

You can compare the list above to the available configurations in geronimo/config-store/index.properties. That file should contain all the entries here plus any additional configurations you've deployed.

Individual configurations can be started and stopped using the Geronimo deploy tool (however, the deploy tool cannot manipulate specific GBeans within a configuration). For example, to start two additional modules, once the server is up and running you could issue commands such as:

java -jar bin/deployer.jar start \
          geronimo/j2ee-corba/1.0/car
java -jar bin/deployer.jar start \
          geronimo/javamail/1.0/car

Note that these commands require an administrator login, which defaults to a username of "system" with password "manager". For detailed syntax and more information about the deploy tool, see Section 10.4, “The Deploy Tool”.

4.2.1. Configuration Dependencies

A configuration module may have both explicit and implicit dependencies. Any configuration module may have a parent and it may also import other modules, so the parent and imports make up the explicit dependencies. When starting a configuration module, the server will always ensure that its parent has been started first (and its parent and so on). Therefore one strategy for resolving dependencies between modules is to create a explicit dependencies on everything that your application needs in order to run: an EAR may have two database configurations listed as imports, etc

Example 4.1. Explicit Dependencies

This is a sample Geronimo deployment plan header for a web application. The web application uses the configuration name MyWebApp and its parent is defined as ApplicationDatabasePool and an import set for ApplicationJMSResources:

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

That means that the database pool and JMS resources will always be started before the web application. All Geronimo deployment plans include these same configId and parentId attributes on the main element for the file, and an import element shortly thereafter. The specific format of the Geronimo deployment plans for application modules is covered in Part III, “J2EE Applications on Geronimo”.

The explicit dependency (parentId) is optional, and if not defined, the only explicit dependency will be on the core Geronimo infrastructure.

The other type of dependencies are implicit dependencies. These are dependencies which you did not specifically configure as such, but which the server can deduce based on the resource references and EJB references declared within a J2EE application.

Example 4.2. Implicit Dependencies

Imagine a web application that uses two database connections. It declares resource references for each:

<web-app xmlns="http://java.sun.com/xml/ns/j2ee" version="2.4">
  ...
  <resource-ref>
    <res-ref-name>jdbc/FinanceDatabase</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
    <res-sharing-scope>Shareable</res-sharing-scope>
  </resource-ref>

  <resource-ref>
    <res-ref-name>jdbc/ApplicationDatabase</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
    <res-sharing-scope>Shareable</res-sharing-scope>
  </resource-ref>
</web-app>

Then in the Geronimo deployment plan maps those to two different databases, one application database pool, and one finance database pool:

<web-app xmlns="http://geronimo.apache.org/xml/ns/web"
         xmlns:naming="http://geronimo.apache.org/xml/ns/naming"
         configId="MyWebApp">
  <resource-ref>
    <ref-name>jdbc/FinanceDatabase</ref-name>
    <resource-link>FinanceDatabasePool</resource-link>
  </resource-ref>

  <resource-ref>
    <ref-name>jdbc/ApplicationDatabase</ref-name>
    <resource-link>ApplicationDatabasePool</resource-link>
  </resource-ref>
</web-app>

Based on that deployment plan, the server knows that the database pools FinanceDatabasePool and ApplicationDatabasePool must be running in order for the web application to work. So the application has implicit dependencies on those two database pools.

Finally, if an application uses resources from other applications (or the server itself) without declaring references in its deployment descriptors, the server has no way of identifying those dependencies, period. In that case it will always be up to you to ensure that everything an application requires is up and running.

[Tip]Tip

To avoid worrying about dependencies altogether, you can include all your application modules in an EAR, and configure the necessary Geronimo resources in the EAR as well. That will make sure the application modules and all the resources they require are deployed as a single unit. However, that approach also prevents the sharing of a resource (such as a database connection pool) between multiple applications.

4.2.2. Adding New Applications & Configurations

The deployer tool can be used to add new configuration modules to the Geronimo server. The usual syntax looks like this:

java -jar bin/deployer.jar deploy mymodule.jar

This would deploy and start a new module defined by the archive mymodule.jar. It will prompt for a username and password, which default to "system" and "manager" respectively. This command can be run on any J2EE application module (EJB JAR, WAR, RAR, EAR, etc.) to create a configuration for it. The server must be running for this command to work.

In cases where the Geronimo-specific deployment information is stored in a file outside the application archive, an additional parameter can be used to identify the Geronimo deployment plan:

java -jar bin/deployer.jar deploy mymodule.jar \
        module-geronimo-dd.xml

Another deployment option is to copy the module to the geronimo/deploy directory and allow the hot deployer to notice it and deploy it (this does not work with a Geronimo deployment plan unless the plan is packaged in the application module). Generally the command-line deploy tool has a couple advantages: in addition to handling external plans, it also prints any deployment errors directly to the console where you ran it (as opposed to the hot deploy tool, where any errors go to the server console and server log only). However, the command-line deployer does not work when the server is not running, while the hot deploy directory can at least deploy new applications during server startup (it doesn't handle redeployment or undeployment during startup).

For more deployment options, see Section 10.4, “The Deploy Tool”.

The same deployer syntax can be used to deploy Geronimo services in addition to application modules. In this case you may not have a module archive to deploy -- if the necessary code is already in the Geronimo repository, the module arguments can be omitted and only the deployment plan specified.

4.2.3. Server Startup Options

The following command-line options are available when starting the server:

--quiet

Suppresses the normal progress bar output while starting Geronimo. This is useful for starting from scripts or automated processes.

--long

Instead of the progress bar format, list each configuration along with its startup time as it is started. This is also a good format for scripts.

-v or --verbose

Set the console log level to DEBUG instead of the default INFO. Most Geronimo output will still be suppressed outside of the startup process, but application DEBUG messages will be displayed on thie console, and you can also turn down the base log level of org.apache.geronimo in the Log4J configuration.

-vv or --veryverbose

Set the console log level to TRACE.

--override [configId] [configId] ...

Override the saved configuration selection and only start the configurations specifically listed on the command line. WARNING: this is quite dangerous as listing the wrong configurations can result in a non-functional server.

4.3. Introduction to Deployment

4.3.1. XML Schema and Geronimo Deployment Plans

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

[Tip]Tip

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

A Geronimo deployment plan contains configuration information such as:

  • A name for the configuration, and the name of its parent configuration

  • Service-specific information for GBeans, like the listen port for the web container or the transaction timeout for the transaction manager

  • Which server resource should satisfy each resource reference declared by an application module

  • How to map CMP entity beans to a specific database

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

Example 4.3. Web Application Deployment Descriptor: Schema vs. DTD

Here's a typical J2EE 1.3 web application deployment descriptor (WEB-INF/web.xml) based on a DTD:

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

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

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

Here's the same for J2EE 1.4, based on a Schema:

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

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

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

  • The extra information is provided within the first element, instead of before it

  • The document type is identified by an XML namespace (the xmlns attribute) instead of by a URI (the bit starting with -//Sun...)

  • You still provide a URL pointing to the schema like you did for the DTD, but now it's provided by the xsi:schemaLocation attribute (which takes a namespace and then a URL for that namespace)

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

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

Example 4.4. Nested Schemas in a Geronimo Deployment Plan

In this example, a Geronimo web deployment plan (WEB-INF/geronimo-web.xml) uses some elements from the common Geronimo naming schema:

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

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

The elements with no prefix are from the namespace http://geronimo.apache.org/xml/ns/j2ee/web-1.0, while the elements with the naming: prefix are from the namespace http://geronimo.apache.org/xml/ns/naming-1.0. Both namespaces are identified in the web-app header (which makes them available anywhere within the document), though the naming: namespace could also have been declared on the naming:resource-ref element (in which case it would be available only to that element and its children).

[Tip]Tip

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

4.3.2. Deploying J2EE Application Modules

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

  • Web Applications (WAR modules)

  • EJBs (EJB JAR modules)

  • J2EE Connectors (RAR modules)

  • Client Applications (Client JAR modules)

  • Enterprise Applications (EAR modules)

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

  • Packaged into the module, like the J2EE deployment descriptor

  • Provided separately to the deployment tool

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

Table 4.1. Geronimo Deployment Plan File Names

Module TypeDeployment Plan File
Web ApplicationWEB-INF/geronimo-web.xml
EJB JARMETA-INF/openejb-jar.xml
J2EE ConnectorMETA-INF/geronimo-ra.xml
Client ApplicationMETA-INF/geronimo-application-client.xml
Enterprise ApplicationMETA-INF/geronimo-application.xml

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

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

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

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

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

4.3.3. Deploying JDBC and JMS Resources

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

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

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

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

4.3.4. Deploying GBeans

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

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

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

scheduler-plan.xml

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

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

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

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

4.4. ClassLoaders in Geronimo

Each configuration (server, application module, or resource) has its own ClassLoader. The hierarchy of ClassLoaders matches the hierarchy of configurations. So if a Web Application module has an EJB JAR as its parent, then the ClassLoader for the EJB JAR will be the parent of the ClassLoader for the Web Application. Clearly the ClassLoader arrangement is one of the key reasons to configure the module dependencies in Geronimo.

Within an application EAR, EJBs and RARs are loaded in one ClassLoader, while Web Applications are loaded in a child of that ClassLoader. The ClassLoader hierarchy for an EAR including one module of each type and using a database would look like Figure 4.3, “EAR ClassLoader Hierarchy”.

Figure 4.3. EAR ClassLoader Hierarchy

EAR ClassLoader Hierarchy

Notes on Figure 4.3, “EAR ClassLoader Hierarchy”:

  • The ClassLoaders with a white background are created by Java -- the first two cover the internal JVM classes, and the last includes the command-line argument (which includes a trick to load tools.jar containing the Java compiler).

  • The ClassLoaders with a grey background are created by Geronimo. The geronimo/j2ee-server/1.0/car configuration loads all of the critical classes and services for J2EE applications, which is why it's almost always used as the parent configuration for J2EE applications.

  • The application does not need to directly depend on the database configuration, because the two only interact through the java.sql and javax.sql classes, which are defined at a higher level.

  • Dependencies listed in Geronimo deployment plans are loaded in the same ClassLoader as the module that declares them. In the case of the database pool, the JDBC driver is loaded as a dependency. If the resource adapter in the EAR declares dependencies, they'll be loaded with the rest of the EJB and Connector classes in the ClassLoader for the EAR.

Configuring Geronimo

Table of Contents

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

Chapter 5. Core Configuration [EMPTY]

5.1. Network Configuration

5.2. Logging Configuration

5.3. Transaction Configuration

Chapter 6. Database Configuration [DRAFT (1.0-pre)]

Most enterprise applications use a relational database in one way or another. Geronimo provides database connection pools, so you can bind a certain database into JNDI, access it from your applications, and reuse existing database connections rather than constantly closing and re-opening them. When mapped as application resources, these database connection pools can be accessed from:

  • EJBs

  • Web Applications

  • Client Applications

Geronimo supports both standard JDBC connection pools with local transaction, and XA database pools supporting two-phase commit transactions. However, there are a limited number of supported XA drivers in Geronimo 1.0, whereas any JDBC driver should work for a normal JDBC pool.

Database connection pools may be configured at the server level, at the application level, or in the case of an application client, as a part of a single application module. The default visibility can be summarized like this:

Table 6.1. Database Connection Pool: Default Visibility

Pool TypeMultiple ApplicationsMultiple Modules in Same ApplicationClient Module Only
Server-Wideyesyesno
Application-Scopednoyesno
Client-Scopednonoyes

This chapter covers configuring database connection pools in each of these ways.

[Note]Note

Client-scoped and application-scoped pools are started and stopped with the owning application or module, and the default reference mapping strategies ignore resources deployed in other applications. However, this is not a security feature; it's always possible to manually construct a reference to any resource running in the server (no matter what its default visibility is).

6.1. JDBC Drivers

In order to deploy any database connection to Geronimo, you need to make a JDBC driver available to it. Geronimo has a standard directory structure to accommodate additional libraries that may be required by the services, resources, or applications it runs. If you look at the repository directory under the Geronimo installation, you'll see something like this:

The JARs for the common libraries are each stored under repository/library-name/jars in Geronimo. If you wanted to add, for example, the Oracle JDBC driver, you could create the directory repository/oracle/jars and copy the Oracle JAR into that directory. A PostgreSQL JAR might likewise go under repository/postgresql/jars. Then when you configure the connection pool later, you'll list the driver JAR as a dependency.

[Tip]Tip

Note that JARs in the repository should be identified using a version number in the name, so different versions of the same driver can be included in the same repository directory. Then different database pools can use separate versions of the same product's driver (for example, for Oracle 9i vs. 10g, or PostgreSQL 7.4 vs. 8.0).

6.1.1. Automatic JDBC Driver Installation

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

  • HSQLDB 1.7.3 and 1.8.0

  • MaxDB (SAP DB) 7.5 and 7.6

  • McKoi 1.0.3

  • MySQL (JDBC driver version 3.0 and 3.1)

  • PostgreSQL 7.3, 7.4, 8.0, and 8.1

  • SQL Server (jTDS driver version 1.1 and 1.2)

  • Sybase (jConnect 5.5 and 6.0)

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

6.2. Database Pools as Connectors and the TranQL RAR

Under the covers in Geronimo, database connection pools are implemented by deploying a J2EE Connector that provides the pool. JMS resources and user-provided Connectors work the same way, so the plumbing is similar for all three. In general, this implementation strategy isn't terribly important, but you'll notice that to configure a database connection pool, you'll need to write a Geronimo-specific deployment descriptor for a J2EE Connector -- one whose configuration properties are the database server, JDBC URL, etc. But you also need a RAR file containing the Geronimo logic for managing the database connection pool -- this is currently provided by a package called TranQL, and the RAR file can be found in the Geronimo installation at repository/tranql/rars/tranql-connector-1.1.rar.

[Tip]Tip

If you deploy database pools through the Geronimo console, you won't have to worry about the details of the RAR file and deployment plan. The console can only deploy server-wide database pools, though you can use it to write a plan for an application-scoped or client-scoped database pool.

When you deploy a server-wide connection pool, you'll give the customized deployment descriptor and the TranQL RAR to the deploy tool, and it will deploy the new database pool as it would any other standalone J2EE Connector. When you deploy an application-scoped connection pool, you'll include the TranQL RAR in the application EAR like any other application module, and add the customized deployment descriptor to the EAR as well. When you deploy a client-scoped connection pool, you'll use a shortcut in the client module's Geronimo-specific deployment descriptor that allows you to configure a J2EE Connector right there, for that module alone. In any of those cases the TranQL RAR is the same and the configuration file format is the same; it's just the method of deployment that's different.

6.3. Easy Configuration and Deployment using the Console

The fastest way to configure a database pool is to use the console. The section walks through that process.

To begin with, start Geronimo and point your browser to the console, which is typically at a URL like http://localhost:8080/console/. This brings up the login screen:

Figure 6.1. Console: Login

Console: Login

The default login is username "system" and password "manager" (this can be changed in var/security/users.properties and var/security/groups.properties -- for more detail see Chapter 9, Security Configuration [DRAFT (1.0-pre)]). Once logged in, the specific path depends on what you're trying to do, as described in the following sections:

6.3.1. Create a new JDBC Pool

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

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

Figure 6.2. Console: List Database Pools

Console: List Database Pools

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

6.3.1.1. Step 1: Basic Settings

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

Figure 6.3. Console: Database Pool -- Basic Settings

Console: Database Pool -- Basic Settings

The fields here are:

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

Select Next to continue.

6.3.1.2. Step 2: Connection Properties

This screen handles the basic settings for the database pool:

Figure 6.4. Console: Database Pool -- Connection Properties

Console: Database Pool -- Connection Properties

The fields here are:

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

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

FieldDescription
HostThe host name or IP address of the database server.
PortThe network port that the database server is listening on.
DatabaseThe name of the database to connect to, if the server hosts multiple databases.

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

Figure 6.5. Console: Database Pool -- Driver Error

Console: Database Pool -- Driver Error

6.3.1.3. Step 3: Pool Properties

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

Figure 6.6. Console: Database Pool -- Pool Settings

Console: Database Pool -- Pool Settings

The fields here are:

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

There are three paths forward from here:

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

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

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

6.3.1.4. Step 4: Test Pool

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

Figure 6.7. Console: Database Pool -- Test Successful

Console: Database Pool -- Test Successful

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

Figure 6.8. Console: Database Pool -- Test Failed

Console: Database Pool -- Test Failed

If the test failed, you have three options:

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

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

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

6.3.1.5. Detailed Pool Edit Screen

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

Figure 6.9. Console: Database Pool -- Detailed Edit

Console: Database Pool -- Detailed Edit

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

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

There are three paths forward from here:

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

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

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

6.3.2. Create a new XA Database Pool

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

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

  • Derby embedded server

  • Derby network server

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

6.3.2.1. Create New Database Pool

Figure 6.10. Console: Database Pool List View

Console: Database Pool List View

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

6.3.2.2. Step 1: Select Database Type

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

Console: Database Pool -- Select XA Database

The fields here are:

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

Select Next to continue.

6.3.2.3. Step 2: Edit XA Database Pool Settings

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

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

Console: Database Pool -- New XA Database Pool

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

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

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

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

6.3.3. Import a Pool from Another Application Server

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

  • JBoss 4.x

  • WebLogic 8.1

The import process starts on the pool list screen:

Figure 6.13. Console: Database Pool -- Start Import

Console: Database Pool -- Start Import

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

6.3.3.1. Import File Selection

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

Figure 6.14. Console: Database Pool -- JBoss Import

Console: Database Pool -- JBoss Import

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

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

Figure 6.15. Console: Database Pool -- WebLogic Import

Console: Database Pool -- WebLogic Import

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

6.3.3.2. Import Status

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

Figure 6.16. Console: Database Pool -- Import Status

Console: Database Pool -- Import Status

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

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

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

6.3.4. Generate a Plan for an Application or Client Scoped Pool

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

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

6.3.4.1. Plan View

Figure 6.17. Console: Database Pool -- Show Plan

Console: Database Pool -- Show Plan

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

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

[Tip]Tip

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

6.3.4.1.1. Deploy via Command-Line Deploy Tool

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

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

java -jar GERONIMO_HOME/bin/deployer.jar deploy \
    GERONIMO_HOME/database-pool.xml \
    GERONIMO_HOME/repository/tranql/rars/tranql-connector-1.1.rar
6.3.4.1.2. Deploy as Application-scoped Pool

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

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

6.3.4.1.3. Deploy as Client-scoped Pool

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

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

6.3.5. Edit an Existing Pool

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

6.3.5.1. Select Database Pool to Edit

Figure 6.18. Console: Database Pool List View

Console: Database Pool List View

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

6.3.5.2. Edit JDBC Database Pool

The JDBC pool edit screen looks like this:

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

Console: Database Pool -- Edit JDBC Database Pool

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

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

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

6.3.5.3. Edit XA Database Pool

The XA database pool edit screen looks like this:

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

Console: Database Pool -- New XA Database Pool

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

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

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

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

6.4. Manual Configuration and Deployment

Under the covers, the console creates a Geronimo deployment plan for the database pool, and then deploys the appropriate RAR file with that plan using the same deployment logic that the command-line deployer uses. After deploying a database pool, if you look at the list of deployed RAR files, you'll see an entry for the database pool.

[Note]Note

The name (or configId) of the deployed RAR file is not important except to stop or undeploy it. When application modules want to refer to the database pool, they'll use the name configured in the database pool screen in the console, or the name specified in the connectiondefinition-instance if the plan is deployed manually.

In other words, the console is not doing anything special, and a database pool can be configured and deployed manually. This may be especially useful if you want to deploy the same pool to multiple servers, or save the configuration for every developer to apply to their local instance later. This section describes how to configure and deploy database pools using the underlying text files and command-line tools.

6.4.1. Configuring a Database Pool

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

[Note]Note

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

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

Example 6.1. Database Pool Deployment Plan

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

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

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

The key attribute and elements here are:

configId

If this is deployed as a server-wide connection pool, the name specified here can be passed on the server command line to start the pool. In any case, it should be unique, and the configurations that ship with Geronimo use a format of product-group/product-name/version/type, as in some-company/my-product/1.0/jar.

parentId

Identifies the parent for this configuration. The parent is primarily important for ensuring that standalone RARs have access to the correct J2EE classes in their ClassLoader -- it should either be geronimo/j2ee-system/1.0/car or another configuration that has j2ee-system as an ultimate parent. For more information on the Geronimo ClassLoader hierarchy, see Section 4.4, “ClassLoaders in Geronimo”.

dependency

The dependency identifies a JAR that must be loaded for the connector to load -- this is generally used for the JDBC driver JAR. This element may appear more than once if multiple JARs need to be loaded.

uri

The path to the dependency JAR, relative to geronimo/repository. See Section 6.1, “JDBC Drivers”.

connectionfactory-interface

Must be javax.sql.DataSource

name

The name that other modules will use to refer to this connection pool. This must be unique within any given scope (server, application, etc.), and it will be easiest to configure references if this is further unique across all resources deployed at any scope in the server.

config-property-setting

Specifies a value for one of the configuration properties for the connector. The name attribute identifies the property, and the content of this element is the value to set for that property. The available properties are listed in Table 6.2, “Connection Pool Configuration Properties”.

max-size

The maximum number of simultaneous connections to allow for this connection pool.

min-size

The minimum size of the connection pool. If the pool falls below this size, it will be refilled to the minimum size. However, the pool is not initialized to this size until the first time a connection attempt is made. The default value is 0.

blocking-timeout-milliseconds

If a caller requests a connection and all the connections in the pool are in use, the caller will wait this long for a connection to become available. If the timeout expires without an available connection, an exception will be thrown.

idle-timeout-minutes

This interval defines how often the pool is checked for unused connections. If during that check any individual connection has been unused for at least this long, it will be closed and removed from the pool. The default value of 0 disables idle timeouts.

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

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

Table 6.2. Connection Pool Configuration Properties

NameDescription
DriverThe class name of the JDBC driver
ConnectionURLThe JDBC URL used to connect to the database
UserNameThe user name used to connect to the database
PasswordThe password used to connect to the database
CommitBeforeAutocommitIf the JDBC driver does not commit pending work when setAutoCommit(true) is called, then this should be set to true to work around that. It's always safest to set it to true, but the performance is better for JDBC-compliant drivers when this is set to false (which is the default).
ExceptionSorterClassThe JDBC pool needs to know whether a given SQLException means that the connection has failed, or if it's just a normal SQL problem. This class is responsible for determining whether any given SQLException is fatal (and if so, the connection will be closed and released from the pool). In general, this is a product-specific decision, but product-specific implementations are not available as of Milestone 4. The current options are NoExceptionsAreFatalSorter or AllExceptionsAreFatalSorter (both in the package org.tranql.connector). This is mainly important if some SQLExceptions indicate or result in a broken database connection, and Geronimo should open new connections to compensate.
[Note]Note

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

6.4.2. Deploying a Database Pool

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

6.4.2.1. Deploying a Server-Wide Database Pool

To deploy a server-wide database pool, you'll create a deployment plan using the format described in Section 6.4.1, “Configuring a Database Pool” and then deploy the connection pool using that plan.

First you should save the database pool deployment plan to a file like database-pool.xml (the name can be anything you like). Then you need to locate the TranQL RAR and deploy the pool using a command like this:

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

Note that this example assumes that the server is running, and it can be run from any directory, so long as you point it to the deployer JAR in geronimo/bin. The two arguments should point to the TranQL RAR file and the database pool deployment plan (the order doesn't matter). If the server is not running, you can use the command distribute instead of deploy though then you'll still have to start the configuration once the server is running. For more information on deployment commands, see Section 10.4, “The Deploy Tool”.

Other application modules can map resources to that database pool using the procedure described in Section 6.5, “Using a Database Pool”.

6.4.2.2. Deploying an Application-Scoped Database Pool

In contrast to server-wide database pools, application-scoped database pools are only visible to a single application by default, which must be packaged as an EAR.

To deploy an application-scoped database pool, you'll include the TranQL Connector RAR as a module in your application EAR (for normal JDBC pools; XA database pools would use a product-specific TranQL RAR, which should be in the same location.). First you should save the database pool deployment plan to a file like database-pool.xml (the name can be anything you like). Then you need to locate the TranQL RAR, and add both of these to your EAR.

For example, the EAR structure might look like this:

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

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

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

META-INF/application.xml

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

Notice the final module entry for the RAR.

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

META-INF/geronimo-application.xml

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

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

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

6.4.2.3. Deploying a Client-Scoped Database Pool

The most restricted type of database pools, client-scoped database pools are only visible to the application client module that declares them. These pools are not visible to either other modules in the same application or to other applications in the same server.

To deploy a client-scoped database pool, you'll refer to a common copy of the TranQL Connector RAR (for normal JDBC pools) -- make sure it appears in geronimo/repository/tranql/rars. (XA database pools would use a product-specific TranQL RAR, which should be in the same location.)

A client-scoped connection pool is declared in the Geronimo deployment plan for the application client module that should have access to the pool. The plan will have an additional resource element containing the pool definition. A deployment plan that declared a pool using the same configuration shown in Example 6.1, “Database Pool Deployment Plan” would look like this:

META-INF/geronimo-application-client.xml

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

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

The important elements here are:

resource

This element contains the entire definition of the client-scoped database pool

external-rar

This is formatted as a repository URI.

connector

This element contains all the data from the connector configuration file. The content is no different that the content of the deployment plan would have been for the server-wide or application-scoped database pools.

In the next section you'll see how to access that pool from application code.

6.5. Using a Database Pool

There are two steps necessary in order for an application module to use a database connection pool. First, the deployment information for the module must declare a resource reference and map it to a specific connection pool available to that module. Second, the module's code must look up the connection pool in JNDI.

[Note]Note

The procedure described here uses J2EE 1.4 deployment descriptor syntax. The same mapping could be done with earlier versions, but the deployment descriptor file format would be somewhat different.

6.5.1. Updating the Module's Deployment Information

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

WEB-INF/web.xml

<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
         http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
         version="2.4">
  ...
  <resource-ref>
    <res-ref-name>jdbc/DataSource</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
    <res-sharing-scope>Shareable</res-sharing-scope>
  </resource-ref>
</web-app>

The key elements here are:

resource-ref

This block holds all the configuration information for a single database pool reference.

res-ref-name

A JNDI name fragment, which also acts as a unique identifier for this resource reference. When an application component looks in JNDI, it will find the resource under jdbc:comp/env/ followed by the value specified here (in this case, jdbc:comp/env/jdbc/DataSource).

res-type

Should always be javax.sql.DataSource for a database pool.

res-auth

If set to Container, the server will handle logging in to the database with the username and password configured for the connection pool. If set to Application, the application must specify a username and password every time it gets a connection from the pool.

res-sharing-scope

If multiple components in the same transaction attempt to use database connections from the same pool, this value controls whether they will all get the same connection (Shareable) or they will each get a different connection (Unshareable). The default value of Shareable is usually preferable, though it may not work if one component will change connection settings such as the isolation level or localization (and you don't want other components to be affected by that).

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

WEB-INF/geronimo-web.xml

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

The important elements here are:

resource-ref

Holds the Geronimo information that maps a resource reference to a specific database pool.

ref-name

Matches the res-ref-name in the J2EE deployment descriptor, and identifies which resource reference this configuration block applies to.

target-name

Identifies the database connection pool that will be used to fulfill requests to the resource named by the ref-name element. To identify the pool, the value specified here must match the name specified in the database pool deployment information.

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

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

[Tip]Tip

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

6.5.2. Application Code

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

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

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

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

[Note]Note

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

6.6. Reconfiguring a Previously Deployed Pool

From the command line, Geronimo does not have very good support for altering a database pool configuration at runtime. The best way to reconfigure a database pool on the command line is to alter the original configuration file, and then redeploy the database pool (or the application or client module containing the pool definition).

However, pools can be conveniently reconfigured from the console, as described in Section 6.3.5, “Edit an Existing Pool”.

Chapter 7. JMS Configuration [DRAFT (1.0)]

Many applications use the Java Message Service for asynchronous messaging. Geronimo includes a JMS server, and application components can access JMS resources including connection factories, topics, and queues from the JMS server. When mapped as application resources, these JMS objects can be accessed from:

  • EJBs

  • Web Applications

  • Client Applications

JMS resource groups may be configured at the server level, at the application level, or a part of a single application client module. The default visibility can be summarized like this:

Table 7.1. JMS Resource Groups: Default Visibility

Resource Group TypeMultiple ApplicationsMultiple Modules in Same ApplicationClient Module Only
Server-Wideyesyesno
Application-Scopednoyesno
Client-Scopednonoyes

This chapter covers configuring JMS resource groups in each of these ways. We'll also look at customizing the embedded ActiveMQ JMS server, though that's not normally necessary.

[Note]Note

Client-scoped and application-scoped resource are started and stopped with the owning application or module, and the default reference mapping strategies ignore resources deployed in other applications. However, this is not a security feature; it's always possible to manually construct a reference to any resource running in the server (no matter what its default visibility is).

7.1. JMS Resource Groups, Connectors, and the ActiveMQ RAR

There are two aspects to JMS in Geronimo: the JMS Server itself (also known as the Message Broker), and the connection factories, topics, and queues through which individual application components communicate with the message broker. The ActiveMQ message broker is started by default in Geronimo, and usually does not need to be changed. JMS connection factories and destinations are bundled into JMS Resource Groups which can be individually deployed into Geronimo. Under the covers, JMS resource groups are configured as J2EE Connectors, and the default JMS resource groups connect to the embedded ActiveMQ server, so the J2EE Connector used to deploy JMS connection factories and destinations is known as the ActiveMQ RAR.

[Tip]Tip

If you deploy JMS Resource Groups through the Geronimo console, you won't have to worry about the details of the RAR file and deployment plan. The console can only deploy server-wide resource groups, though you can use it to write a plan for an application-scoped or client-scoped resource group.

With that in mind, there are several steps to deploying JMS resources:

  1. Ensure an ActiveMQ message broker is running in the server (the default configuration for it is geronimo/activemq-broker/1.0/car).

  2. Write the RAR deployment plan for the JMS resources

  3. Deploy JMS resources using the ActiveMQ RAR

  4. Configure application components to refer to those JMS resources

  5. Write code that accesses JMS resources in JNDI and configures properties such as persistence and transactions before sending or receiving messages.

When you deploy a server-wide resource group, you'll give the customized deployment descriptor and the ActiveMQ RAR to the deploy tool, and it will deploy the new resource group as it would any other standalone J2EE Connector. When you deploy an application-scoped JMS resource group, you'll include the TranQL RAR in the application EAR like any other application module, and add the customized deployment descriptor to the EAR as well. When you deploy a client-scoped resource group, you'll use a shortcut in the client module's Geronimo-specific deployment descriptor that allows you to configure a J2EE Connector right there, for that module alone. In any of those cases the ActiveMQ RAR is the same and the configuration file format is the same; it's just the method of deployment that's different.

7.2. Easy Configuration and Deployment Using the Console

The fastest way to configure a JMS resource group is to use the console. The overall process is to configure the connection to the JMS server, add any number of connection factories and destinations, and then review and deploy the resource group. The section walks through that process.

[Warning]Warning

The console features described here are available in Geronimo starting with version 1.0.1.

To begin with, start Geronimo and point your browser to the console, which is typically at a URL like http://localhost:8080/console/. This brings up the login screen:

Figure 7.1. Console: Login

Console: Login

The default login is username "system" and password "manager" (this can be changed in var/security/users.properties and var/security/groups.properties -- for more detail see Chapter 9, Security Configuration [DRAFT (1.0-pre)]).

7.2.1. JMS Resource Group List

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

Figure 7.2. Console: JMS Resource Group List

Console: JMS Resource Group List

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

7.2.2. Creating a new JMS Resource Group

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

7.2.2.1. Select JMS Provider RAR

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

Figure 7.3. Console: Select JMS Provider

Console: Select JMS Provider

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

7.2.2.2. Initial Configuration

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

Figure 7.4. Console: JMS Resource Group Configuration

Console: JMS Resource Group Configuration

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

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

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

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

7.2.2.2.1. ActiveMQ Configuration Settings

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

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

7.2.2.3. Create Resource Group Progress

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

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

Console: JMS Resource Group Progress (First Time)

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

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

Figure 7.6. Console: JMS Resource Group Progress

Console: JMS Resource Group Progress

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

7.2.2.4. Add Connection Factory

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

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

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

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

Figure 7.7. Console: Select JMS Connection Factory Type

Console: Select JMS Connection Factory Type

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

Figure 7.8. Console: Configure JMS Connection Factory

Console: Configure JMS Connection Factory

The standard settings here are:

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

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

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

7.2.2.5. Add Destination

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

  • javax.jms.Topic

  • javax.jms.Queue

Figure 7.9. Console: Select JMS Destination Type

Console: Select JMS Destination Type

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

Figure 7.10. Console: Configure JMS Destination

Console: Configure JMS Destination

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

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

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

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

7.2.2.5.1. ActiveMQ Destination Configuration

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

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

7.2.3. Generate a Plan for an Application or Client Scoped Resource Group

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

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

Figure 7.11. Console: JMS Resource Group Deployment Plan

Console: JMS Resource Group Deployment Plan

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

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

[Tip]Tip

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

7.2.3.1. Deploy via Command-Line Deploy Tool

To deploy via the command-line deploy tool, save the plan to a file on disk. Then that file can be used along with the listed RAR file to deploy the pool. (Note that the RAR file may be different for different JMS providers, but the RAR file displayed on the screen in Figure 7.11, “Console: JMS Resource Group Deployment Plan” is always the correct one based on the way the resource group was configured.)

For example, if the plan was saved as GERONIMO_HOME/jms-resources.xml, and it was a standard resource group using the RAR file activemq/rars/activemq-ra-3.2.1.rar, then a deploy command might look like this:

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

7.2.3.2. Deploy as Application-Scoped Resource Group

To deploy the resource group as part of an EAR, save the plan to a file in the EAR, and copy the RAR file into the EAR as well. Again, note that the RAR file may be different for different JMS providers, but the RAR file displayed on the screen in Figure 7.11, “Console: JMS Resource Group Deployment Plan” is always the correct one based on the way the resource group was configured.

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

7.2.3.3. Deploy as Client-Scoped Resource Group

To deploy the resource group as part of an application client module, you'll need to copy the plan content into the client deployment plan, and refer to the correct RAR file from the client deployment plan as well. Again, note that the RAR file may be different for different JMS providers, but the RAR file displayed on the screen in Figure 7.11, “Console: JMS Resource Group Deployment Plan” is always the correct one based on the way the resource group was configured.

For full details on this procedure, see Section 7.3.2.3, “Client-Scoped Deployment”.

7.3. Manual Configuration and Deployment

Under the covers, the console creates a Geronimo deployment plan for the JMS resource group and then deploys the appropriate RAR file with that plan using the same deployment logic that the command-line deployer uses. After deploying a resource group, if you look at the list of deployed RAR files, you'll see an entry for the new group.

[Note]Note

The name (or configId) of the deployed RAR file is not important except to stop or undeploy it. When application modules want to refer to the JMS resources, they'll use the names configured in the connection factory or destination screens in the console.

In other words, the console is not doing anything special, and a JMS resource group can be configured and deployed manually. This may be especially useful if you want to deploy the same resource to multiple servers, or save the configuration for every developer to apply to their local instance later. This section describes how to configure and deploy JMS resource groups using the underlying text files and command-line tools.

7.3.1. JMS Resource Group Configuration

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

A typical resource group deployment plan would look like this:

Example 7.1. JMS Resource Group Deployment Plan

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

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

This rather dense deployment plan has 4 basic sections:

  1. The connector header

  2. Settings to connect to the message broker

  3. ConnectionFactory definitions

  4. Queue and Topic definitions

7.3.1.1. The Connector Header

The important elements in the connector header are:

configId

A unique name for this configuration. If the JMS resources are deployed server-wide, the name specified here can be passed to the deploy tool to start or stop the JMS configuration.

parentId

If a parentId is specified, this configuration will become a child of that one. The value specified as the parentId needs to match the configId specified for the parent configuration. Usually the JMS resource configuration is set to be a child of the message broker configuration, so the objects declared here have direct access to the server resources (through their parent ClassLoader) -- this is required in order to use the in-VM transport, and recommended in any case to resolve dependencies and startup ordering. (For more information on the Geronimo ClassLoader hierarchy, see Section 4.4, “ClassLoaders in Geronimo”.)

7.3.1.2. Message Broker Connection Settings

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

resourceadapter-name element

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

ServerUrl configuration property

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

UserName configuration property

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

Password configuration property

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

workmanager element

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

[Tip]Tip

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

7.3.1.3. ConnectionFactory Settings

The outbound-resourceadapter block contains the ConnectionFactory settings. In general, not much needs to be customized for the ConnectionFactory other than the name. However, note that you are actually configuring a pool of ConnectionFactory instances that will be shared across the JMS clients. The important elements in this block are:

connectionfactory-interface

Should normally be javax.jms.ConnectionFactory (though you could use javax.jms.QueueConnectionFactory or javax.jms.TopicConnectionFactory if you want a more restrictive connection factory).

name

The name that other modules will use to refer to this ConnectionFactory.

implemented-interface

Lists any specific interfaces that the ConnectionFactory should implement, in addition to the standard interface declared in the connectionfactory-interface element. The values here allow you to cast that to either a QueueConnectionFactory or TopicConnectionFactory, in addition to the generic ConnectionFactory.

max-size

The maximum size of the ConnectionFactory connection pool. Because of the pooling, this is also the maximum number of simultaneous connections allowed.

min-size

The minimum size of the connection pool. If the pool falls below this size, it will be refilled to the minimum size. However, the pool is not initialized to this size until the first time a connection attempt is made. The default value is 0.

blocking-timeout-milliseconds

If a caller requests a connection and all the ConnectionFactories in the pool are in use, the caller will wait this long for a ConnectionFactory to become available. If the timeout expires without an available ConnectionFactory, an exception will be thrown.

idle-timeout-minutes

This interval defines how often the pool is checked for unused connections. If during that check any individual connection has been unused for at least this long, it will be closed and removed from the pool. The default value of 0 disables idle timeouts.

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

7.3.1.4. Topic or Queue Settings

The adminobject block contains a reference to a Topic or Queue. Any number of adminobject blocks may be included, to configure as many destinations as you like. In many cases, multiple adminobjects may be present for the same underlying Topic or Queue -- this is because the adminobject is essentially the glue between message-destination objects declared in J2EE deployment descriptors, and the actual physical destinations. In the case where several J2EE modules use different names to refer to the same destination, you'll need several adminobject definitions to map all of those to the same destination.

The important settings in this block are:

adminobject-interface element

Should be javax.jms.Topic or javax.jms.Queue for a Topic or Queue, respectively.

adminobject-class element

Similarly should use org.activemq.message.ActiveMQTopic or org.activemq.message.ActiveMQQueue for a Topic or a Queue, respectively.

message-destination-name element

A name that application modules (like EJBs or web applications) will use to refer to this destination in their configuration information.

PhysicalName configuration property

The name of the actual Topic or Queue in the JMS Server. Different adminobjects can refer to the same Topic or Queue if the physical names match.

7.3.2. JMS Resource Deployment

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

7.3.2.1. Server-Wide Deployment

First you should save the JMS Resource deployment plan to a file like jms-resource-plan.xml (the name can be anything you like). Then you can deploy the resource configuration using a command like this:

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

Note that this example assumes that the server is running, and it can be run from any directory, so long as you point it to the deployer JAR in geronimo/bin and the correct plan file and RAR locations. The two arguments should point to the ActiveMQ RAR file and the JMS deployment plan (the order doesn't matter). If the server is not running, you can use the command distribute instead of deploy, though then you'll still have to start the configuration once the server is running. For more information on deployment commands, see Section 10.4, “The Deploy Tool”.

7.3.2.2. Application-Scoped Deployment

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

For example, the EAR structure might look like this:

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

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

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

META-INF/application.xml

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

Notice the final module entry for the RAR.

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

META-INF/geronimo-application.xml

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

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

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

[Tip]Tip

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

7.3.2.3. Client-Scoped Deployment

To deploy client-scoped JMS Resources, you'll refer to a common copy of the ActiveMQ RAR. Make sure it appears in geronimo/repository/activemq/rars for the client's Geronimo installation.

Module-scoped JMS Resources are declared in the Geronimo deployment plan for the module that should have access to the resources. The plan will have an additional resource element containing the entire JMS Resource deployment plan. A deployment plan that declared JMS resources using the same configuration shown in Example 7.1, “JMS Resource Group Deployment Plan” would look like this:

META-INF/geronimo-application-client.xml

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

The important elements here are:

resource

This element contains the entire definition of the module-scoped JMS Resources

external-rar

This is formatted as a repository URI.

connector

The entire contents of the JMS Resource deployment plan should be inserted here.

In this case, when the application module is started, the JMS resources will be started as well.

7.4. JMS Applications

In the preceding sections, you deployed a JMS Server, and then JMS resources including a connection factory and destinations. To use these from an application module, the module needs to map references to the resources in its deployment information, and then the module's code needs to look up the resources in JNDI.

[Note]Note

The procedure described here uses J2EE 1.4 deployment descriptor syntax. The same mapping could be done with earlier versions, but the deployment descriptor file format would be somewhat different.

7.4.1. Updating the Module's Deployment Information

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

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

WEB-INF/web.xml

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

The important elements here are:

resource-ref

Declares a connection factory reference

res-ref-name

The partial JNDI name where the ConnectionFactory will appear. In this case, the ConnectionFactory will appear in JNDI at java:comp/env/jms/AConnectionFactory for the web application.

res-sharing-scope

When set to Shareable (the default), allows more than one application component in the same transaction to use the same ConnectionFactory. Should be set to Unshareable if a component will make changes to the ConnectionFactory that should be invisible to other components even within the same transaction (in which case each will get a different ConnectionFactory).

message-destination-ref

Declares a message destination reference, which may be a topic or a queue.

message-destination-ref-name

The partial JNDI name where the Topic or Queue will appear. In this case, the topic will appear in JNDI at java:comp/env/jms/ATopic, and a Queue will appear at java:comp/env/jms/AQueue.

message-destination-type

Should be either javax.jms.Topic or javax.jms.Queue

message-destination-link

Must match the message-destination-name of a message-destination declared later in the same file, and also the message-destination-name for an adminobject declared in the JMS resource deployment plan.

message-destination

There should be a message-destination block for every destination used in this configuration file.

message-destination-name

Matches the message-destination-link of a message-destination-ref declared elsewhere in the same file, and also the message-destination-name for an adminobject declared in the JMS resource deployment plan.

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

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

WEB-INF/geronimo-web.xml

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

The important elements here are:

resource-ref

Holds the Geronimo information mapping a resource reference to a specific connection factory that's available to the module

ref-name

Matches the res-ref-name in the J2EE deployment descriptor, and identifies which reference this configuration block applies to

resource-link

Matches the name specified for the connection factory in the JMS resource deployment information. For server-wide or application-scoped connection pools, the name is located in the deployment plan used for the ActiveMQ connector. For module-scoped connection pools, the name is located in the configuration block in a resource element appearing later in this same deployment plan.

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

[Tip]Tip

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

7.4.2. Application Code

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

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

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

7.5. Message Broker Configuration and Deployment

A message broker hosts the destinations (topics and queues), manages delivery, applies options such as transactional delivery and persistent messages, and so on. When configuring the server, you don't create specific destinations, but you can customize things like where persistent messages should be stored and whether the message broker should be clustered.

Since Geronimo starts an ActiveMQ message broker by default, the procedures described in the section are usually not necessary, but they are described in case more extensive ActiveMQ customization is required.

7.5.1. Quick Start

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

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

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

7.5.2. Message Broker GBean Configuration

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

[Tip]Tip

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

A sample GBean configuration looks like this:

Example 7.2. JMS Message Broker Configuration

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

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

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

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

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

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

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

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

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

[Warning]Warning

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

7.5.2.1. Dependency Configuration Elements

The elements in Example 7.2, “JMS Message Broker Configuration” related to dependencies include:

import

Indicates that another Geronimo configuration should be a parent of this one. In this case, the ActiveMQ broker uses the system database as a parent, because the JDBC persistent store will use the system database.

dependency

Holds a single JAR that includes code for the GBeans, or third-party libraries that the GBeans require. Multiple JARs can be listed by using multiple dependency elements.

uri

The URI identifying the dependency, in the standard repository format. The JAR must be located under the repository/ directory of the Geronimo installation.

In this case, a number of JARs are listed, including ActiveMQ itself and a number of dependencies. Make sure the version numbers you list here match the JARs actually present in the geronimo/repository subdirectories.

7.5.2.2. GBean Configuration Elements

The rest of the elements in Example 7.2, “JMS Message Broker Configuration” control the GBeans for the JMS Server. There are two JMS GBean types -- the core JMS Server configuration (or ActiveMQContainer) and one or more transports (or ActiveMQConnectors) providing a pathway for JMS resources to communicate with the core JMS Server. Each of the GBean definitions has the same overall form, with elements and attributes including:

gbean

The overall wrapper for a single GBean configuration

gbean:name

The unique name to use for this GBean. It is combined with some default settings based on the GBean type and deployment style to create a full GBean Name identifying this component. Note that some of the GBeans here include references to each other, so changing the name of a GBean may require updating the references to it to match. Finally, note that every GBean must have a unique name.

gbean:class

The implementation class for this GBean. There specific values that must be used for this.

attribute

Sets a property exposed by the GBean class. When you use an attribute tag, you provide the value as a basic Java type such as String or Integer. The name attribute will be used to identify the setter to invoke on the GBean, the type attribute specifies the data type, and the content of this element is the value to set.

reference

Sets a property exposed by the GBean class. When you use a reference tag, you provide either a gbean-name element with the full GBean Name that identifies another GBean, or a group of child elements that specifically identify certain portions of the GBean name (leaving the rest to use default values).

While that gives you a feel for the structure of the GBean configuration, each of the JMS GBean types requires specific configuration options.

7.5.2.2.1. The ActiveMQContainer GBean

The first GBean in the example creates the core JMS Server. This must be present. The configuration that can be performed here includes:

gbean:name

The name may be changed to something other than ActiveMQ if you like. The connector GBeans need to refer to this one by name, so changes to this will require changed to those.

brokerName attribute

A name used to identify this ActiveMQ instance.

persistenceAdapter reference

A pointer to the persistence implementation, which typically involves a back-end data store and a cache on top of it. Normally this GBean refers to the cache, and the cache refers to the underlying persistence mechanism.

7.5.2.2.2. The Persistence Implementation GBeans

The next GBeans in the example create a persistence implementation that is a cache on top of a journaling system on top of a JDBC data store. Some persistence implementation must be present, and while all these layers are not strictly required, they give a good balance between performance and reliability. The ActiveMQContainer GBean must refer to the topmost persistence GBean, and each persistence GBean refers to the next one down the chain. While each persistence GBean is distinct, they are similar and the configuration options are listed together here:

gbean:name

The name may be changed, though the ActiveMQContainer GBean needs to refer to the topmost persistence GBean by name, and each persistence GBean needs to refer to the next by name, so each GBean needs to be kept synchronized with name changes to the GBean it depends upon.

cacheSize attribute

The number of entries the caching GBeans holds in its cache.

serverInfo reference

This reference should not be changed, as it allows ActiveMQ to discover other elements of the Geronimo configuration. In this case, the journaling GBean uses it to locate a directory to use for its journal.

directory

The directory (relative to the server directory identified by the ServerInfo service) where the journaling GBean stores its journal.

journalType

The format used for the journal.

longTermPersistence reference

A pointer to the next GBean in the chain, which this one uses to store persistent data.

dataSource

The database connection pool that the JDBC persistence GBean uses to communicate with the database. This should be a JCAManagedConnectionFactory GBean, where the name is the name of the database pool.

7.5.2.2.3. The ActiveMQConnector GBeans

Once the core JMS Server is available, we need to define one or more methods for JMS resources to contact it. This may include network transports, a direct connection for clients in the same JVM, and more. Whichever transports are provided here will be available when we configure JMS resources later. You'll configure one GBean for each transport -- Example 7.2, “JMS Message Broker Configuration” has one GBean for an in-VM transport, and one GBean for a TCP/IP transport.

The recommended transport types are summarized in Table 7.2, “ActiveMQ Transport Types”. Other transport types are available, but they are generally more suitable for peer-to-peer operation instead of a configuration with a JMS Server.

Table 7.2. ActiveMQ Transport Types

Transport TypeURL
direct in-VMvm://localhost
TCPtcp://host:port
SSLssl://host:port

The configuration that can be performed on an ActiveMQConnector includes:

gbean:name attribute

A unique name for this GBean.

url property

The URL that clients will use to connect to the JMS Server through this connector. The URL controls how the connector will listen for client connections.

activeMQContainer property

A reference to the core JMS Server. This example uses a gbean-name element, which must exactly match the overall GBean name of the ActiveMQContainer GBean (which includes its gbean:name attribute and some other stuff defined by the implementation class). It's also possible to break up the reference and only list the components that can't be defaulted, using syntax similar to the serverInfo reference above.

7.5.3. Message Broker GBean Deployment

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

7.5.3.1. Server-Wide Deployment

First, create a deployment plan that's simply a wrapper around the dependencies and GBeans above, and save it to a file such as message-broker-plan.xml (you can use any name). The file should look like this:

message-broker-plan.xml

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

Next, deploy that with a command like this:

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

(Note that this command assumes that the server is running.)

7.5.3.2. Application-Scoped Deployment

To deploy a JMS Server to a single application, you'll add the GBean definitions to the deployment plan for the application (which must be packaged as an EAR). This is typically a META-INF/geronimo-application.xml file in the application EAR. If you don't already have a Geronimo deployment plan for the application, you can create one with nothing but the message broker GBean configuration.

A typical geronimo-application.xml deployment plan would look like this:

META-INF/geronimo-application.xml

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

Then the application can be packaged and deployed like normal, and the message broker will be started when the application is started.

7.5.3.3. Client-Scoped Deployment

A client-scoped message broker is configured the same way as an application-scoped message broker, except the GBean configuration is inserted into the deployment plan for a single application module instead of for the application EAR. For example, here's an geronimo-application-client.xml file including a JMS Server as part of an client deployment:

META-INF/openejb-jar.xml

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

For the specific ordering of elements within the different module deployment plans, see Chapter 11, Web Applications (WARs) [DRAFT (1.0)], Chapter 12, Enterprise Java Beans (EJB JARs) [DRAFT (1.0)], and Chapter 14, Client Applications (Client JARs) [IN PROGRESS].

Chapter 8. Additional Services [EMPTY]

8.1. J2EE Connectors

8.2. Java Mail Resources

Chapter 9. Security Configuration [DRAFT (1.0-pre)]

In Geronimo, you can define and activate multiple security realms. Each security realm can authenticate users (validate their login), and provide a set of Principals used to authorize those users (control which services they can access). Since each secured J2EE application module provides a list of roles applicable to that module, you can specify which users or groups should be considered to have each application role. Finally, if certain resources (such as legacy database connections) require separate logins, it's also possible to map each user in the Geronimo security realm to a different account to be used with those resources.

Since there are a number of security-related options and a number of configuration points to straighten them all out, this chapter begins with a more extensive walkthrough of all the security concepts and their relations to each other, and then covers the configuration options for each.

9.1. Geronimo Security Concepts

9.1.1. Login: Authentication and Principals

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

  • A user visits a web application requiring authentication

  • A client application requires the user to authenticate in order to access a secured server-side resource (such as an EJB)

  • The server administrator is required to authenticate to use administrative tools to connect to the server

  • An application deployer is required to authenticate in order to deploy to a running server

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

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

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

9.1.2. Security Realms

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

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

  • Authenticate based on a username and password, certificate, or Kerberos credentials

  • Record all login attempts

  • Reject a login after a certain number of failures for that user

  • Add extra credentials when a user logs in, allowing them to transparently sign on to a different resource with a different username and password (for example, a database or J2EE connector)

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

9.1.2.1. Default Security Realm

Geronimo does not have a server-wide default security realm. Any number of security realms may be configured in the server, and each application module should specify the name of the security realm it wants to use. In some cases, application deployments may be rejected if the J2EE deployment descriptor includes security settings but the Geronimo deployment plan omits the specify a security realm or other security settings.

9.1.3. JAAS Login Modules

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

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

Geronimo ships with login modules that handle many common cases:

  • Authenticating against a list of users and groups stored in properties files on the server's filesystem.

  • Authenticating against a database holding the users and groups

  • Authenticating via Kerberos

  • Authenticating via SSL client certificates, where a properties file maps certificate names to users and groups

  • Auditing (recording all login attempts) to a file

  • Rejecting logins for a user after too many login failures in a certain period of time

  • Storing the login username and password in the Subject for future access

9.1.4. JAAS Configuration Entries

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

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

[Note]Note

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

9.1.5. Authorization

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

9.1.6. One Login, Multiple Destinations

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

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

9.2. Security Realm Configuration

This section reviews the process for configuring a standard or custom Geronimo security realm. There are two approaches: using the management console, and manually configuring and deploying a realm using GBeans and a Geronimo deployment plan. The console approach is the most convenient, but the manual approach has some additional flexibilitiy.

In either case, a security realm may use one or a series of login modules. Each of the standard Geronimo login modules requires certain configuration settings, described in Section 9.2.3, “Configuration Options for Standard Login Modules”. Third-party or custom login modules use the same general syntax to set login module options, but the specific options available will vary.

9.2.1. Easy Configuration and Deployment using the Console

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

[Tip]Tip

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

Figure 9.1. Console: List Security Realms

Console: List Security Realms

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

9.2.1.1. Step 1: Basic Settings

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

Figure 9.2. Console: Security Realm -- Basic Settings

Console: Security Realm -- Basic Settings

The two settings on this screen are:

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

Select Next to continue.

9.2.1.2. Step 2: Main Settings

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

Figure 9.3. Console: Security Realm -- Main Settings

Console: Security Realm -- Main Settings

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

Select Next to continue.

9.2.1.3. Setp 2: Advanced Settings

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

Figure 9.4. Console: Security Realm -- Advanced Settings

Console: Security Realm -- Advanced Settings

The options available on this screen are:

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

From here, there are three ways to proceed:

Test a Login

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

Skip Test and Deploy

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

Skip Test and Show Plan

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

9.2.1.4. Step 4: Test Login

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

Figure 9.5. Console: Security Realm -- Test Login

Console: Security Realm -- Test Login

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

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

Console: Security Realm -- Test Login Failure

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

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

Console: Security Realm -- Test Login Success

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

From here, there are four options:

Test Again

Run the test again with a different login.

Edit Realm

Adjust the configuration for the realm.

Show Plan

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

Deploy Realm

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

9.2.1.5. Creating Custom Security Realms

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

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

Console: Security Realm -- Create Custom Realm

This brings up the detailed realm edit screen:

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

Console: Security Realm -- Configure Custom Realm

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

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

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

From here, there are two options:

Show Plan

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

Deploy

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

9.2.1.6. Editing Existing Security Realms

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

Figure 9.10. Console: Security Realm -- Edit Realm

Console: Security Realm -- Edit Realm

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

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

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

From here, there are two options:

Show Plan

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

Save

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

9.2.1.7. Generate a Plan for an Application Scoped Realm

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

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

Figure 9.11. Console: Security Realm -- Show Plan

Console: Security Realm -- Show Plan

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

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

[Tip]Tip

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

9.2.1.7.1. Deploy via Command-Line Deploy Tool

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

java -jar GERONIMO_HOME/bin/deployer.jar deploy \
    GERONIMO_HOME/security-realm.xml
9.2.1.7.2. Deploy as Application-scoped Pool

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

Example 9.1. EAR Deployment Plan with Application Scoped Security Realm

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

9.2.2. Manual Security Realm Configuration

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

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

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

Example 9.2. Sample Security Realm Configuration

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

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

The important elements and attributes in this configuration block are:

gbean:name

A unique name used to identify this GBean. By convention, for security realms, this should be the same as the value of the realmName attribute.

gbean:class

The implementation class for the GBean. For a security realm, this should always be org.apache.geronimo.security.realm.GenericSecurityRealm.

attribute

Sets a property exposed by the GBean class. The name identifies which GBean attribute this block applies to, and the contents of this element are the value to set for that attribute. The realmName attribute sets a unique name for this security realm, and it should always be used and by convention should match the GBean name.

reference

Gives this GBean a reference to another one. The ServerInfo reference should always be configured exactly as shown here.

xml-reference

Provides a block of XML that the GBean will decode into additional settings or additional GBeans to load. The LoginModuleConfiguration XML block configures the LoginModules to use for this security realm. The contents of this element are described below. Note that it's important to specify a namespace for the nested elements, as the namespace is used to figure out how to decode the nested content. For a security realm, the contents should always use the namespace http://geronimo.apache.org/xml/ns/loginconfig (note the xmlns attribute on the topmost nested element, login-config).

The login module configuration looks like this:

Figure 9.12. Security: Login Module List

Security: Login Module List

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

login-module-ref

Refers to an existing login module, configured elsewhere.

login-module

Defines a new login module configuration

The reference to an existing login module looks like this:

Figure 9.13. Security: Existing Login Module Configuration

Security: Existing Login Module Configuration

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

login-module-ref:control-flag

Should be one of the defined JAAS control flag values (REQUIRED, REQUISITE, SUFFICIENT, or OPTIONAL). Refer to the JAAS API Documentation for a full definition of the login procedure for multiple modules based on their control flags. If there's only one login module for this realm then the value should typically be REQUIRED. For multiple modules, often the flags are set to REQUIRED or OPTIONAL. Note that REQUISITE and SUFFICIENT settings may prevent some login modules from executing in all cases (which would defeat an auditing login module, for example).

domain

The domain name portion of the GBean Name identifying the login module to map to. This should usually be geronimo.server, and if not specified, it defaults to the domain of the JSR-77 J2EEServer that was configured for the deployer GBean that's deploying the current module -- which is going to be geronimo.server unless you have substantially altered your default configuration.

server

The J2EE Server portion of the GBean Name identifying the login module to map to. This should usually be geronimo, and if not specified, it defaults to the name of the JSR-77 J2EEServer that was configured for the deployer GBean that's deploying the current module -- which is going to be geronimo unless you have substantially altered your default configuration.

application

The name of the application that the target login module is in. If the target login module was not deployed as part of a J2EE application, this would be null. If it was deployed as part of an EAR, this should be the applicationId specified for the EAR, or the configId if no applicationId was specified. If omitted, defaults to null or the current application depending on where the security realm is being configured.

module

The configId of the module that the target login module is in. If omitted, defaults to the current module.

type

Should always be set to LoginModule in order to identify a login module.

name

The name of the target login module.

The definition for a new login module looks like this:

Figure 9.14. Security: New Login Module Configuration

Security: New Login Module Configuration

The elements introduced here are:

login-module:control-flag

Should be one of the defined JAAS control flag values (REQUIRED, REQUISITE, SUFFICIENT, or OPTIONAL). Refer to the JAAS API Documentation for a full definition of the login procedure for multiple modules based on their control flags. If there's only one login module for this realm then the value should typically be REQUIRED. For multiple modules, often the flags are set to REQUIRED or OPTIONAL. Note that REQUISITE and SUFFICIENT settings may prevent some login modules from executing in all cases (which would defeat an auditing login module, for example).

login-module:server-side

If set to true, this login module should do all its processing on the server side. For example, if invoked by a client, the client's information would be passed to the server and the server would execute the authentication logic. This should almost always be set to true. The exception is for schemes where the client will retrieve its authorization information from the local operating system on the client side, in which case this attribute should be set to false.

login-domain-name

Each login module is named with a login domain name. This allows a security realm to use two instances of the same login module, configured with different login domain names. For example, a security realm might use two LDAP login modules to communicate with two different LDAP servers, and their principals would be indistinguishable without a unique login domain name. For simple scenarios, this should just be set to a unique value.

login-module-class

The fully-qualified class name of the class that implements javax.security.auth.spi.LoginModule. The standard login modules shipped with Geronimo are all in the package org.apache.geronimo.security.realm.providers and are:

  • PropertiesFileLoginModule

  • SQLLoginModule

  • CertificateChainLoginModule

  • GeronimoPasswordCredentialLoginModule

  • CertificatePropertiesFileLoginModule

option

Each LoginModule may have a set of options it takes. There may be any number of option elements, and each one configures a single option for the login module. The content of this element is the value to set for this option.

option:name

Identifies the option that this element is setting.

9.2.3. Configuration Options for Standard Login Modules

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

9.2.3.1. Properties File Login Module Configuration

A properties file login module reads users and groups from (plain text) properties files on the filesystem of the Geronimo server. The options for a properties file login module are:

Table 9.1. Properties File Realm Configuration

PropertyTypeDefinition
usersURIURIThe path to the user properties file, relative to the Geronimo directory.
groupURIURIThe path to the group properties file, relative to the Geronimo directory.
9.2.3.1.1. User File Contents

The user file contains one line for each user defined in the realm, with the format user=password.

Example 9.3. Properties File Realm: User File

user1=somepassword
another_user=my_password
this-user=secret

The usersURI configuration property points to the user file (relative to the Geronimo installation directory), so a value of var/security/users.properties would cause it to use geronimo/var/security/users.properties.

9.2.3.1.2. Group File Contents

The group file contains one line for each group defined in the realm, with the format group=member,member,member...

Example 9.4. Properties File Realm: Group File

administrators=user1,this-user
normalUsers=another_user

The groupURI configuration property points to the group file (relative to the Geronimo installation directory), so a value of var/security/groups.properties would cause it to use geronimo/var/security/groups.properties.

9.2.3.2. Database (SQL) Security Realm Configuration

A SQL login module reads users and groups from a database that's accessible to the Geronimo server. The options for a SQL file login module are:

Table 9.2. SQL Realm Configuration

PropertyTypeDefinition
dataSourceNameStringThe name of a JDBC data source deployed in Geronimo. If this is specified, then the JDBC Driver, URL, user, and password are unnecessary.
dataSourceApplicationStringIf a data source is specified and the data source was deployed as an application-scoped data source (e.g. within an EAR), then the application name must be specified here. If the data source was deployed through the console or as a standalone (server-scoped) data source, then this setting is not necessary.
jdbcURLStringThe JDBC URL used to connect to the database that holds the users and groups. This is used when a data source is not specified.
jdbcUserStringThe username used to connect to the database. This is used when a data source is not specified.
jdbcPasswordStringThe password used to connect to the database. This is used when a data source is not specified.
jdbcDriverClassThe fully-qualified class name of the JDBC driver to use to connect to the database. This is used when a data source is not specified.
userSelectStringA SQL query that returns the username and password for all users in the realm. Any prepared statment parameters (?'s) in the query will be set to the username for the current login attempt.
groupSelectStringA SQL query that returns the username and group name for each group that the user is a member of. Any prepared statment parameters (?'s) in the query will be set to the username for the current login attempt.

A sample user query might look like this. Note that the user name should be the first result column, and the password the second:

SELECT username, password FROM application_users
 WHERE username=?

A sample group query for a data model based on numeric IDs might look like this:

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

The same query for a data model based on names might be more straightforward:

SELECT user_name, group_name FROM user_groups
 WHERE user_name=?

Note in any case that the user name should be the first result column, and the group name the second.

9.2.3.3. Kerberos Login Module Configuration

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

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

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

  • clearPass

  • debug

  • doNotPrompt

  • keyTab

  • principal

  • refreshKrb5Config

  • storeKey

  • storePass

  • ticketCache

  • tryFirstPass

  • useFirstPass

  • useKeyTab

  • useTicketCache

These options are documented on Sun's site:

[Note]Note

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

9.3. Deploying a Security Realm

A security realm may be deployed directly to the server (available to any application), or as part of a single application. Both styles use the same configuration syntax discussed previously; the difference is which file you put that information in.

9.3.1. Server-Wide Security Realms

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

Example 9.5. Server-Wide Security Realm Deployment Plan

realm-plan.xml

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

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

</configuration>

The new elements here are:

configuration

The parent element for a deployment plan that contains only GBeans (as opposed to application modules)

configuration:xmlns

Should always be set to http://geronimo.apache.org/xml/ns/deployment

configuration:configId

A unique name for this configuration. This can be passed on the server command line to activate this security realm when the server starts.

configuration:parentId

Identifies the parent configuration for this security realm (the value specified here should match the configId for that module). This should generally be set to geronimo/j2ee-server/1.0/car, since that configuration has the code for all the security realm classes and interfaces on its ClassPath, though it might be set to another sub-configuration of that to set up a chain of dependent configurations.

9.3.1.1. Deploying A Server-Wide Security Realm

To deploy a security realm, you can use the deploy tool and pass it the security realm deployment plan:

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

That will install and start the realm (assuming the server is already running). For more information on the deploy tool, see Section 10.4, “The Deploy Tool”.

9.3.2. Application-Scoped Security Realms

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

Example 9.6. Application-Scoped Security Realm Deployment Plan

META-INF/geronimo-application.xml

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

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

</application>

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

9.3.2.1. Deploying an Application-Scoped Security Realm

To deploy the security realm, just deploy the application like normal, and the realm will be deployed and started when the application is deployed and started. No extra steps are necessary.

9.4. Enabling Security for Applications

Once the security realm is running, it's time to hook up individual applications and modules to use it. There are two steps to this; first, we must make sure that whenever you authenticate, you ultimately hit the new realm. Second, we must tell each application module which principals are allowed to access it.

9.4.1. Selecting the Realm to Authenticate Against

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

  1. A J2EE application client (running in the Geronimo client container) may authenticate in order to invoke a secure resource on the server (such as an EJB)

  2. A "plain Java" application client may authenticate in order to invoke a secure resource on the server

  3. A web client (a user with a browser) may authenticate using the web application authentication features (basic, form-based, etc.)

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

9.4.2. Mapping Roles to Principals

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

[Note]Note

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

Example 9.7. Role Mapping

A web application declares a single role like this:

WEB-INF/web.xml

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

In the Geronimo deployment plan, you map that to multiple principals in one of three ways. Normally, the simple mapping based on principal class (essentially, user or group) and principal name (the name of the user or group) will suffice. However, if you need to distinguish between principals in different login domains (that is, from different login modules in the same realm that happen to use the same principal classes), or between principals in different realms that use the same login domains, the more complex mapping types may be used.

WEB-INF/geronimo-web.xml using simple mapping

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

WEB-INF/geronimo-web.xml using login domain specific mapping

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

WEB-INF/geronimo-web.xml using realm-specific mapping

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

In all of these cases, the configuration selects the role NormalUser, and then picks two LDAP principals and two "Tribal" principals to count as members of that role. The principal class is specific to the security realm; in this case one realm uses the classes User and Group whereas the other realm uses the classes Clan and Chief.

Note that there's a Developers principal in both LDAP and Tribal login domains. One is a "User" while the other is a "Clan". Using the simple mapping style, only the principal class distinguishes the two Developers principals, and if two login domains used the same principal classes, the Developers principals from the two would be indistinguishable. Using the login domain specific mapping, you can also specify that the Developers principal must come from the login domain LDAPdomain or TRIBALdomain, though if two different realms used the same login domain names and the same principal classes then the Developers principals from each realm might still overlap. Finally, when using realm-specific mapping, the principals can be distinguished even in that case.

[Tip]Tip

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

9.5. Using a Custom Login Module

This section discuses implementing a custom login module. If one of the default login modules meets your needs, you can go with that and skip this section. On the other hand, if you have special requirements (such as a lockout after a certain number of failed logins) or if you need to authenticate against a security provider not covered by one of the default realms (such as a Single Sign-On product), then this is the section for you!

9.5.1. Implementing a Custom LoginModule

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

  1. Prompt for the user's login information (often a username and password, but sometimes a certificate, etc.) and validate whether that represents a valid account

  2. If the account is valid, populate a javax.security.auth.Subject with appropriate java.security.Principal values.

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

Example 9.8. Custom Realm Principal Classes

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

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

    public String getName() {
        return name;
    }

    public String toString() {
        return name;
    }

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

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

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

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

    public String getName() {
        return state;
    }

    public String toString() {
        return state;
    }

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

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

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

Example 9.9. Custom Realm LoginModule

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

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

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

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

    ...
}

9.5.2. Packaging and Deploying a Custom LoginModule

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

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

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

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

9.6. Configuring SSL/HTTPS

This section discusses configuring Geronimo to support HTTPS access to web applications. (Currently secure access to EJBs is not supported.) There are three parts to configuring SSL:

  1. Preparing a keystore with the server certificate, server key, and optionally the CA certificate.

  2. Configuring a HTTPS connector for Jetty (the web application container)

  3. Deploying and starting the HTTPS connector for Jetty

The following sections cover these steps in detail.

9.6.1. Keystore Configuration

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

  • It should contain only one private key, with a matching certificate

  • If client certs are enabled, and you choose not to trust the standard set of certificate authorities, all CA certificates in the keystore will be trusted

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

There are three possible approaches to server certificates:

  1. Use a self-signed certificate for testing

  2. Use a certificate signed by an internal certificate authority

  3. Use a certificate signed by a public certificate authority

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

[Note]Note

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

9.6.1.1. Preparing a Keystore with a Self-Signed Test Certificate

This is the easiest case, as you can do everything in one step:

  • Create a new keystore

  • Create a private key in the keystore

  • Create a self-signed certificate in the keystore that matches the private key

The command looks like this:

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

The arguments are:

-genkey

Indicates that we're generating a new key

-alias

The name to store the new key under. This is not terribly important as Geronimo will pick the only private key out of the keystore, but you'll need to use this if you want to inspect or alter the key using keytool.

-keyalg

The key algorithm, which may be DSA or RSA. RSA is preferred.

-validity

The number of days the key should be valid for

-keystore

The file name to save the keystore to (or the name of an existing keystore, to update an existing one)

When you run this command, you'll be prompted for:

  1. A password for the keystore (a new password for a new keystore, or the existing password for an existing keystore)

  2. Your first and last name. Important: you should actually enter the host name for the server here.

  3. Your organizational unit, such as a department within your company

  4. Your company

  5. A city

  6. A country code

  7. A password for the private key, which may be the same as or different than the password for the keystore.

When the command finishes, they keystore has been created with the private key and self-signed certificate. If you're not planning to use client certs, or if the standard certificate authorities are sufficient, you can skip ahead to Section 9.6.2, “HTTPS Connector Configuration”.

9.6.1.2. Preparing a Keystore with a Certificate Signed by a Certificate Authority

This case has three steps:

  1. Create a new key and keystore using a procedure just like in the previous section.

  2. Generate a certificate signing request (CSR) and have the certificate authority generate a signed certificate for you.

  3. Import the certificate authority's response into the keystore.

To generate a key, use the same command described in the previous section:

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

In this case, the alias is important as we'll need it for the next two steps.

To generate a CSR, use a command like this:

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

The arguments are:

-certreq

Indicates that we're generating a CSR

-alias

The alias of the private key, which should be the same as what you specified in the first command when you created the key

-file

The output file to write the CSR to

-keystore

The keystore file, which should be the same as what you specified in the first command.

When you run this command, you'll be prompted for the keystore password, and the private key password. The tool will then write the CSR to the specified file.

You should send the CSR to the certificate authority, and they should sign it and return a new certificate for the Geronimo server key. That process is outside of the scope of this book.

When you receive the CA response, make sure it is in PEM format (plain text, not binary) and copy it to the same location as the keystore.

If the CA is not one of the standard certificate authorities present in the common JDK CA cert file, you'll also need a copy of the CA certificate. Import that CA cert into the keystore with a command like this:

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

The arguments here are:

-import

Indicates that you're importing a certificate

-trustcacerts

Indicates that the certificate should be imported as a trusted CA cert. The CA cert must be trusted in order to successfully import a certificate signed by that CA.

-file

The file containing the CA certificate.

-alias

The name to store this CA under in the keystore. You can choose this freely, so long as it does not conflict with the private key alias.

-keystore

The keystore file, which should be the same as you've been using all along

You'll be prompted for the keystore password, and for whether you really want to trust the certificate you're importing.

Then use a command like this to import the certificate signed by the CA into the keystore:

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

The arguments here are:

-import

Indicates that you're importing a certificate

-file

The file containing the CA response (a signed copy of your server certificate)

-alias

The name of the private key in the keystore.

-keystore

The keystore file, which should be the same as you've been using all along

You'll be prompted for the keystore password and the private key password.

Once this command completes, the keystore should contain a private key, a server certificate signed by a CA, and if it is not a standard CA, a copy of the certificate identifying the CA.

9.6.1.3. Loading CA Certificates into the Keystore

If any additional certificate authorities should be trusted, particularly trusted to sign client certs for clients connecting to the server, you should import their CA certificates using a command like this:

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

The arguments here are:

-import

Indicates that you're importing a certificate

-trustcacerts

Indicates that the certificate should be imported as a trusted CA cert. The CA cert must be trusted in order to successfully import a certificate signed by that CA.

-file

The file containing the CA certificate.

-alias

The name to store this CA under in the keystore. You can choose this freely, so long as it does not conflict with any other entries in the keystore.

-keystore

The keystore file, which should be the same as you've been using all along

For each CA cert you import, you'll be prompted for the keystore password, and for whether you really want to trust the certificate you're importing.

9.6.2. HTTPS Connector Configuration

Now that the keystore is configured, you need to configure the server to listen for incoming HTTPS requests and use the key and certificate in the keystore.

In Geronimo, you need to explicitly configure the pathways used by browsers attempting to connect to the web container. In the case of Jetty, the default web container, these pathways are knows as connectors. The standard configuration includes a Jetty connector supporting HTTP on port 8080, as well as a HTTPS connector on port 8443. This section discusses configuring a custom connector supporting HTTPS, on a different port.

[Note]Note

Milestone 5 allows you to add, remove, and edit connectors (including HTTPS settings) through the web console, which is much easier than using the deployment plans described in this section. The console also supports both Tomcat and Jetty with the same interface.

Each Jetty connector is a GBean, so the process of configuring a Jetty connector involves configuring a GBean. The standard GBean deployment information for a Jetty HTTPS connector looks like this:

Example 9.10. Jetty HTTPS Connector Configuration

<gbean name="MyJettySSLConnector"
      class="org.apache.geronimo.jetty.connector.HTTPSConnector">
  <attribute name="port">8443</attribute>
  <attribute name="keystoreFileName">
    var/security/keystore
  </attribute>
  <attribute name="keystoreType">JKS</attribute>
  <attribute name="keystorePassword">secret</attribute>
  <attribute name="keyPassword">secret</attribute>
  <attribute name="clientAuthRequired">false</attribute>
  <attribute name="secureProtocol">TLS</attribute>
  <attribute name="maxThreads">50</attribute>
  <attribute name="minThreads">10</attribute>
  <reference name="JettyContainer">
    <module>geronimo/jetty/1.0/car</module>
    <name>JettyWebContainer</name>
  </reference>
  <reference name="ServerInfo">
    <module>geronimo/j2ee-system/1.0/car</module>
    <name>ServerInfo</name>
  </reference>
</gbean>

The GBean name should be adjusted to be unique, and the class should always appear exactly as above.

The configuration attributes and references for the HTTPS connector are:

port

The port that the HTTPS connector should listen on. The standard HTTPS port is 443, but in order for Geronimo to bind to port 443, it must be run with administrative privileges (which means as root, on a UNIX OS).

keystoreFileName

The path to the keystore configured in Section 9.6.1, “Keystore Configuration”. This should be relative to the Geronimo installation directory.

keystoreType

An optional attribute specifying the keystore type. For the procedure above to work, this should be left out or set to JKS.

keystorePassword

The password for the keystore itself, if any.

keyPassword

The password for the private key within the keystore, if any. Note that for maximum compatibility with Tomcat, the keyPassword and keystorePassword should be the same.

clientAuthRequired

If set to true, the clients must have a valid client certificate in order to connect. If set to false, any client can connect. The connection will still be secure in either case; it's only a question of whether the server can trust the clients.

secureProtocol

The variety of the SSL protocol to use. Normally this should be omitted or set to TLS, though certain JDKs (mainly from IBM) require a value of SSL to work correctly.

minThreads

The lower bound on the thread pool used to service connections coming in to this connector.

maxThreads

The upper bound on the thread pool used to service connections coming in to this connector.

JettyContainer

A reference to the master web container. This should normally appear exactly as shown in the example.

ServerInfo

A reference to the basic server information repository, used to locate files on the file system. This should normally appear exactly as shown in the example.

9.6.3. HTTPS Connector Deployment

HTTPS Connector GBeans are generally deployed as server-wide services.

[Note]Note

Technically, the GBean could be deployed with an application or module. However, it is not possible to configure a connector that only allows access to a single application or web module. Therefore an application-scoped deployment doesn't usually make sense -- while that application was running HTTPS access would be open for all web applications running in Geronimo, and when that application was stopped then HTTPS access would be disabled for all web applications.

The deployment plan for an HTTPS connector typically looks like this:

Example 9.11. Jetty HTTPS Connector Deployment Plan

ssl-plan.xml

<configuration
    xmlns="http://geronimo.apache.org/xml/ns/deployment"
    configId="SSL"
    parentId="geronimo/jetty/1.0/car">
  <!-- HTTPS Connector GBean goes here -->
</configuration>

The parentId for the HTTPS Connector should always be geronimo/jetty/1.0/car, since that is the configuration that deploys the main Jetty container. To complete this deployment plan, you should insert the gbean configuration information from Section 9.6.2, “HTTPS Connector Configuration” into the configuration element here.

Once the deployment plan has been saved, you can deploy it with a command like this:

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

That will install the configuration into the server and start it (assuming the server is running). Jetty will immediately begin listening for HTTPS connections on the designated port.

For testing purposes, you may also want to start the console (if it's not already running):

java -jar bin/deployer.jar start \
              geronimo/webconsole-jetty/1.0/car

Then you can visit the console in your browser using a URL like https://localhost:8443/console/

When you try this, you may run into a few issues:

  • If port 8443 doesn't work, you should use whichever port you configured in the HTTPS connector configuration

  • If you have not added the certificate authority that signed the server certificate to your browser, or if it's a self-signed test certificate, you may get a prompt that the signer is not trusted, asking you whether to accept the certificate for this session or permanently.

  • If you generated the certificate for a host name other than localhost, your browser may prompt you with a note that you're trying to connect to localhost but the certificate is for a different host name

J2EE Applications on Geronimo

Table of Contents

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

Chapter 10. Development & Deployment Overview [DRAFT (1.0)]

Generally speaking, two types of components can be developed for Geronimo: services and applications. Applications are J2EE applications or J2EE application modules, including:

  • Web applications

  • EJBs

  • J2EE connectors

  • J2EE application clients

  • J2EE enterprise applications

Services are other components that can be loaded into a Geronimo server, providing services to applications, or affecting the behavior of Geronimo itself. Some of the services discussed already include:

  • The ActiveMQ JMS Server

  • Geronimo security realms

  • The Geronimo logging system

While the overall process for developing and deploying services and applications is very similar, the specific configuration options vary. This chapter covers the common process and the related tools that ship with Geronimo. The rest of the chapters in this part of the book discuss the specific configuration options for each type of J2EE application module. Chapter 18, GBeans: Adding New Services to Geronimo [EMPTY] discusses the specific configuration process for services, as opposed to application components.

10.1. Component Development

Every application component must be developed and packaged according to the appropriate J2EE specifications. For example, the web application specification covers what base classes a Servlet should extend, the structure of a web application archive (with libraries under WEB-INF/lib, etc.), rules the web components should follow, and more. Any component that is developed, packaged, and configured according to those rules and guidelines can be deployed to Geronimo. Though the specifics are outside the scope of this book, there are many good references on J2EE application development.:

Developing services is described in more detail in Chapter 18, GBeans: Adding New Services to Geronimo [EMPTY]. As with application modules, there are certain rules that must be followed for the service to be a legitimate GBean, which is the type of component that Geronimo can deploy and run. Fortunately there are fewer rules here, and the configuration of a GBean is more open-ended compared to the J2EE deployment descriptors required for an application component. But this is a two-edged sword, as even two very similar or interchangeable GBeans may have very different implementation strategies and very different configuration strategies.

The bottom line is that in either case, you must develop a component according to the established rules. In some cases your IDE may be able to point out where you have deviated, but in others, any mistakes may not be revealed until you either deploy the component or actually attempt to start it. Generally any development errors can be reported when you first attempt to deploy a component, and it's usually the configuration problems that are not revealed until the component is actually started. For example, it's quite easy for the deployer to validate that a servlet actually implements javax.servlet.Servlet, but it's impossible to tell whether a database the servlet relies upon will be available when the servlet is eventually started.

10.2. J2EE Deployment Descriptors

One of the requirements for every J2EE application module is that it must include an XML-based deployment descriptor. The location differs for each module type, but the overall construction is similar.

Table 10.1. J2EE Deployment Descriptor File Names

Module TypeDeployment Descriptor File
Web ApplicationWEB-INF/web.xml
EJB JARMETA-INF/ejb-jar.xml
J2EE ConnectorMETA-INF/ra.xml
Client ApplicationMETA-INF/application-client.xml
Enterprise ApplicationMETA-INF/application.xml
[Note]Note

For application modules packaged in an EAR, the deployment descriptors for each module in the ear may be stored in the EAR but outside the module archives, by using the alt-dd element when each module is described in the application.xml deployment descriptor for the EAR.

In J2EE specifications up through version 1.3, these deployment descriptors were based on XML DTDs. Starting with J2EE 1.4, these deployment descriptors are based on XML Schemas. In general, there is little difference from the perspective of a developer -- either a schema or a DTD indicates which elements are allowed to go where in the deployment descriptor, and what they might contain. However, the file headers are slightly different, as the way an XML file indicates that it complies with a schema is different than the way it would indicate that it complied with a DTD: