Apache Geronimo Development and Deployment

Aaron Mulder



Chariot Solutions



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